Skip to content

Commit 6d24f7c

Browse files
EmyrkEmyrk
authored
feat: Add documentation for workspace proxy creation (#7377)
* feat: Add documentation for workspace proxy creation
1 parent 8909110 commit 6d24f7c

File tree

3 files changed

+107
-0
lines changed

3 files changed

+107
-0
lines changed

‎docs/admin/workspace-proxies.md

+100
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Workspace Proxies
2+
3+
> Workspace proxies are in an [experimental state](../contributing/feature-stages.md#experimental-features) and the behavior is subject to change. Use [GitHub issues](https://github.com/coder/coder) to leave feedback. This experiment must be specifically enabled with the `--experiments="moons"` option on both coderd and the workspace proxy.
4+
5+
Workspace proxies provide low-latency experiences for geo-distributed teams.
6+
7+
Coder's networking does a best effort to make direct connections to a workspace. In situations where this is not possible, such as [dashboard connections](../networking/README.md#dashboard-connections), workspace proxies are able to reduce the amount of distance the network traffic needs to travel.
8+
9+
A workspace proxy is a relay connection a developer can choose to use when connecting with their workspace over ssh, a workspace app, port forwarding, etc.
10+
11+
<!-- TODO: Might want to modify this diagram? -->
12+
13+
![ProxyDiagram](../images/workspaceproxy/proxydiagram.png)
14+
15+
# Deploy a workspace proxy
16+
17+
Each workspace proxy should be a unique instance. At no point should 2 workspace proxy instances share the same authentication token. They only require port 443 to be open and are expected to have network connectivity to the coderd dashboard. Workspace proxies **do not** make any database connections.
18+
19+
Workspace proxies can be used in the browser by navigating to the user `Account -> Workspace Proxy`
20+
21+
## Requirements
22+
23+
- The [Coder CLI](../cli.md) must be installed and authenticated as a user with the Owner role.
24+
25+
## Step 1: Create the proxy
26+
27+
Create the workspace proxy and make sure to save the returned authentication token for said proxy. This is the token the workspace proxy will use to authenticate back to primary coderd.
28+
29+
```bash
30+
$ coder proxy create --name=newyork --display-name="USA East" --icon="/emojis/2194.png"
31+
Workspace Proxy "newyork" created successfully. Save this token, it will not be shown again.
32+
Token: 2fb6500b-bb47-4783-a0db-dedde895b865:05271b4ef9432bac14c02b3c56b5a2d7f05453718a1f85ba7e772c0a096c7175
33+
```
34+
35+
To verify it was created.
36+
37+
```bash
38+
$ coder proxy ls
39+
NAME URL STATUS STATUS
40+
newyork unregistered
41+
```
42+
43+
## Step 2: Deploy the proxy
44+
45+
Deploying the workspace proxy will also register the proxy with coderd and make the workspace proxy usable. If the proxy deployment is successful, `coder proxy ls` will show an `ok` status code:
46+
47+
```
48+
$ coder proxy lsPM
49+
NAME URL STATUS STATUS
50+
brazil-saopaulo https://brazil.example.com ok
51+
europe-frankfurt https://europe.example.com ok
52+
sydney https://sydney.example.com ok
53+
```
54+
55+
Other Status codes:
56+
57+
- `unregistered` : The workspace proxy was created, and not yet deployed
58+
- `unreachable` : The workspace proxy was registered, but is not responding. Likely the proxy went offline.
59+
- `unhealthy` : The workspace proxy is reachable, but has some issue that is preventing the proxy from being used. `coder proxy ls` should show the error message.
60+
- `ok` : The workspace proxy is healthy and working properly!
61+
62+
### Configuration
63+
64+
<!--
65+
I am not sure the best way to present this.
66+
Ideally in the future we can auto sync some of the settings with coderd.
67+
-->
68+
69+
Workspace proxy configuration overlaps with a subset of the coderd configuration. To see the full list of configuration options: `coder proxy server --help`
70+
71+
```bash
72+
# Proxy specific configuration. These are REQUIRED
73+
# Example: https://coderd.example.com
74+
CODER_PRIMARY_ACCESS_URL="https://<url_of_coderd_dashboard>"
75+
CODER_PROXY_SESSION_TOKEN="<session_token_from_proxy_create>"
76+
77+
# Runtime variables for "coder start".
78+
CODER_HTTP_ADDRESS=0.0.0.0:80
79+
CODER_TLS_ADDRESS=0.0.0.0:443
80+
# Example: https://east.coderd.example.com
81+
CODER_ACCESS_URL="https://<access_url_of_proxy>"
82+
# Example: *.east.coderd.example.com
83+
CODER_WILDCARD_ACCESS_URL="*.<app_hostname_of_proxy>"
84+
85+
CODER_TLS_ENABLE=true
86+
CODER_TLS_CLIENT_AUTH=none
87+
CODER_TLS_CERT_FILE="<cert_file_location>"
88+
CODER_TLS_KEY_FILE="<key_file_location>"
89+
90+
# Additional configuration options are available.
91+
```
92+
93+
### Running on a VM
94+
95+
```bash
96+
# Set configuration options via environment variables, a config file, or cmd flags
97+
coder proxy server
98+
```
99+
100+
<!-- Additional run options? -->

‎docs/images/workspaceproxy/proxydiagram.png

904 KB
Loading

‎docs/manifest.json

+7
Original file line numberDiff line numberDiff line change
@@ -307,6 +307,13 @@
307307
"icon_path": "./images/icons/queue.svg",
308308
"state": "enterprise"
309309
},
310+
{
311+
"title": "External Workspace Proxies",
312+
"description": "Run geo distributed workspace proxies",
313+
"path": "./admin/workspace-proxies.md",
314+
"icon_path": "./images/icons/networking.svg",
315+
"state": "enterprise"
316+
},
310317
{
311318
"title": "Audit Logs",
312319
"description": "Learn how to use Audit Logs in your Coder deployment",

0 commit comments

Comments
 (0)