Skip to content

Commit 91cbd67

Browse files
authored
feat: document proxy settings (coder#830)
1 parent 08ca860 commit 91cbd67

File tree

3 files changed

+129
-2
lines changed

3 files changed

+129
-2
lines changed

guides/deployments/proxy.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
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+
```

manifest.json

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -436,14 +436,17 @@
436436
{
437437
"path": "./guides/deployments/code-server.md"
438438
},
439+
{
440+
"path": "./guides/deployments/podman.md"
441+
},
439442
{
440443
"path": "./guides/deployments/postgres.md"
441444
},
442445
{
443-
"path": "./guides/deployments/keycloak.md"
446+
"path": "./guides/deployments/proxy.md"
444447
},
445448
{
446-
"path": "./guides/deployments/podman.md"
449+
"path": "./guides/deployments/keycloak.md"
447450
},
448451
{
449452
"path": "./guides/deployments/teardown.md"

setup/air-gapped/index.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,13 +126,20 @@ platform images are hosted in Coder's Docker Hub repo.
126126
proxy:
127127
http: http://proxy.internal:8888
128128
exempt: cluster.local
129+
129130
postgres:
130131
default:
131132
image: my-registry.com/coderenvs/timescale:<version>
133+
132134
envbox:
133135
image: my-registry.com/coderenvs/envbox:<version>
134136
```
135137
138+
See [configuring forward and reverse proxies] for additional information
139+
about Coder's support for network proxies.
140+
141+
[configuring forward and reverse proxies]: ../../guides/deployments/proxy.md
142+
136143
1. Once all of the resources are in your air-gapped network, run the following
137144
to deploy Coder to your Kubernetes cluster:
138145

0 commit comments

Comments
 (0)