Workspace Proxies
Workspace proxies provide low-latency experiences for geo-distributed teams.
Coder's networking does a best effort to make direct connections to a workspace.In situations where this is not possible, such as connections via the webterminal andweb IDEs,workspace proxies are able to reduce the amount of distance the network trafficneeds to travel.
A workspace proxy is a relay connection a developer can choose to use whenconnecting with their workspace over SSH, a workspace app, port forwarding, etc.Dashboard connections and API calls (e.g. the workspaces list) are not servedover workspace proxies.
Deploy a workspace proxy
Each workspace proxy should be a unique instance. At no point should twoworkspace proxy instances share the same authentication token. They only requireport 443 to be open and are expected to have network connectivity to the coderddashboard. Workspace proxiesdo not make any database connections.
Workspace proxies can be used in the browser by navigating to the userAccount -> Workspace Proxy
Requirements
- TheCoder CLI must be installed andauthenticated as a user with the Owner role.
Step 1: Create the proxy
Create the workspace proxy and make sure to save the returned authenticationtoken for said proxy. This is the token the workspace proxy will use toauthenticate back to primary coderd.
$ coder wsproxy create --name=newyork --display-name="USA East" --icon="/emojis/2194.png"Workspace Proxy "newyork" created successfully. Save this token, it will not be shown again.Token: 2fb6500b-bb47-4783-a0db-dedde895b865:05271b4ef9432bac14c02b3c56b5a2d7f05453718a1f85ba7e772c0a096c7175To verify it was created.
$ coder wsproxy lsNAME URL STATUS STATUSnewyork unregisteredStep 2: Deploy the proxy
Deploying the workspace proxy will also register the proxy with coderd and makethe workspace proxy usable. If the proxy deployment is successful,coder wsproxy ls will show anok status code:
$ coder wsproxy lsNAME URL STATUS STATUSprimary https://dev.coder.com okbrazil-saopaulo https://brazil.example.com okeurope-frankfurt https://europe.example.com oksydney https://sydney.example.com okOther Status codes:
unregistered: The workspace proxy was created, and not yet deployedunreachable: The workspace proxy was registered, but is not responding.Likely the proxy went offline.unhealthy: The workspace proxy is reachable, but has some issue that ispreventing the proxy from being used.coder wsproxy lsshould show the errormessage.ok: The workspace proxy is healthy and working properly!
Configuration
Workspace proxy configuration overlaps with a subset of the coderdconfiguration. To see the full list of configuration options:coder wsproxy server --help
# Proxy specific configuration. These are REQUIRED# Example: https://coderd.example.comCODER_PRIMARY_ACCESS_URL="https://<url_of_coderd_dashboard>"CODER_PROXY_SESSION_TOKEN="<session_token_from_proxy_create>"# Runtime variables for "coder start".CODER_HTTP_ADDRESS=0.0.0.0:80CODER_TLS_ADDRESS=0.0.0.0:443# Example: https://east.coderd.example.comCODER_ACCESS_URL="https://<access_url_of_proxy>"# Example: *.east.coderd.example.comCODER_WILDCARD_ACCESS_URL="*.<app_hostname_of_proxy>"CODER_TLS_ENABLE=trueCODER_TLS_CLIENT_AUTH=noneCODER_TLS_CERT_FILE="<cert_file_location>"CODER_TLS_KEY_FILE="<key_file_location>"# Additional configuration options are available.Running on Kubernetes
Make avalues-wsproxy.yaml with the workspace proxy configuration.
Notice theworkspaceProxy configuration which isfalse by default in theCoder Helm chart:
coder: env: - name: CODER_PRIMARY_ACCESS_URL value: "https://<url_of_coderd_dashboard>" - name: CODER_PROXY_SESSION_TOKEN value: "<session_token_from_proxy_create>" # Example: https://east.coderd.example.com - name: CODER_ACCESS_URL value: "https://<access_url_of_proxy>" # Example: *.east.coderd.example.com - name: CODER_WILDCARD_ACCESS_URL value: "*.<app_hostname_of_proxy>" tls: secretNames: - kubernetes-wsproxy-secret # enable workspace proxy workspaceProxy: trueUsing Helm, install the workspace proxy chart
helm install coder coder-v2/coder --namespace <your workspace proxy namespace> -f ./values-wsproxy.yamlTest that the workspace proxy is reachable withcurl -vvv. If for some reason,the Coder dashboard still shows the workspace proxy isUNHEALTHY, scale downand up the deployment's replicas.
Running on a VM
# Set configuration options via environment variables, a config file, or cmd flagscoder wsproxy serverRunning as a system service
If you've installed Coder via asystem package, youcan configure the workspace proxy by settings in/etc/coder.d/coder-workspace-proxy.env
To run workspace proxy as a system service on the host:
# Use systemd to start workspace proxy now and on rebootsudo systemctl enable --now coder-workspace-proxy# View the logs to ensure a successful startjournalctl -u coder-workspace-proxy.service -bTo restart workspace proxy after applying system changes:
sudo systemctl restart coder-workspace-proxyRunning in Docker
Modify the default entrypoint to run a workspace proxy server instead of aregular Coder server.
Docker Compose
Change the providedcompose.ymlfile to include a custom entrypoint:
image: ghcr.io/coder/coder:${CODER_VERSION:-latest}+ entrypoint: /opt/coder wsproxy serverDocker run
docker run --rm -it --entrypoint /opt/coder ghcr.io/coder/coder:latest wsproxy serverCustom Dockerfile
FROM ghcr.io/coder/coder:latestENTRYPOINT ["/opt/coder", "wsproxy", "server"]Selecting a proxy
Users can select a workspace proxy at the top-right of the browser-based Coderdashboard. Workspace proxy preferences are cached by the web browser. If a proxygoes offline, the session will fall back to the primary proxy. This could takeup to 60 seconds.
Multiple workspace proxies
When multiple workspace proxies are deployed:
- The browser measures latency to each available proxy independently.
- Users can select their preferred proxy from the dashboard.
- The system can automatically select the lowest-latency proxy.
- The dashboard latency indicator shows latency to the currently selected proxy.
Observability
Coder workspace proxy exports metrics via the HTTP endpoint, which can beenabled using either the environment variableCODER_PROMETHEUS_ENABLE or theflag--prometheus-enable.
The Prometheus endpoint address ishttp://localhost:2112/ by default. You canuse either the environment variableCODER_PROMETHEUS_ADDRESS or the flag--prometheus-address <network-interface>:<port> to select a different listenaddress.