From 56cd373b62323a43fbd616cee2f89563e97f88b4 Mon Sep 17 00:00:00 2001 From: Jonathan Yu Date: Fri, 4 Feb 2022 23:09:52 +0000 Subject: [PATCH 1/8] feat: document proxy settings Document use of the new Helm chart settings for forward and reverse proxies. --- guides/deployments/proxy.md | 97 +++++++++++++++++++++++++++++++++++++ manifest.json | 3 ++ setup/air-gapped/index.md | 8 +++ 3 files changed, 108 insertions(+) create mode 100644 guides/deployments/proxy.md diff --git a/guides/deployments/proxy.md b/guides/deployments/proxy.md new file mode 100644 index 000000000..a7532dd7b --- /dev/null +++ b/guides/deployments/proxy.md @@ -0,0 +1,97 @@ +--- +title: Proxies +description: Learn how to configure forward and reverse proxies for Coder. +--- + +If your Coder installation will access the Internet through a forward proxy, see +the reference for configuring [Forward proxies](#forward-proxies). + +If you have a reverse proxy in front of Coder, such as an Ingress Controller +internal to the cluster, then see the reference for configuring +[Reverse proxies](#reverse-proxies). + +## Forward proxies + +Coder supports proxies for outbound HTTP and HTTPS connections by configuring +the `coderd.proxy.http` and `coderd.proxy.https` settings in the Helm chart, +which correspond to the standard `http_proxy` and `https_proxy` environment +variables, respectively. + +If the proxy URL does not include a scheme, Coder will default to treating it as +an HTTP proxy. It is also possible to connect to the proxy using HTTPS or SOCKS5 +protocols. + +For an HTTP proxy with address `http://localhost:3128`, use the setting: + +```yaml +coderd: + proxy: + http: localhost:3128 +``` + +For an HTTPS proxy with address `https://localhost:3128`, include the scheme: + +```yaml +coderd: + proxy: + http: https://localhost +``` + +For a [SOCKS 5 proxy](https://en.wikipedia.org/wiki/SOCKS) with on port 1080, +use the setting: + +```yaml +coderd: + proxy: + http: socks5://10.10.10.10:1080 +``` + +If you specify a proxy for outbound HTTP connections and do not specify a proxy +for outgoing HTTPS connections, then Coder will proxy requests to HTTPS +endpoints using the HTTP proxy. The previous examples will proxy all requests, +regardless of protocol (HTTP or HTTPS), through the defined proxy. + +To configure a different proxy to use for outbound HTTPS connections, you may +specify the same proxy types (`http`, `https`, `socks5`) using the +`coderd.proxy.https` key. + +For hosts that must connect directly, rather than using the proxy, define the +`exempt` setting with a comma-separated list of hosts and subdomains: + +```yaml +coderd: + proxy: + # Coder will establish connections to cluster.local or example.com, or + # their subdomains, directly, rather than using the proxy settings. + exempt: "cluster.local,example.com" +``` + +## Reverse proxies + +If you have a reverse proxy in front of Coder, as will be the case when you are +using an Ingress Controller, Coder will receive connections originating from the +proxy. In order for auditing, logging, and other features to associate the +connecting user's IP address information correctly, you will need to configure +the `coderd.reverseProxy` setting. + +By default, to prevent clients from spoofing their originating IP addresses +using the `X-Forwarded-For` or similar headers, Coder will ignore all such +headers and remove them from proxied connections to +[Dev URL services](../../devurls.md). + +Specify a list of trusted origin addresses (those of the reverse proxy) in CIDR +format as follows: + +```yaml +coderd: + reverseProxy: + # These settings will treat inbound connections originating from + # localhost (127.0.0.1/8) and the RFC 1918 Class A network (10.0.0.0/8) + # as trusted proxies, and will consider the configured headers. + trustedOrigins: + - 127.0.0.1/8 + - 10.0.0.0/8 + + headers: + - X-Forwarded-For +``` diff --git a/manifest.json b/manifest.json index 872ae7d15..e6334da73 100644 --- a/manifest.json +++ b/manifest.json @@ -440,6 +440,9 @@ { "path": "./guides/deployments/podman.md" }, + { + "path": "./guides/deployments/proxy.md" + }, { "path": "./guides/deployments/teardown.md" }, diff --git a/setup/air-gapped/index.md b/setup/air-gapped/index.md index a89a40ac1..5fe9ca2ce 100644 --- a/setup/air-gapped/index.md +++ b/setup/air-gapped/index.md @@ -126,13 +126,21 @@ platform images are hosted in Coder's Docker Hub repo. proxy: http: http://proxy.internal:8888 exempt: cluster.local + postgres: default: image: my-registry.com/coderenvs/timescale: + envbox: image: my-registry.com/coderenvs/envbox: ``` + See [configuring forward and reverse proxies] for additional information + about Coder's support for network proxies. + + [configuring forward and reverse proxies]: + ../../guides/admin/deployments/proxy.md + 1. Once all of the resources are in your air-gapped network, run the following to deploy Coder to your Kubernetes cluster: From 6536e366d834216d42cbd007a3ec9feba6c30e50 Mon Sep 17 00:00:00 2001 From: Jonathan Yu Date: Fri, 4 Feb 2022 23:22:08 +0000 Subject: [PATCH 2/8] update inks --- guides/deployments/proxy.md | 2 +- setup/air-gapped/index.md | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/guides/deployments/proxy.md b/guides/deployments/proxy.md index a7532dd7b..58ba3abe6 100644 --- a/guides/deployments/proxy.md +++ b/guides/deployments/proxy.md @@ -77,7 +77,7 @@ the `coderd.reverseProxy` setting. By default, to prevent clients from spoofing their originating IP addresses using the `X-Forwarded-For` or similar headers, Coder will ignore all such headers and remove them from proxied connections to -[Dev URL services](../../devurls.md). +[Dev URL services](../../workspaces/devurls.md). Specify a list of trusted origin addresses (those of the reverse proxy) in CIDR format as follows: diff --git a/setup/air-gapped/index.md b/setup/air-gapped/index.md index 5fe9ca2ce..f1cd510aa 100644 --- a/setup/air-gapped/index.md +++ b/setup/air-gapped/index.md @@ -138,8 +138,7 @@ platform images are hosted in Coder's Docker Hub repo. See [configuring forward and reverse proxies] for additional information about Coder's support for network proxies. - [configuring forward and reverse proxies]: - ../../guides/admin/deployments/proxy.md + [configuring forward and reverse proxies]: ../../guides/deployments/proxy.md 1. Once all of the resources are in your air-gapped network, run the following to deploy Coder to your Kubernetes cluster: From 31989a3484ad2bd2accf299a5a96115e253864b4 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 8 Feb 2022 10:34:02 -0600 Subject: [PATCH 3/8] edit text --- guides/deployments/proxy.md | 52 ++++++++++++++++++------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/guides/deployments/proxy.md b/guides/deployments/proxy.md index 58ba3abe6..1ed44090e 100644 --- a/guides/deployments/proxy.md +++ b/guides/deployments/proxy.md @@ -3,22 +3,23 @@ title: Proxies description: Learn how to configure forward and reverse proxies for Coder. --- -If your Coder installation will access the Internet through a forward proxy, see -the reference for configuring [Forward proxies](#forward-proxies). +This article walks you through configuring proxies for Coder. -If you have a reverse proxy in front of Coder, such as an Ingress Controller -internal to the cluster, then see the reference for configuring -[Reverse proxies](#reverse-proxies). +If your Coder installation accesses the internet through a forward proxy, +configure a [forward proxy](#forward-proxies). + +If you have a reverse proxy in front of Coder, such as an ingress controller +internal to the cluster, then configure a [reverse proxy](#reverse-proxies). ## Forward proxies -Coder supports proxies for outbound HTTP and HTTPS connections by configuring -the `coderd.proxy.http` and `coderd.proxy.https` settings in the Helm chart, -which correspond to the standard `http_proxy` and `https_proxy` environment -variables, respectively. +Coder supports proxies for outbound HTTP and HTTPS connections once you've +configured the `coderd.proxy.http` and `coderd.proxy.https` settings in the +[Helm chart](../admin/helm-charts.md). These settings correspond to the standard +`http_proxy` and `https_proxy` environment variables, respectively. -If the proxy URL does not include a scheme, Coder will default to treating it as -an HTTP proxy. It is also possible to connect to the proxy using HTTPS or SOCKS5 +If the proxy URL does not include a scheme, Coder defaults to treating it as +an HTTP proxy. It is also possible to connect to the proxy using HTTPS or SOCKS 5 protocols. For an HTTP proxy with address `http://localhost:3128`, use the setting: @@ -37,7 +38,7 @@ coderd: http: https://localhost ``` -For a [SOCKS 5 proxy](https://en.wikipedia.org/wiki/SOCKS) with on port 1080, +For a [SOCKS 5 proxy](https://en.wikipedia.org/wiki/SOCKS) on port 1080, use the setting: ```yaml @@ -46,12 +47,12 @@ coderd: http: socks5://10.10.10.10:1080 ``` -If you specify a proxy for outbound HTTP connections and do not specify a proxy +If you specify a proxy for outbound HTTP connections, and you do not specify a proxy for outgoing HTTPS connections, then Coder will proxy requests to HTTPS -endpoints using the HTTP proxy. The previous examples will proxy all requests, -regardless of protocol (HTTP or HTTPS), through the defined proxy. +endpoints using the HTTP proxy. The previous examples will proxy all requests through the defined proxy, +regardless of protocol (HTTP or HTTPS). -To configure a different proxy to use for outbound HTTPS connections, you may +To configure a different proxy for use with outbound HTTPS connections, you can specify the same proxy types (`http`, `https`, `socks5`) using the `coderd.proxy.https` key. @@ -62,22 +63,21 @@ For hosts that must connect directly, rather than using the proxy, define the coderd: proxy: # Coder will establish connections to cluster.local or example.com, or - # their subdomains, directly, rather than using the proxy settings. + # their subdomains directly, rather than using the proxy settings. exempt: "cluster.local,example.com" ``` ## Reverse proxies -If you have a reverse proxy in front of Coder, as will be the case when you are -using an Ingress Controller, Coder will receive connections originating from the -proxy. In order for auditing, logging, and other features to associate the -connecting user's IP address information correctly, you will need to configure -the `coderd.reverseProxy` setting. +If you have a reverse proxy in front of Coder, which is the case if you're using +an ingress controller, Coder receives connections originating from the proxy. For auditing, logging, and other features to correctly recognize the +connecting user's IP address information, you will need to configure the +`coderd.reverseProxy` setting. -By default, to prevent clients from spoofing their originating IP addresses -using the `X-Forwarded-For` or similar headers, Coder will ignore all such -headers and remove them from proxied connections to -[Dev URL services](../../workspaces/devurls.md). +> By default, Coder will ignore `X-Forwarded-For` and similar headers and remove +> them from proxied connections to [Dev URL +> services](../../workspaces/devurls.md). This prevents clients from spoofing +> their originating IP addresses. Specify a list of trusted origin addresses (those of the reverse proxy) in CIDR format as follows: From bdca0a4e54f4f29ad7137bbd0dd6b6d232b6681d Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 8 Feb 2022 10:34:24 -0600 Subject: [PATCH 4/8] lint --- guides/deployments/proxy.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/guides/deployments/proxy.md b/guides/deployments/proxy.md index 1ed44090e..2709455f6 100644 --- a/guides/deployments/proxy.md +++ b/guides/deployments/proxy.md @@ -47,10 +47,10 @@ coderd: http: socks5://10.10.10.10:1080 ``` -If you specify a proxy for outbound HTTP connections, and you do not specify a proxy -for outgoing HTTPS connections, then Coder will proxy requests to HTTPS -endpoints using the HTTP proxy. The previous examples will proxy all requests through the defined proxy, -regardless of protocol (HTTP or HTTPS). +If you specify a proxy for outbound HTTP connections, and you do not specify a +proxy for outgoing HTTPS connections, then Coder will proxy requests to HTTPS +endpoints using the HTTP proxy. The previous examples will proxy all requests +through the defined proxy, regardless of protocol (HTTP or HTTPS). To configure a different proxy for use with outbound HTTPS connections, you can specify the same proxy types (`http`, `https`, `socks5`) using the @@ -70,8 +70,9 @@ coderd: ## Reverse proxies If you have a reverse proxy in front of Coder, which is the case if you're using -an ingress controller, Coder receives connections originating from the proxy. For auditing, logging, and other features to correctly recognize the -connecting user's IP address information, you will need to configure the +an ingress controller, Coder receives connections originating from the proxy. +For auditing, logging, and other features to correctly recognize the connecting +user's IP address information, you will need to configure the `coderd.reverseProxy` setting. > By default, Coder will ignore `X-Forwarded-For` and similar headers and remove From 6572448ac2fb967df40b5479c87631030308e146 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 8 Feb 2022 10:36:37 -0600 Subject: [PATCH 5/8] update manifest --- manifest.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/manifest.json b/manifest.json index e6334da73..aa8c2037a 100644 --- a/manifest.json +++ b/manifest.json @@ -432,16 +432,16 @@ "path": "./guides/deployments/code-server.md" }, { - "path": "./guides/deployments/postgres.md" + "path": "./guides/deployments/podman.md" }, { - "path": "./guides/deployments/keycloak.md" + "path": "./guides/deployments/postgres.md" }, { - "path": "./guides/deployments/podman.md" + "path": "./guides/deployments/proxy.md" }, { - "path": "./guides/deployments/proxy.md" + "path": "./guides/deployments/keycloak.md" }, { "path": "./guides/deployments/teardown.md" From 514da2e8455b0c5e4fdebd516e91d68785c2dd67 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 8 Feb 2022 10:39:58 -0600 Subject: [PATCH 6/8] apply Cian's suggestions --- guides/deployments/proxy.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/guides/deployments/proxy.md b/guides/deployments/proxy.md index 2709455f6..f6abc2290 100644 --- a/guides/deployments/proxy.md +++ b/guides/deployments/proxy.md @@ -19,8 +19,7 @@ configured the `coderd.proxy.http` and `coderd.proxy.https` settings in the `http_proxy` and `https_proxy` environment variables, respectively. If the proxy URL does not include a scheme, Coder defaults to treating it as -an HTTP proxy. It is also possible to connect to the proxy using HTTPS or SOCKS 5 -protocols. +an HTTP proxy. Coder also supports proxies using HTTPS or SOCKS 5 protocols. For an HTTP proxy with address `http://localhost:3128`, use the setting: @@ -35,10 +34,10 @@ For an HTTPS proxy with address `https://localhost:3128`, include the scheme: ```yaml coderd: proxy: - http: https://localhost + http: https://localhost:3128 ``` -For a [SOCKS 5 proxy](https://en.wikipedia.org/wiki/SOCKS) on port 1080, +For a [SOCKS 5 proxy](https://en.wikipedia.org/wiki/SOCKS) on listening on port 1080, use the setting: ```yaml @@ -57,7 +56,7 @@ specify the same proxy types (`http`, `https`, `socks5`) using the `coderd.proxy.https` key. For hosts that must connect directly, rather than using the proxy, define the -`exempt` setting with a comma-separated list of hosts and subdomains: +`coderd.proxy.exempt` setting with a comma-separated list of hosts and subdomains: ```yaml coderd: From c6f659bcb18910caf9bcc663fc11b5150850327c Mon Sep 17 00:00:00 2001 From: Jonathan Yu Date: Wed, 9 Feb 2022 16:08:47 +0000 Subject: [PATCH 7/8] minor edits --- guides/deployments/proxy.md | 42 +++++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 11 deletions(-) diff --git a/guides/deployments/proxy.md b/guides/deployments/proxy.md index f6abc2290..ab6f7b382 100644 --- a/guides/deployments/proxy.md +++ b/guides/deployments/proxy.md @@ -18,27 +18,36 @@ configured the `coderd.proxy.http` and `coderd.proxy.https` settings in the [Helm chart](../admin/helm-charts.md). These settings correspond to the standard `http_proxy` and `https_proxy` environment variables, respectively. -If the proxy URL does not include a scheme, Coder defaults to treating it as -an HTTP proxy. Coder also supports proxies using HTTPS or SOCKS 5 protocols. +If the proxy URL does not include a scheme, Coder defaults to treating it as an +HTTP proxy. Coder also supports proxies using HTTPS or SOCKS 5 protocols. As a +special case, Coder will always establish connections to `localhost` directly, +regardless of the `coderd.proxy.exempt` setting. For additional proxy setting +information, see the [documentation for ProxyFromEnvironment]. + +[documentation for proxyfromenvironment]: + https://pkg.go.dev/net/http#ProxyFromEnvironment For an HTTP proxy with address `http://localhost:3128`, use the setting: ```yaml coderd: proxy: + # If the scheme is omitted, Coder will default to `http` http: localhost:3128 ``` -For an HTTPS proxy with address `https://localhost:3128`, include the scheme: +For an HTTPS proxy with address `https://localhost`, include the scheme: ```yaml coderd: proxy: - http: https://localhost:3128 + # If the port is omitted, Coder will use the default port corresponding to + # the selected scheme (443 for https) + http: https://localhost ``` -For a [SOCKS 5 proxy](https://en.wikipedia.org/wiki/SOCKS) on listening on port 1080, -use the setting: +For a [SOCKS 5 proxy](https://en.wikipedia.org/wiki/SOCKS) on listening on port +1080, use the setting: ```yaml coderd: @@ -53,10 +62,20 @@ through the defined proxy, regardless of protocol (HTTP or HTTPS). To configure a different proxy for use with outbound HTTPS connections, you can specify the same proxy types (`http`, `https`, `socks5`) using the -`coderd.proxy.https` key. +`coderd.proxy.https` key: + +```yaml +coderd: + proxy: + # Use an HTTP proxy on port 3128 for outbound HTTP connections, and an + # HTTP proxy on port 8080 for outbound HTTPS connections. + http: http://localhost:3128 + https: http://localhost:8080 +``` For hosts that must connect directly, rather than using the proxy, define the -`coderd.proxy.exempt` setting with a comma-separated list of hosts and subdomains: +`coderd.proxy.exempt` setting with a comma-separated list of hosts and +subdomains: ```yaml coderd: @@ -75,9 +94,10 @@ user's IP address information, you will need to configure the `coderd.reverseProxy` setting. > By default, Coder will ignore `X-Forwarded-For` and similar headers and remove -> them from proxied connections to [Dev URL -> services](../../workspaces/devurls.md). This prevents clients from spoofing -> their originating IP addresses. +> them from proxied connections to [Dev URL services]. This prevents clients +> from spoofing their originating IP addresses. + +[dev url services]: ../../workspaces/devurls.md Specify a list of trusted origin addresses (those of the reverse proxy) in CIDR format as follows: From de54b02d3248c355174dc44a0a82c3a9f7027ae9 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 9 Feb 2022 13:07:06 -0600 Subject: [PATCH 8/8] minor edits --- guides/deployments/proxy.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/deployments/proxy.md b/guides/deployments/proxy.md index ab6f7b382..ecd36305a 100644 --- a/guides/deployments/proxy.md +++ b/guides/deployments/proxy.md @@ -18,8 +18,8 @@ configured the `coderd.proxy.http` and `coderd.proxy.https` settings in the [Helm chart](../admin/helm-charts.md). These settings correspond to the standard `http_proxy` and `https_proxy` environment variables, respectively. -If the proxy URL does not include a scheme, Coder defaults to treating it as an -HTTP proxy. Coder also supports proxies using HTTPS or SOCKS 5 protocols. As a +If the proxy URL does not include a scheme, Coder treats it as an HTTP proxy by +default. Coder also supports proxies using the HTTPS and SOCKS 5 protocols. As a special case, Coder will always establish connections to `localhost` directly, regardless of the `coderd.proxy.exempt` setting. For additional proxy setting information, see the [documentation for ProxyFromEnvironment].