|
| 1 | +--- |
| 2 | +title: Proxies |
| 3 | +description: Learn how to configure forward and reverse proxies for Coder. |
| 4 | +--- |
| 5 | + |
| 6 | +This article walks you through configuring proxies for Coder. |
| 7 | + |
| 8 | +If your Coder installation accesses the internet through a forward proxy, |
| 9 | +configure a [forward proxy](#forward-proxies). |
| 10 | + |
| 11 | +If you have a reverse proxy in front of Coder, such as an ingress controller |
| 12 | +internal to the cluster, then configure a [reverse proxy](#reverse-proxies). |
| 13 | + |
| 14 | +## Forward proxies |
| 15 | + |
| 16 | +Coder supports proxies for outbound HTTP and HTTPS connections once you've |
| 17 | +configured the `coderd.proxy.http` and `coderd.proxy.https` settings in the |
| 18 | +[Helm chart](../admin/helm-charts.md). These settings correspond to the standard |
| 19 | +`http_proxy` and `https_proxy` environment variables, respectively. |
| 20 | + |
| 21 | +If the proxy URL does not include a scheme, Coder treats it as an HTTP proxy by |
| 22 | +default. Coder also supports proxies using the HTTPS and SOCKS 5 protocols. As a |
| 23 | +special case, Coder will always establish connections to `localhost` directly, |
| 24 | +regardless of the `coderd.proxy.exempt` setting. For additional proxy setting |
| 25 | +information, see the [documentation for ProxyFromEnvironment]. |
| 26 | + |
| 27 | +[documentation for proxyfromenvironment]: |
| 28 | + https://pkg.go.dev/net/http#ProxyFromEnvironment |
| 29 | + |
| 30 | +For an HTTP proxy with address `http://localhost:3128`, use the setting: |
| 31 | + |
| 32 | +```yaml |
| 33 | +coderd: |
| 34 | + proxy: |
| 35 | + # If the scheme is omitted, Coder will default to `http` |
| 36 | + http: localhost:3128 |
| 37 | +``` |
| 38 | +
|
| 39 | +For an HTTPS proxy with address `https://localhost`, include the scheme: |
| 40 | + |
| 41 | +```yaml |
| 42 | +coderd: |
| 43 | + proxy: |
| 44 | + # If the port is omitted, Coder will use the default port corresponding to |
| 45 | + # the selected scheme (443 for https) |
| 46 | + http: https://localhost |
| 47 | +``` |
| 48 | + |
| 49 | +For a [SOCKS 5 proxy](https://en.wikipedia.org/wiki/SOCKS) on listening on port |
| 50 | +1080, use the setting: |
| 51 | + |
| 52 | +```yaml |
| 53 | +coderd: |
| 54 | + proxy: |
| 55 | + http: socks5://10.10.10.10:1080 |
| 56 | +``` |
| 57 | + |
| 58 | +If you specify a proxy for outbound HTTP connections, and you do not specify a |
| 59 | +proxy for outgoing HTTPS connections, then Coder will proxy requests to HTTPS |
| 60 | +endpoints using the HTTP proxy. The previous examples will proxy all requests |
| 61 | +through the defined proxy, regardless of protocol (HTTP or HTTPS). |
| 62 | + |
| 63 | +To configure a different proxy for use with outbound HTTPS connections, you can |
| 64 | +specify the same proxy types (`http`, `https`, `socks5`) using the |
| 65 | +`coderd.proxy.https` key: |
| 66 | + |
| 67 | +```yaml |
| 68 | +coderd: |
| 69 | + proxy: |
| 70 | + # Use an HTTP proxy on port 3128 for outbound HTTP connections, and an |
| 71 | + # HTTP proxy on port 8080 for outbound HTTPS connections. |
| 72 | + http: http://localhost:3128 |
| 73 | + https: http://localhost:8080 |
| 74 | +``` |
| 75 | + |
| 76 | +For hosts that must connect directly, rather than using the proxy, define the |
| 77 | +`coderd.proxy.exempt` setting with a comma-separated list of hosts and |
| 78 | +subdomains: |
| 79 | + |
| 80 | +```yaml |
| 81 | +coderd: |
| 82 | + proxy: |
| 83 | + # Coder will establish connections to cluster.local or example.com, or |
| 84 | + # their subdomains directly, rather than using the proxy settings. |
| 85 | + exempt: "cluster.local,example.com" |
| 86 | +``` |
| 87 | + |
| 88 | +## Reverse proxies |
| 89 | + |
| 90 | +If you have a reverse proxy in front of Coder, which is the case if you're using |
| 91 | +an ingress controller, Coder receives connections originating from the proxy. |
| 92 | +For auditing, logging, and other features to correctly recognize the connecting |
| 93 | +user's IP address information, you will need to configure the |
| 94 | +`coderd.reverseProxy` setting. |
| 95 | + |
| 96 | +> By default, Coder will ignore `X-Forwarded-For` and similar headers and remove |
| 97 | +> them from proxied connections to [Dev URL services]. This prevents clients |
| 98 | +> from spoofing their originating IP addresses. |
| 99 | + |
| 100 | +[dev url services]: ../../workspaces/devurls.md |
| 101 | + |
| 102 | +Specify a list of trusted origin addresses (those of the reverse proxy) in CIDR |
| 103 | +format as follows: |
| 104 | + |
| 105 | +```yaml |
| 106 | +coderd: |
| 107 | + reverseProxy: |
| 108 | + # These settings will treat inbound connections originating from |
| 109 | + # localhost (127.0.0.1/8) and the RFC 1918 Class A network (10.0.0.0/8) |
| 110 | + # as trusted proxies, and will consider the configured headers. |
| 111 | + trustedOrigins: |
| 112 | + - 127.0.0.1/8 |
| 113 | + - 10.0.0.0/8 |
| 114 | +
|
| 115 | + headers: |
| 116 | + - X-Forwarded-For |
| 117 | +``` |
0 commit comments