This article walks you through the process of deploying a workspace provider to a Kubernetes cluster. If you do not have one, you can use our cluster guides to create one compatible with Coder.


Install the following dependencies if you haven't already:

Creating the new workspace provider

  1. Log in to Coder, and go to Manage > Providers.

  2. Click Create New in the top-right corner to launch the Create a Kubernetes Provider page.

  3. Provide a name for your new provider (e.g., us-central-gpus).

  4. Under Cluster Address, provide the address of your Kubernetes control plane. If you don't know the address, you can get it by running the following in the terminal:

    kubectl cluster-info
  5. Provide the namespace to which Coder should provision new workspaces. If you don't already have one, you can create one by running the following in the terminal:

    kubectl create namespace <NAMESPACE>
  6. Create a ServiceAccount, Role, and Rolebinding in the namespace that you specified in the previous step (Coder will use this account to provision workspaces):

    kubectl apply -n <NAMESPACE> -f - <<EOF
    apiVersion: v1
    kind: ServiceAccount
      name: coder
    apiVersion: rbac.authorization.k8s.io/v1
    kind: Role
      name: coder
      - apiGroups: ["", "apps", "networking.k8s.io"] # "" indicates the core API group
        resources: ["persistentvolumeclaims", "pods", "deployments", "services", "secrets", "pods/exec","pods/log", "events", "networkpolicies", "serviceaccounts"]
        verbs: ["create", "get", "list", "watch", "update", "patch", "delete", "deletecollection"]
      - apiGroups: ["metrics.k8s.io", "storage.k8s.io"]
        resources: ["pods", "storageclasses"]
        verbs: ["get", "list", "watch"]
    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
      name: coder
      - kind: ServiceAccount
        name: coder
      kind: Role
      name: coder
      apiGroup: rbac.authorization.k8s.io

    You should get a response similar to the following:

    serviceaccount/coder created
    role.rbac.authorization.k8s.io/coder created
    rolebinding.rbac.authorization.k8s.io/coder created
  7. Retrieve the service account token and certificate, which Coder uses to authenticate with the Kubernetes cluster.

    kubectl get secrets -n <NAMESPACE> -o jsonpath="{.items[?(@.metadata.annotations['kubernetes\.io/service-account\.name']=='coder')].data}{'\n'}"

    Copy and paste the output returned from this command into the Coder form.

  8. Click Create Provider to proceed. Coder will deploy your provider at this point.

Allowlist organizations

Before users can provision workspaces using the provider, you must edit the provider and indicate the organizations that can use the provider.

Once Coder has deployed your provider, you'll see it listed on the Providers page. Click the vertical ellipsis to its right, and select Edit. Scroll down to Organizations and select the ones you want to be able to use this provider.

Users in the allowed organizations can now choose to deploy into the newly set up workspace provider.

Using workspace providers in separate regions

Workspace providers enable a single Coder deployment to manage resources anywhere you can deploy Kubernetes. A common use case this feature enables is to colocate the developer's physical location and workspace location to the same geographic region.

To ensure low latency in these scenarios, you should deploy satellites into these regions. Satellites enable traffic to stay within the region and provide an improved user experience.

See an opportunity to improve our docs? Make an edit.