Release 1.28

admin/access-control/index.md

@@ -7,7 +7,7 @@ The **Authentication** tab allows you to choose how your users log in and gain
 access to Coder. Currently, you can choose between **Built-In Authentication**
 and **OpenID Connect**.
 
-## Built-In authentication
+## Built-in authentication
 
 Built-in authentication, which is the default method, allows you (or any admin)
 to manually create users who log in with their email address and temporary

admin/access-control/manage.md

@@ -23,7 +23,7 @@ domain name for the OIDC token callback; use
 
 Once you've registered a Coder application with your OIDC provider, you'll need
 to return to Coder and complete the setup process. Under **Admin** > **Manage** >
-**Authentication**, make sure that you've selected **OpenID Connect** as the
+**Authentication**, ensure that you've selected **OpenID Connect** as the
 authentication type. Then, provide the following parameters:
 
 - **Client ID**: The client ID for the Coder application you registered with the
@@ -42,7 +42,10 @@ you:
 - **Enable Access Tokens:** Toggle **On** if you'd like to allow users to fetch
   tokens from `https://<yourDomain>/api/v0/users/me/oidc-access-token`
 - **Additional Scopes:** Specify any scopes (beyond the default) that you would
-  like Coder to request during the login process
+  like Coder to request from the authentication provider. By default, Coder
+requests the scopes `openid`, `email`, and `profile`. Consult your
+authentication provider's documentation for information on which scopes they
+support.
 - **Disable built-in authentication:** Choose whether Coder removes the ability
   to log in with an email/password option when you've enabled OIDC
   authentication
@@ -55,6 +58,9 @@ have OIDC configured.
 ![Login page with built-in authentication
 disabled](../../assets/admin/disable-built-in-auth.png)
 
+To do so, navigate to **Manage** > **Admin** > **Authentication**. Then, toggle
+**Disable built-in authentication** to **On** and click **Save preferences**.
+
 [Site managers](users/user-roles#site-manager-permissions) can still use
 built-in authentication. To view this option on the login page, add the
 following query parameter to the URL you use to access your Coder deployment:

admin/satellites/global-access-url.md

@@ -0,0 +1,161 @@
+---
+title: Global access URL configuration
+description: |
+  Learn how to configure your primary and satellite deployments so that they
+  share an access URL.
+state: alpha
+---
+
+By default, the primary deployment and satellite deployments have different
+access URLs. Using two access URLs can confuse engineering teams when it comes
+time to determine which one they should use for Coder.
+
+To prevent confusion, Coder supports an optional unified hostname configuration
+where the primary deployment and all satellite deployments share a hostname. All
+users who access Coder use the same URL; meanwhile, your DNS server or anycast
+configuration ensures that users are still accessing a deployment that is near
+to them geographically, offering low latency when connecting to their
+workspaces.
+
+GeoDNS (also known as _geographical split-horizon DNS_) is a DNS load balancing
+technique that helps users connect to their geographically nearest servers
+without relying on anycast IP routing. This guide will focus on GeoDNS setup,
+though it will still work with anycast routing.
+
+## Requirements
+
+You will need the following:
+
+- A primary access URL (e.g. `https://primary.example.com`)
+- One or more satellite access URLs (e.g. `https://sydney.example.com`,
+  `https://london.example.com`)
+- A "unified" access URL (e.g. `https://coder.example.com`). If you are using
+  GeoDNS, you should set the default backend to the primary access URL. Set the
+  backend for each region with a satellite to the corresponding satellite access
+  URL or IP address
+- A TLS certificate for the primary deployment that has both the primary
+  hostname and the corresponding unified hostname
+- A TLS certificate for _each_ satellite with the satellite's hostname and the
+  corresponding unified hostname
+
+> Please note that:
+>
+> - If you are using cert-manager, you can add hostnames to a certificate by
+>   including them in the `spec.dnsNames` section.
+> - We recommend maintaining a separate "regional" hostname or IP address for
+>   each primary or satellite so you can access them explicitly to aid in
+>   debugging. This guide will walk you through preserving the existing regional
+>   access URL.
+
+## Configure a unified access URL on Coder
+
+1. Configure your geo DNS or anycast routing so the primary Coder deployment and
+   all satellites share a single hostname, as well as their individual
+   hostnames. (We have provided instructions on
+   [how to create a GeoDNS load balancer on Cloudflare](#create-a-geodns-load-balancer-on-cloudflare)
+   below.)
+
+1. In the primary Helm values file, set `coderd.alternateHostnames` to your
+   primary hostname and unified hostname:
+
+   ```yaml
+   coderd:
+     alternateHostnames:
+       - "primary.example.com"
+       - "coder.example.com"
+   ```
+
+1. In _each_ of your satellite deployments' Helm values file:
+
+   1. Set `coderd.satellite.accessURL` to your unified access URL (this value
+      will be used as the default URL).
+
+   1. Set `coderd.alternateHostnames` to your satellite's specific hostname and
+      your unified hostname:
+
+      ```yaml
+      coderd:
+        alternateHostnames:
+          - "satellite.example.com"
+          - "coder.example.com"
+      ```
+
+1. Redeploy your primary and satellite deployments with your new Helm values.
+
+1. Once you've fully deployed your primary and satellite deployments, log into
+   Coder on your original primary access URL and go to **Manage** > **Admin**.
+
+1. On the **Infrastructure** tab, set the **Access URL** field to your unified
+   access URL (e.g. `https://coder.example.com`).
+
+1. If you've enabled logins via OIDC, log into your OIDC identity provider's
+   admin page and update Coder's redirect URI to reflect your new access URL
+   (e.g. `https://coder.example.com/oidc/callback`).
+
+1. If you've enabled Git account linking, log into each Git provider and update
+   Coder's redirect URI to reflect your new access URL.
+
+At this point, all users should be able to access Coder via the unified access
+URL. Your DNS server will automatically route users to their nearest
+geographical primary or satellite deployment for low latency. OIDC logins should
+work as expected across all domain names, including the primary access URL.
+
+## Create a geo DNS load balancer on Cloudflare
+
+To create a geo DNS load balancer on Cloudflare:
+
+1. Log in to Cloudflare, and select the domain on which you want your geo DNS
+   hostname to exist.
+
+1. Expand the **Traffic** app on the sidebar and select **Load Balancing**.
+
+1. Enable **Load Balancing** if you haven't already.
+
+1. Ensure that your Cloudflare plan has enough origin servers for your
+   deployments; you will need one origin server for the primary deployment and
+   one for each satellite deployment.
+
+1. Click **Create Load Balancer**.
+
+1. Enter the unified hostname you wish to use (e.g. `coder.example.com`).
+
+   ![Enter hostname](../../assets/admin/cloudflare-geodns/hostname.png)
+
+1. **Optional:** Disable Cloudflare proxying by **unchecking** the orange cloud.
+   We recommend disabling Cloudflare proxying when using satellites, since
+   proxying adds additional hops that will increase latency.
+
+1. Click **Next** to proceed.
+
+1. For the primary deployment and _each_ satellite deployment, do the following
+   steps:
+
+   1. Click **+ Create an Origin Pool**.
+
+   1. Set the **Pool Name** and **Pool Description**.
+
+   1. Specify a single origin with **Origin Address** set to the hostname or IP
+      address of the deployment. Then, set the **Weight** to **1**.
+
+   1. Click **Configure co-ordinates for Proximity Steering** and drag the
+      marker to roughly where the deployment is located geographically.
+
+   1. Click **Save**.
+
+   ![Create pool](../../assets/admin/cloudflare-geodns/create-pool.png)
+
+1. Once you have completed the above steps for the primary and each satellite
+   deployment, ensure that all origin pools have been assigned to the load
+   balancer.
+
+1. Set the **Fallback Pool** to your primary deployment's origin pool.
+
+   ![Pools](../../assets/admin/cloudflare-geodns/pools.png)
+
+1. Click **Next** until you reach the **Traffic Steering** step.
+
+1. Set the traffic steering policy to **Proximity steering**.
+
+1. Click **Next** until you reach the **Review** step.
+
+1. Review your changes; then, click **Save and Deploy**.

admin/workspace-management/tun-device.md

@@ -0,0 +1,38 @@
+---
+title: TUN device enablement
+description: Learn how to enable TUN devices for VPN usage within Coder.
+state: alpha
+---
+
+By default, Coder workspaces do not contain a TUN device, making it difficult to
+run a VPN. However, Coder offers an admin configuration setting that, when
+enabled, automatically creates a TUN device within all Kubernetes [CVM-enabled
+workspaces](cvms/index.md).
+
+> At this time, Coder does not support TUN devices for other workspace types
+> (such as EC2 or Docker).
+>
+> If you're working with EC2 workspaces, we recommend enabling privileged mode
+> in the workspace provider settings, which will allow users to create their own
+> TUN device.
+
+## Enable TUN devices in Coder
+
+To enable TUN devices for Kubernetes [CVM-enabled workspaces](cvms/index.md):
+
+1. Log into Coder, and go to **Manage** > **Admin**.
+1. On the **Infrastructure** page, scroll down to the **Workspace container
+   runtime** section.
+1. Under **Enable TUN device**, click the toggle to switch this feature **On**.
+1. Click **Save workspaces**.
+
+![Enabling TUN devices](../../assets/admin/tun.png)
+
+The new setting will apply to workspaces **after** you rebuild them.
+
+Users running workspaces with TUN devices should be able to run VPN clients
+within their workspace as long as they have root (or `sudo`) access within their
+workspace.
+
+> We've tested this feature using the [Tailscale](https://tailscale.com/) VPN
+> within Coder.

changelog/1.28.0.md

@@ -0,0 +1,78 @@
+---
+title: "1.28.0"
+description: "Released on 02/16/2022"
+---
+
+### Breaking changes ❗
+
+- infra: Coder v1.28.x requires the use of Kubernetes v1.21 or later. See
+  Coder's [version support policy] for more information.
+
+<!-- Turn off linting to avoid changing the link -->
+<!-- markdownlint-disable MD044 -->
+
+[version support policy]:
+  ../setup/kubernetes/index.md#supported-kubernetes-versions
+
+<!-- markdownlint-enable MD044 -->
+
+### Features ✨
+
+- web: added support for requesting additional scopes from the OIDC
+  authentication provider.
+- web: added prompt for new users to link their Git accounts when signing in for
+  the first time.
+- C4D: added ability to view Docker workspace providers in the dashboard and
+  edit its name and organizations whitelist.
+- C4D: added support for remote Postgres databases to Coder for Docker.
+- cli: added ability for authenticated users to obtain their OIDC access token
+  from the Coder CLI using `coder tokens get-oidc-access-token` once an admin
+  has enabled access tokens.
+- api: added `autostart_at` field to the information returned about users.
+- infra: updated code-server to 4.0.2.
+- infra: added
+  [support for a single access URL](../admin/satellites/global-access-url.md) to
+  be used for both primary and satellite deployments using GeoDNS.
+- infra: updated Coder to pass `X-Forwarded-For` headers to dev URL connections.
+- infra: add client TLS support for Coder, which is used for connections to
+  registries and Git providers.
+- infra: added a `labels` field to all logged entries for AWS EKS.
+- infra: added
+  [support for TUN devices](../admin/workspace-management/tun-device.md) to
+  CVM-enabled workspaces.
+
+### Bug fixes 🐛
+
+- web: fixed issue with Coder not persisting custom resource allocation
+  requests.
+- web: fixed issue where existing OIDC users cannot log in when the license is
+  at maximum usage.
+- web: fixed issue with dormant user accounts not being redirected home properly
+  after being reactivated.
+- web: fixed issue with workspace provider tooltip interfering with the
+  workspace start button.
+- web: removed ability to use double-hyphens in workspaces, causing conflict
+  with dev URLs.
+- web: fix issue with custom apps not working with satellites.
+- C4D: fixed issue with access URLs not being saved.
+- C4D: fixed issue with inability to rebuild workspaces relying on templates.
+- cli: fixed issue where the `coder-cli` location was not appended to the `PATH`
+  in terminal sessions.
+- infra: added functionality to clean up and remove image pull secrets during
+  workspace clean-up.
+- infra: fixed issues with `coderd` certificate injection.
+
+### Security updates 🔐
+
+- web: added requirement to authenticate when auto-creating dev URLs.
+
+### Known issues 🔧
+
+- web: the service banner (if enabled) reappears for all users, even if they've
+  previously dismissed it.
+- web: using the web terminal in Coder can occasionally result in the connection
+  being reset and needing to be restarted.
+- web: the **Switch workspace** drop-down menu shows a workspace's status as
+  **Building** even though the build process is completed.
+- web: users installing v1.24 (or later) into an air-gapped environment cannot
+  upload their license when prompted.

guides/admin/oidc-azuread.md

@@ -103,7 +103,7 @@ the Coder UI.
 1. Log in to Coder, and go to **Manage** > **Admin** > **Authentication**.
 1. In the top-most drop-down box, select **OpenID Connect**.
 1. Provide the requested values for **Client ID**, **Client Secret**, and
-   **Issuer**.
+   **Issuer**. Optionally, you can specify **Additional Scopes**.
 
 When done, click **Save Preferences**.
 

guides/admin/oidc-google.md

@@ -66,6 +66,8 @@ Now that you've registered an app, you can provide the relevant **Client ID**,
 
 1. For the **Issuer**, provide `accounts.google.com`.
 
+1. For **Additional Scopes**, you can leave this value blank.
+
 1. Click **Save preferences**.
 
 You can now use Google as an SSO provider with Coder.

guides/admin/oidc-okta.md

@@ -5,9 +5,9 @@ description: Learn how to use Okta SSO with Coder.
 
 This article walks you through setting up single sign-on to Coder using Okta.
 
-Configuring [Coder's OpenID
-Connect](../../admin/access-control/index.md#openid-connect) feature requires
-you to provide three pieces of information from Okta:
+Configuring
+[Coder's OpenID Connect](../../admin/access-control/index.md#openid-connect)
+feature requires you to provide three pieces of information from Okta:
 
 - Client ID
 - Client Secret
@@ -33,14 +33,14 @@ you need to provide to Coder.
 1. Select **OpenID Connect** and click **Create**
 
    ![Okta Create Application
-   Modal](../../assets/guides/admin/okta-custom-app-creation.jpg)
+Modal](../../assets/guides/admin/okta-custom-app-creation.jpg)
 
 1. Provide an **Application name** (i.e., `Coder`), (optionally) add a logo, and
    add the **Login redirect URIs** for Coder (it will be formatted similarly to
    `https://coder.my-company.com/oidc/callback`).
 
    ![Okta Create OpenID
-   Application](../../assets/guides/admin/okta-create-openid-integration.jpg)
+Application](../../assets/guides/admin/okta-create-openid-integration.jpg)
 
 1. Click **Save** to proceed.
 
@@ -85,7 +85,7 @@ the Coder UI.
 1. Log in to Coder, and go to **Manage** > **Admin** > **Authentication**.
 1. In the top-most drop-down box, select **OpenID Connect**.
 1. Provide the requested values for **Client ID**, **Client Secret**, and
-   **Issuer**.
+   **Issuer**. Optionally, you can specify **Additional Scopes**.
 
 When done, click **Save Preferences**.