docs: add high availability (#4583)

- Rename `CODER_DERP_SERVER_RELAY_ADDRESS`

Co-authored-by: Ammar Bandukwala <ammar@ammar.io>

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

docs/admin/high-availability.md

@@ -0,0 +1,63 @@
+# High Availability
+
+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 other cloud vendors offer fully-managed HA Postgres services that pair
+nicely with Coder.
+
+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.
+
+## Setup
+
+Coder automatically enters HA mode when multiple instances simultaneously connect
+to the same Postgres endpoint.
+
+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.
+
+`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:
+
+| 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 into Kubernetes by some other means, insert the relay URL
+via the environment like so:
+
+```yaml
+  env:
+    - name: POD_IP
+      valueFrom:
+        fieldRef:
+          fieldPath: status.podIP
+    - name: CODER_DERP_SERVER_RELAY_URL
+      value: http://$(POD_IP)
+```
+Then, increase the number of pods.
+
+## Up next
+
+- [Networking](../networking.md)
+- [Kubernetes](../install/kubernetes.md)
+- [Enterprise](./enterprise.md)