diff --git a/docs/images/platforms/kubernetes/region-picker.png b/docs/images/platforms/kubernetes/region-picker.png new file mode 100644 index 0000000000000..465a1b6324c5a Binary files /dev/null and b/docs/images/platforms/kubernetes/region-picker.png differ diff --git a/docs/manifest.json b/docs/manifest.json index 2fdf523e89e60..7b2c837cc2afc 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -106,7 +106,14 @@ { "title": "Kubernetes", "description": "Set up Coder on Kubernetes", - "path": "./platforms/kubernetes.md" + "path": "./platforms/kubernetes/index.md", + "children": [ + { + "title": "Additional clusters", + "description": "Deploy workspaces on additional Kubernetes clusters", + "path": "./platforms/kubernetes/additional-clusters.md" + } + ] }, { "title": "Other platforms", diff --git a/docs/platforms/kubernetes/additional-clusters.md b/docs/platforms/kubernetes/additional-clusters.md new file mode 100644 index 0000000000000..af05efc912a65 --- /dev/null +++ b/docs/platforms/kubernetes/additional-clusters.md @@ -0,0 +1,218 @@ +# Additional clusters + +With Coder, you can deploy workspaces in additional Kubernetes clusters using different [authentication methods](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication) in the Terraform provider. + +![Region picker in "Create workspace" screen](../../images/platforms/kubernetes/region-picker.png) + +## Option 1) Kubernetes contexts and kubeconfig + +First, create a kubeconfig file with [multiple contexts](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/). + +```sh +$ kubectl config get-contexts + +CURRENT NAME CLUSTER + workspaces-europe-west2-c workspaces-europe-west2-c +* workspaces-us-central1-a workspaces-us-central1-a +``` + +### Kubernetes control plane + +If you deployed Coder on Kubernetes, you can attach a kubeconfig as a secret. + +This assumes Coder is deployed on the `coder` namespace and your kubeconfig file is in ~/.kube/config. + +```sh +kubectl create secret generic kubeconfig-secret -n coder--from-file=~/.kube/config +``` + +Modify your helm values to mount the secret: + +```yaml +coder: + # ... + volumes: + - name: "kubeconfig-mount" + secret: + secretName: "kubeconfig-secret" + volumeMounts: + - name: "kubeconfig-mount" + mountPath: "/mnt/secrets/kube" + readOnly: true +``` + +[Upgrade Coder](http://localhost:3000/docs/v2/latest/install/kubernetes#upgrading-coder-via-helm) with these new values. + +### VM control plane + +If you deployed Coder on a VM, copy the kubeconfig file to `/home/coder/.kube/config`. + +### Create a Coder template + +You can start from our [example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes). From there, add [template parameters](../../templates/parameters.md) to allow developers to pick their desired cluster. + +```hcl +# main.tf + +data "coder_parameter" "kube_context" { + name = "kube_context" + display_name = "Cluster" + default = "workspaces-us-central1-a" + mutable = false + option { + name = "US Central" + icon = "/emojis/1f33d.png" + value = "workspaces-us-central1-a" + } + option { + name = "Europe West" + icon = "/emojis/1f482.png" + value = "workspaces-europe-west2-c" + } +} + +provider "kubernetes" { + config_path = "~/.kube/config" # or /mnt/secrets/kube/config for Kubernetes + config_context = data.coder_parameter.kube_context.value +} +``` + +## Option 2) Kubernetes ServiceAccounts + +Alternatively, you can authenticate with remote clusters with ServiceAccount tokens. Coder can store these secrets on your behalf with [managed Terraform variables](../../templates/parameters.md#managed-terraform-variables). + +Alternatively, these could also be fetched from Kubernetes secrets or even [Hashicorp Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret). + +This guide assumes you have a `coder-workspaces` namespace on your remote cluster. Change the namespace accordingly. + +### Create a ServiceAccount + +Run this command against your remote cluster to create a ServiceAccount, Role, RoleBinding, and token: + +```sh +kubectl apply -n coder-workspaces -f - < If you deployed Coder on another platform besides Kubernetes, you can set `use_kubeconfig: true` for Coder to read the config from your VM, for example.