From a6df4ebf8e89b13a568c9a9f837b37a0cbd88884 Mon Sep 17 00:00:00 2001 From: Kyle Carberry Date: Mon, 17 Oct 2022 13:55:25 +0000 Subject: [PATCH 1/4] Add scaffoled for HA docs --- docs/admin/high-availability.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 docs/admin/high-availability.md diff --git a/docs/admin/high-availability.md b/docs/admin/high-availability.md new file mode 100644 index 0000000000000..18b6a2ec9ea97 --- /dev/null +++ b/docs/admin/high-availability.md @@ -0,0 +1,21 @@ +# High Availability + +- High Availability enables multiple instances of the Coder server connected to the same PostgreSQL database. + +## Kubernetes Setup + +- Using our Helm, just increase `coder.replicaCount` in `values.yaml` +- Custom Helm Chart: + ``` + env: + - name: POD_IP + valueFrom: + fieldRef: + fieldPath: status.podIP + - name: CODER_DERP_SERVER_RELAY_ADDRESS + value: http://$(POD_IP) + ``` + +## Virtual Machine Setup + +Set `CODER_DERP_SERVER_RELAY_ADDRESS` to an address that other instances can access: From b98b390a87883415762c8fa3b78af9f06a8eec79 Mon Sep 17 00:00:00 2001 From: Ammar Bandukwala Date: Mon, 17 Oct 2022 17:26:39 +0000 Subject: [PATCH 2/4] Further work on HA docs - Also, rename `CODER_DERP_SERVER_RELAY_ADDRESS` --- cli/deployment/flags.go | 2 +- docs/admin/high-availability.md | 24 +++++++++++++++++++++--- docs/images/icons/hydra.svg | 5 +++++ docs/manifest.json | 31 +++++++++++++++++++------------ helm/templates/coder.yaml | 2 +- 5 files changed, 47 insertions(+), 17 deletions(-) create mode 100644 docs/images/icons/hydra.svg diff --git a/cli/deployment/flags.go b/cli/deployment/flags.go index 714365cc8e897..792051f805f70 100644 --- a/cli/deployment/flags.go +++ b/cli/deployment/flags.go @@ -88,7 +88,7 @@ func Flags() *codersdk.DeploymentFlags { DerpServerRelayAddress: &codersdk.StringFlag{ Name: "DERP Server Relay Address", Flag: "derp-server-relay-address", - EnvVar: "CODER_DERP_SERVER_RELAY_ADDRESS", + EnvVar: "CODER_DERP_SERVER_RELAY_URL", Description: "An HTTP address that is accessible by other replicas to relay DERP traffic. Required for high availability.", Enterprise: true, }, diff --git a/docs/admin/high-availability.md b/docs/admin/high-availability.md index 18b6a2ec9ea97..e45b8926ceaa2 100644 --- a/docs/admin/high-availability.md +++ b/docs/admin/high-availability.md @@ -1,6 +1,18 @@ # High Availability -- High Availability enables multiple instances of the Coder server connected to the same PostgreSQL database. +High Availability (HA) mode solves for horizontal scalability and automatic failover +within a single region. When in HA mode, Coder continues using a single Postgres +endpoint. [GCP](https://cloud.google.com/sql/docs/postgres/high-availability), [AWS](https://docs.aws.amazon.com/prescriptive-guidance/latest/saas-multitenant-managed-postgresql/availability.html), and others offer fully-managed HA Postgres services. + +For Coder to operate correctly, all Coder servers must be within 10ms of each other +and Postgres. We make a best-effort attempt to warn the user when inter-coder +latency is too high, but if requests start dropping, this is one metric to investigate. + +## Automatic Setup + +Coder automatically enters HA mode when multiple instances connect to the same +Postgres endpoint. Thus, enabling HA is as simple as increasing the number +of deployed Coder replicas. ## Kubernetes Setup @@ -12,10 +24,16 @@ valueFrom: fieldRef: fieldPath: status.podIP - - name: CODER_DERP_SERVER_RELAY_ADDRESS + - name: CODER_DERP_SERVER_RELAY_URL value: http://$(POD_IP) ``` ## Virtual Machine Setup -Set `CODER_DERP_SERVER_RELAY_ADDRESS` to an address that other instances can access: +Set `CODER_DERP_SERVER_RELAY_URL` to an address that other instances can access: + +## Up next + +- [Networking](../networking.md) +- [Kubernetes](../install/kubernetes.md.md) +- [Enterprise](./enterprise.md) diff --git a/docs/images/icons/hydra.svg b/docs/images/icons/hydra.svg new file mode 100644 index 0000000000000..4b6d0938ed7eb --- /dev/null +++ b/docs/images/icons/hydra.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/docs/manifest.json b/docs/manifest.json index 1cf16bd323f76..4ff1536a6b0d8 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -27,17 +27,17 @@ "children": [ { "title": "Install script", - "description": "One-line install script for macOS and Linux.", + "description": "One-line install script for macOS and Linux", "path": "./install/install.sh.md" }, { "title": "System packages", - "description": "System packages for Debian, Ubuntu, Fedora, CentOS, RHEL, SUSE, and Alpine.", + "description": "System packages for Debian, Ubuntu, Fedora, CentOS, RHEL, SUSE, and Alpine", "path": "./install/packages.md" }, { "title": "Kubernetes", - "description": "Install Coder with Kubernetes via Helm.", + "description": "Install Coder with Kubernetes via Helm", "path": "./install/kubernetes.md" }, { @@ -47,12 +47,12 @@ }, { "title": "Standalone binaries", - "description": "Download binaries for macOS, Windows, and Linux.", + "description": "Download binaries for macOS, Windows, and Linux", "path": "./install/binary.md" }, { "title": "Uninstall", - "description": "Learn how to uninstall Coder.", + "description": "Learn how to uninstall Coder", "path": "./install/uninstall.md" } ] @@ -182,7 +182,7 @@ "children": [ { "title": "Authentication", - "description": "Learn how to set up authentication using GitHub or OpenID Connect.", + "description": "Learn how to set up authentication using GitHub or OpenID Connect", "icon_path": "./images/icons/key.svg", "path": "./admin/auth.md" }, @@ -208,13 +208,13 @@ }, { "title": "Configuration", - "description": "Learn how to configure Coder.", + "description": "Learn how to configure Coder", "path": "./admin/configure.md", "icon_path": "./images/icons/toggle_on.svg" }, { "title": "Upgrading", - "description": "Learn how to upgrade Coder.", + "description": "Learn how to upgrade Coder", "icon_path": "./images/icons/upgrade.svg", "path": "./admin/upgrade.md" }, @@ -226,27 +226,34 @@ }, { "title": "Audit Logs", - "description": "Learn how to use Audit Logs in your Coder deployment.", + "description": "Learn how to use Audit Logs in your Coder deployment", "icon_path": "./images/icons/radar.svg", "path": "./admin/audit-logs.md", "state": "enterprise" }, { "title": "Quotas", - "description": "Learn how to use Workspace Quotas in Coder.", + "description": "Learn how to use Workspace Quotas in Coder", "icon_path": "./images/icons/dollar.svg", "path": "./admin/quotas.md", "state": "enterprise" }, + { + "title": "High Availability", + "description": "Learn how to configure Coder for High Availability", + "icon_path": "./images/icons/hydra.svg", + "path": "./admin/high-availability.md", + "state": "enterprise" + }, { "title": "Enterprise", - "description": "Learn how to enable Enterprise features.", + "description": "Learn how to enable Enterprise features", "icon_path": "./images/icons/group.svg", "path": "./admin/enterprise.md" }, { "title": "Telemetry", - "description": "Learn what usage telemetry Coder collects.", + "description": "Learn what usage telemetry Coder collects", "icon_path": "./images/icons/science.svg", "path": "./admin/telemetry.md" } diff --git a/helm/templates/coder.yaml b/helm/templates/coder.yaml index 1165251fc885b..02badc277d81f 100644 --- a/helm/templates/coder.yaml +++ b/helm/templates/coder.yaml @@ -40,7 +40,7 @@ spec: valueFrom: fieldRef: fieldPath: status.podIP - - name: CODER_DERP_SERVER_RELAY_ADDRESS + - name: CODER_DERP_SERVER_RELAY_URL value: "{{ include "coder.portName" . }}://$(KUBE_POD_IP):{{ include "coder.port" . }}" {{- include "coder.tlsEnv" . | nindent 12 }} {{- with .Values.coder.env -}} From 7cf7e56c410a6c5b0f01c5a5bed3100794689ad7 Mon Sep 17 00:00:00 2001 From: Ammar Bandukwala Date: Mon, 17 Oct 2022 18:22:01 +0000 Subject: [PATCH 3/4] Starting to look good --- docs/admin/high-availability.md | 56 +++++++++++++++++++++++---------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/docs/admin/high-availability.md b/docs/admin/high-availability.md index e45b8926ceaa2..698caa5c2962a 100644 --- a/docs/admin/high-availability.md +++ b/docs/admin/high-availability.md @@ -2,23 +2,50 @@ High Availability (HA) mode solves for horizontal scalability and automatic failover within a single region. When in HA mode, Coder continues using a single Postgres -endpoint. [GCP](https://cloud.google.com/sql/docs/postgres/high-availability), [AWS](https://docs.aws.amazon.com/prescriptive-guidance/latest/saas-multitenant-managed-postgresql/availability.html), and others offer fully-managed HA Postgres services. +endpoint. [GCP](https://cloud.google.com/sql/docs/postgres/high-availability), [AWS](https://docs.aws.amazon.com/prescriptive-guidance/latest/saas-multitenant-managed-postgresql/availability.html), +and other cloud vendors offer fully-managed HA Postgres services that pair +nicely with Coder. -For Coder to operate correctly, all Coder servers must be within 10ms of each other +For Coder to operate correctly, every node must be within 10ms of each other and Postgres. We make a best-effort attempt to warn the user when inter-coder latency is too high, but if requests start dropping, this is one metric to investigate. +Note that this latency requirement applies _only_ to coder services. Coder will +operate correctly even with few seconds of latency on +workspace <-> coder and user <-> coder connections. -## Automatic Setup +## Setup -Coder automatically enters HA mode when multiple instances connect to the same -Postgres endpoint. Thus, enabling HA is as simple as increasing the number -of deployed Coder replicas. +Coder automatically enters HA mode when multiple instances simultaneously connect +to the same Postgres endpoint. -## Kubernetes Setup +HA has one required configuration variable that you must set for each Coder +node: `CODER_DERP_SERVER_RELAY_URL`. The HA nodes use these URLs to communicate +with each other. Inter-node communication is only required while using the +embedded relay (default). If you're using [custom relays](../networking.md#custom-relays), Coder ignores `CODER_DERP_SERVER_RELAY_URL`, since Postgres is the sole rendezvous for the Coder nodes. -- Using our Helm, just increase `coder.replicaCount` in `values.yaml` -- Custom Helm Chart: - ``` +Since `CODER_ACCESS_URL` is a load balancer to all Coder nodes, +`CODER_DERP_SERVER_RELAY_URL` will never be `CODER_ACCESS_URL`. + +Here's an example 3-node network configuration setup: + +| Name | `CODER_ADDRESS` | `CODER_DERP_SERVER_RELAY_URL` | `CODER_ACCESS_URL` | +| ------- | --------------- | ----------------------------- | ----------------------- | +| `coder-1` | `*:80` | `http://10.0.0.1:80` | `https://coder.big.corp` | +| `coder-2` | `*:80` | `http://10.0.0.2:80` | `https://coder.big.corp` | +| `coder-3` | `*:80` | `http://10.0.0.3:80` | `https://coder.big.corp` | + + +## Kubernetes + +If you installed Coder via +[our Helm Chart](../install/kubernetes.md#install-coder-with-helm), just +increase `coder.replicaCount` in `values.yaml`. + + +If you installed Coder by some other means, insert the relay URL via the +environment like so: + +```yaml env: - name: POD_IP valueFrom: @@ -26,14 +53,11 @@ of deployed Coder replicas. fieldPath: status.podIP - name: CODER_DERP_SERVER_RELAY_URL value: http://$(POD_IP) - ``` - -## Virtual Machine Setup - -Set `CODER_DERP_SERVER_RELAY_URL` to an address that other instances can access: +``` +Then, increase the number of pods. ## Up next - [Networking](../networking.md) -- [Kubernetes](../install/kubernetes.md.md) +- [Kubernetes](../install/kubernetes.md) - [Enterprise](./enterprise.md) From fc81bae24722e897725c805fa9523b323af8d223 Mon Sep 17 00:00:00 2001 From: Ammar Bandukwala Date: Mon, 17 Oct 2022 18:52:37 +0000 Subject: [PATCH 4/4] Update enterprise.md --- docs/admin/enterprise.md | 22 +++++++++++++--------- docs/admin/high-availability.md | 12 ++++++------ 2 files changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/admin/enterprise.md b/docs/admin/enterprise.md index 5524660bc8b29..45ecf3dfe48de 100644 --- a/docs/admin/enterprise.md +++ b/docs/admin/enterprise.md @@ -3,28 +3,32 @@ Coder is free to use and includes some features that are only accessible with a paid license. Contact sales@coder.com to obtain a license. -These features are available in the enterprise edition: - -- [Audit Logging](./audit-logs.md) -- [Browser Only Connections](../networking.md#browser-only-connections) +### User Management - [Groups](./groups.md) - [Template RBAC](./rbac.md) -- [Quotas](./quotas.md) - [SCIM](./auth.md#scim) -And we're releasing these imminently: +### Networking & Deployment +- [High Availability](./high-availability.md) +- [Browser Only Connections](../networking.md#browser-only-connections) + +### Other +- [Audit Logging](./audit-logs.md) +- [Quotas](./quotas.md) + +### Coming soon -- High Availability - Multiple Git Provider Authentication +- Max Workspace Auto-Stop ## Adding your license key -### You will need: +### Requirements - Your license key (contact sales@coder.com if you don't have yours) - Coder CLI installed -### Steps: +### Instructions 1. Save your license key to disk and make note of the path 2. Open a terminal diff --git a/docs/admin/high-availability.md b/docs/admin/high-availability.md index 698caa5c2962a..7d418ea5bae39 100644 --- a/docs/admin/high-availability.md +++ b/docs/admin/high-availability.md @@ -18,13 +18,13 @@ workspace <-> coder and user <-> coder connections. Coder automatically enters HA mode when multiple instances simultaneously connect to the same Postgres endpoint. -HA has one required configuration variable that you must set for each Coder +HA brings one configuration variable to set in each Coder node: `CODER_DERP_SERVER_RELAY_URL`. The HA nodes use these URLs to communicate with each other. Inter-node communication is only required while using the -embedded relay (default). If you're using [custom relays](../networking.md#custom-relays), Coder ignores `CODER_DERP_SERVER_RELAY_URL`, since Postgres is the sole rendezvous for the Coder nodes. +embedded relay (default). If you're using [custom relays](../networking.md#custom-relays), Coder ignores `CODER_DERP_SERVER_RELAY_URL` since Postgres is the sole rendezvous for the Coder nodes. -Since `CODER_ACCESS_URL` is a load balancer to all Coder nodes, -`CODER_DERP_SERVER_RELAY_URL` will never be `CODER_ACCESS_URL`. +`CODER_DERP_SERVER_RELAY_URL` will never be `CODER_ACCESS_URL` because +`CODER_ACCESS_URL` is a load balancer to all Coder nodes. Here's an example 3-node network configuration setup: @@ -42,8 +42,8 @@ If you installed Coder via increase `coder.replicaCount` in `values.yaml`. -If you installed Coder by some other means, insert the relay URL via the -environment like so: +If you installed Coder into Kubernetes by some other means, insert the relay URL +via the environment like so: ```yaml env: