Skip to content

Commit 3b099fd

Browse files
stirbystirby
committed
added workspace proxies from lost branch
1 parent 66ff05e commit 3b099fd

File tree

2 files changed

+219
-0
lines changed

2 files changed

+219
-0
lines changed

‎docs/admin/networking/workspace-proxies.md

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
# Workspace Proxies
2+
3+
Workspace proxies provide low-latency experiences for geo-distributed teams.
4+
5+
Coder's networking does a best effort to make direct connections to a workspace.
6+
In situations where this is not possible, such as connections via the web
7+
terminal and [web IDEs](../../user-guides/workspace-access/README.md#web-ides), workspace proxies are able to
8+
reduce the amount of distance the network traffic needs to travel.
9+
10+
A workspace proxy is a relay connection a developer can choose to use when
11+
connecting with their workspace over SSH, a workspace app, port forwarding, etc.
12+
Dashboard connections and API calls (e.g. the workspaces list) are not served
13+
over workspace proxies.
14+
15+
![ProxyDiagram](../../images/workspaceproxy/proxydiagram.png)
16+
17+
# Deploy a workspace proxy
18+
19+
Each workspace proxy should be a unique instance. At no point should 2 workspace
20+
proxy instances share the same authentication token. They only require port 443
21+
to be open and are expected to have network connectivity to the coderd
22+
dashboard. Workspace proxies **do not** make any database connections.
23+
24+
Workspace proxies can be used in the browser by navigating to the user
25+
`Account -> Workspace Proxy`
26+
27+
## Requirements
28+
29+
- The [Coder CLI](../../reference/cli/README.md) must be installed and authenticated as a user with
30+
the Owner role.
31+
32+
## Step 1: Create the proxy
33+
34+
Create the workspace proxy and make sure to save the returned authentication
35+
token for said proxy. This is the token the workspace proxy will use to
36+
authenticate back to primary coderd.
37+
38+
```bash
39+
$ coder wsproxy create --name=newyork --display-name="USA East" --icon="/emojis/2194.png"
40+
Workspace Proxy "newyork" created successfully. Save this token, it will not be shown again.
41+
Token: 2fb6500b-bb47-4783-a0db-dedde895b865:05271b4ef9432bac14c02b3c56b5a2d7f05453718a1f85ba7e772c0a096c7175
42+
```
43+
44+
To verify it was created.
45+
46+
```bash
47+
$ coder wsproxy ls
48+
NAME URL STATUS STATUS
49+
newyork unregistered
50+
```
51+
52+
## Step 2: Deploy the proxy
53+
54+
Deploying the workspace proxy will also register the proxy with coderd and make
55+
the workspace proxy usable. If the proxy deployment is successful,
56+
`coder wsproxy ls` will show an `ok` status code:
57+
58+
```
59+
$ coder wsproxy ls
60+
NAME URL STATUS STATUS
61+
brazil-saopaulo https://brazil.example.com ok
62+
europe-frankfurt https://europe.example.com ok
63+
sydney https://sydney.example.com ok
64+
```
65+
66+
Other Status codes:
67+
68+
- `unregistered` : The workspace proxy was created, and not yet deployed
69+
- `unreachable` : The workspace proxy was registered, but is not responding.
70+
Likely the proxy went offline.
71+
- `unhealthy` : The workspace proxy is reachable, but has some issue that is
72+
preventing the proxy from being used. `coder wsproxy ls` should show the error
73+
message.
74+
- `ok` : The workspace proxy is healthy and working properly!
75+
76+
### Configuration
77+
78+
Workspace proxy configuration overlaps with a subset of the coderd
79+
configuration. To see the full list of configuration options:
80+
`coder wsproxy server --help`
81+
82+
```bash
83+
# Proxy specific configuration. These are REQUIRED
84+
# Example: https://coderd.example.com
85+
CODER_PRIMARY_ACCESS_URL="https://<url_of_coderd_dashboard>"
86+
CODER_PROXY_SESSION_TOKEN="<session_token_from_proxy_create>"
87+
88+
# Runtime variables for "coder start".
89+
CODER_HTTP_ADDRESS=0.0.0.0:80
90+
CODER_TLS_ADDRESS=0.0.0.0:443
91+
# Example: https://east.coderd.example.com
92+
CODER_ACCESS_URL="https://<access_url_of_proxy>"
93+
# Example: *.east.coderd.example.com
94+
CODER_WILDCARD_ACCESS_URL="*.<app_hostname_of_proxy>"
95+
96+
CODER_TLS_ENABLE=true
97+
CODER_TLS_CLIENT_AUTH=none
98+
CODER_TLS_CERT_FILE="<cert_file_location>"
99+
CODER_TLS_KEY_FILE="<key_file_location>"
100+
101+
# Additional configuration options are available.
102+
```
103+
104+
### Running on Kubernetes
105+
106+
Make a `values-wsproxy.yaml` with the workspace proxy configuration:
107+
108+
> Notice the `workspaceProxy` configuration which is `false` by default in the
109+
> coder Helm chart.
110+
111+
```yaml
112+
coder:
113+
env:
114+
- name: CODER_PRIMARY_ACCESS_URL
115+
value: "https://<url_of_coderd_dashboard>"
116+
- name: CODER_PROXY_SESSION_TOKEN
117+
value: "<session_token_from_proxy_create>"
118+
# Example: https://east.coderd.example.com
119+
- name: CODER_ACCESS_URL
120+
value: "https://<access_url_of_proxy>"
121+
# Example: *.east.coderd.example.com
122+
- name: CODER_WILDCARD_ACCESS_URL
123+
value: "*.<app_hostname_of_proxy>"
124+
125+
tls:
126+
secretNames:
127+
- kubernetes-wsproxy-secret
128+
129+
# enable workspace proxy
130+
workspaceProxy: true
131+
```
132+
133+
Using Helm, install the workspace proxy chart
134+
135+
```bash
136+
helm install coder coder-v2/coder --namespace <your workspace proxy namespace> -f ./values-wsproxy.yaml
137+
```
138+
139+
Test that the workspace proxy is reachable with `curl -vvv`. If for some reason,
140+
the Coder dashboard still shows the workspace proxy is `UNHEALTHY`, scale down
141+
and up the deployment's replicas.
142+
143+
### Running on a VM
144+
145+
```bash
146+
# Set configuration options via environment variables, a config file, or cmd flags
147+
coder wsproxy server
148+
```
149+
150+
### Running as a system service
151+
152+
If you've installed Coder via a [system package](../../install/README.md), you can
153+
configure the workspace proxy by settings in
154+
`/etc/coder.d/coder-workspace-proxy.env`
155+
156+
To run workspace proxy as a system service on the host:
157+
158+
```bash
159+
# Use systemd to start workspace proxy now and on reboot
160+
sudo systemctl enable --now coder-workspace-proxy
161+
162+
# View the logs to ensure a successful start
163+
journalctl -u coder-workspace-proxy.service -b
164+
```
165+
166+
To restart workspace proxy after applying system changes:
167+
168+
```shell
169+
sudo systemctl restart coder-workspace-proxy
170+
```
171+
172+
### Running in Docker
173+
174+
Modify the default entrypoint to run a workspace proxy server instead of a
175+
regular Coder server.
176+
177+
#### Docker Compose
178+
179+
Change the provided
180+
[`docker-compose.yml`](https://github.com/coder/coder/blob/main/docker-compose.yaml)
181+
file to include a custom entrypoint:
182+
183+
```diff
184+
image: ghcr.io/coder/coder:${CODER_VERSION:-latest}
185+
+ entrypoint: /opt/coder wsproxy server
186+
```
187+
188+
#### Docker run
189+
190+
```bash
191+
docker run --rm -it --entrypoint /opt/coder ghcr.io/coder/coder:latest wsproxy server
192+
```
193+
194+
#### Custom Dockerfile
195+
196+
```Dockerfile
197+
FROM ghcr.io/coder/coder:latest
198+
ENTRYPOINT ["/opt/coder", "wsproxy", "server"]
199+
```
200+
201+
### Selecting a proxy
202+
203+
Users can select a workspace proxy at the top-right of the browser-based Coder
204+
dashboard. Workspace proxy preferences are cached by the web browser. If a proxy
205+
goes offline, the session will fall back to the primary proxy. This could take
206+
up to 60 seconds.
207+
208+
![Workspace proxy picker](../../images/workspaceproxy/ws-proxy-picker.png)
209+
210+
## Observability
211+
212+
Coder workspace proxy exports metrics via the HTTP endpoint, which can be
213+
enabled using either the environment variable `CODER_PROMETHEUS_ENABLE` or the
214+
flag `--prometheus-enable`.
215+
216+
The Prometheus endpoint address is `http://localhost:2112/` by default. You can
217+
use either the environment variable `CODER_PROMETHEUS_ADDRESS` or the flag
218+
`--prometheus-address <network-interface>:<port>` to select a different listen
219+
address.

‎docs/images/workspaceproxy/ws-proxy-picker.png

326 KB
Loading

0 commit comments

Comments
 (0)