|
| 1 | +--- |
| 2 | +title: Global access URL configuration |
| 3 | +description: | |
| 4 | + Learn how to configure your primary and satellite deployments so that they |
| 5 | + share an access URL. |
| 6 | +state: alpha |
| 7 | +--- |
| 8 | + |
| 9 | +By default, the primary deployment and satellite deployments have different |
| 10 | +access URLs. Using two access URLs can confuse engineering teams when it comes |
| 11 | +time to determine which one they should use for Coder. |
| 12 | + |
| 13 | +To prevent confusion, Coder supports an optional unified hostname configuration |
| 14 | +where the primary deployment and all satellite deployments share a hostname. All |
| 15 | +users who access Coder use the same URL; meanwhile, your DNS server or anycast |
| 16 | +configuration ensures that users are still accessing a deployment that is near |
| 17 | +to them geographically, offering low latency when connecting to their |
| 18 | +workspaces. |
| 19 | + |
| 20 | +GeoDNS (also known as _geographical split-horizon DNS_) is a DNS load balancing |
| 21 | +technique that helps users connect to their geographically nearest servers |
| 22 | +without relying on anycast IP routing. This guide will focus on GeoDNS setup, |
| 23 | +though it will still work with anycast routing. |
| 24 | + |
| 25 | +## Requirements |
| 26 | + |
| 27 | +You will need the following: |
| 28 | + |
| 29 | +- A primary access URL (e.g. `https://primary.example.com`) |
| 30 | +- One or more satellite access URLs (e.g. `https://sydney.example.com`, |
| 31 | + `https://london.example.com`) |
| 32 | +- A "unified" access URL (e.g. `https://coder.example.com`). If you are using |
| 33 | + GeoDNS, you should set the default backend to the primary access URL. Set the |
| 34 | + backend for each region with a satellite to the corresponding satellite access |
| 35 | + URL or IP address |
| 36 | +- A TLS certificate for the primary deployment that has both the primary |
| 37 | + hostname and the corresponding unified hostname |
| 38 | +- A TLS certificate for _each_ satellite with the satellite's hostname and the |
| 39 | + corresponding unified hostname |
| 40 | + |
| 41 | +> Please note that: |
| 42 | +> |
| 43 | +> - If you are using cert-manager, you can add hostnames to a certificate by |
| 44 | +> including them in the `spec.dnsNames` section. |
| 45 | +> - We recommend maintaining a separate "regional" hostname or IP address for |
| 46 | +> each primary or satellite so you can access them explicitly to aid in |
| 47 | +> debugging. This guide will walk you through preserving the existing regional |
| 48 | +> access URL. |
| 49 | +
|
| 50 | +## Configure a unified access URL on Coder |
| 51 | + |
| 52 | +1. Configure your geo DNS or anycast routing so the primary Coder deployment and |
| 53 | + all satellites share a single hostname, as well as their individual |
| 54 | + hostnames. (We have provided instructions on |
| 55 | + [how to create a GeoDNS load balancer on Cloudflare](#create-a-geodns-load-balancer-on-cloudflare) |
| 56 | + below.) |
| 57 | + |
| 58 | +1. In the primary Helm values file, set `coderd.alternateHostnames` to your |
| 59 | + primary hostname and unified hostname: |
| 60 | + |
| 61 | + ```yaml |
| 62 | + coderd: |
| 63 | + alternateHostnames: |
| 64 | + - "primary.example.com" |
| 65 | + - "coder.example.com" |
| 66 | + ``` |
| 67 | +
|
| 68 | +1. In _each_ of your satellite deployments' Helm values file: |
| 69 | +
|
| 70 | + 1. Set `coderd.satellite.accessURL` to your unified access URL (this value |
| 71 | + will be used as the default URL). |
| 72 | + |
| 73 | + 1. Set `coderd.alternateHostnames` to your satellite's specific hostname and |
| 74 | + your unified hostname: |
| 75 | + |
| 76 | + ```yaml |
| 77 | + coderd: |
| 78 | + alternateHostnames: |
| 79 | + - "satellite.example.com" |
| 80 | + - "coder.example.com" |
| 81 | + ``` |
| 82 | + |
| 83 | +1. Redeploy your primary and satellite deployments with your new Helm values. |
| 84 | + |
| 85 | +1. Once you've fully deployed your primary and satellite deployments, log into |
| 86 | + Coder on your original primary access URL and go to **Manage** > **Admin**. |
| 87 | + |
| 88 | +1. On the **Infrastructure** tab, set the **Access URL** field to your unified |
| 89 | + access URL (e.g. `https://coder.example.com`). |
| 90 | + |
| 91 | +1. If you've enabled logins via OIDC, log into your OIDC identity provider's |
| 92 | + admin page and update Coder's redirect URI to reflect your new access URL |
| 93 | + (e.g. `https://coder.example.com/oidc/callback`). |
| 94 | + |
| 95 | +1. If you've enabled Git account linking, log into each Git provider and update |
| 96 | + Coder's redirect URI to reflect your new access URL. |
| 97 | + |
| 98 | +At this point, all users should be able to access Coder via the unified access |
| 99 | +URL. Your DNS server will automatically route users to their nearest |
| 100 | +geographical primary or satellite deployment for low latency. OIDC logins should |
| 101 | +work as expected across all domain names, including the primary access URL. |
| 102 | + |
| 103 | +## Create a geo DNS load balancer on Cloudflare |
| 104 | + |
| 105 | +To create a geo DNS load balancer on Cloudflare: |
| 106 | + |
| 107 | +1. Log in to Cloudflare, and select the domain on which you want your geo DNS |
| 108 | + hostname to exist. |
| 109 | + |
| 110 | +1. Expand the **Traffic** app on the sidebar and select **Load Balancing**. |
| 111 | + |
| 112 | +1. Enable **Load Balancing** if you haven't already. |
| 113 | + |
| 114 | +1. Ensure that your Cloudflare plan has enough origin servers for your |
| 115 | + deployments; you will need one origin server for the primary deployment and |
| 116 | + one for each satellite deployment. |
| 117 | + |
| 118 | +1. Click **Create Load Balancer**. |
| 119 | + |
| 120 | +1. Enter the unified hostname you wish to use (e.g. `coder.example.com`). |
| 121 | + |
| 122 | +  |
| 123 | + |
| 124 | +1. **Optional:** Disable Cloudflare proxying by **unchecking** the orange cloud. |
| 125 | + We recommend disabling Cloudflare proxying when using satellites, since |
| 126 | + proxying adds additional hops that will increase latency. |
| 127 | + |
| 128 | +1. Click **Next** to proceed. |
| 129 | + |
| 130 | +1. For the primary deployment and _each_ satellite deployment, do the following |
| 131 | + steps: |
| 132 | + |
| 133 | + 1. Click **+ Create an Origin Pool**. |
| 134 | + |
| 135 | + 1. Set the **Pool Name** and **Pool Description**. |
| 136 | + |
| 137 | + 1. Specify a single origin with **Origin Address** set to the hostname or IP |
| 138 | + address of the deployment. Then, set the **Weight** to **1**. |
| 139 | + |
| 140 | + 1. Click **Configure co-ordinates for Proximity Steering** and drag the |
| 141 | + marker to roughly where the deployment is located geographically. |
| 142 | + |
| 143 | + 1. Click **Save**. |
| 144 | + |
| 145 | +  |
| 146 | + |
| 147 | +1. Once you have completed the above steps for the primary and each satellite |
| 148 | + deployment, ensure that all origin pools have been assigned to the load |
| 149 | + balancer. |
| 150 | + |
| 151 | +1. Set the **Fallback Pool** to your primary deployment's origin pool. |
| 152 | + |
| 153 | +  |
| 154 | + |
| 155 | +1. Click **Next** until you reach the **Traffic Steering** step. |
| 156 | + |
| 157 | +1. Set the traffic steering policy to **Proximity steering**. |
| 158 | + |
| 159 | +1. Click **Next** until you reach the **Review** step. |
| 160 | + |
| 161 | +1. Review your changes; then, click **Save and Deploy**. |
0 commit comments