Skip to content

Deploy a Coder Control Plane

In this tutorial, you install the coder-k8s operator. Then you create one Coder instance from a CoderControlPlane resource.

Time: 10–15 minutes.

Prerequisites

  • A Kubernetes cluster, and kubectl configured to use it.
  • Permission to create the objects in dist/install.yaml: a Namespace, CustomResourceDefinitions, a ServiceAccount, a ClusterRole, a ClusterRoleBinding, and a Deployment. Step 1 also creates the coder namespace.

1. Install the operator

Set the source one time. For an install that you can repeat with the same result, use a release tag that contains dist/install.yaml, not main.

BASE="https://raw.githubusercontent.com/coder/coder-k8s/main"

Apply the install bundle. Then create the namespace for the control plane:

kubectl apply -f "$BASE/dist/install.yaml"
kubectl rollout status deployment/coder-k8s -n coder-system

kubectl create namespace coder

dist/install.yaml installs the operator in controller mode. It contains the coder-system namespace, the coder.com CRDs, the RBAC, and the operator Deployment.

  • The bundle does not deploy Coder. Step 2 does that.
  • The bundle does not include the aggregated API server. To add it, see Deploy the aggregated API server.
  • The bundle uses the ghcr.io/coder/coder-k8s:latest image. If you need a fixed operator version, pin the image too.

2. Create a control plane

kubectl apply -f "$BASE/config/samples/coder_v1alpha1_codercontrolplane.yaml"

3. Verify

kubectl get codercontrolplane codercontrolplane-sample -n coder \
  -o jsonpath='{.status.phase}{"\n"}{.status.url}{"\n"}'
kubectl rollout status deployment/codercontrolplane-sample -n coder
kubectl get deployment,service codercontrolplane-sample -n coder

Make sure that:

  • status.phase is Ready.
  • status.url has a value, for example http://codercontrolplane-sample.coder.svc.cluster.local:80.
  • A Deployment and a Service with the name codercontrolplane-sample exist in the coder namespace.

4. Open Coder (optional)

kubectl port-forward svc/codercontrolplane-sample -n coder 3000:80

Then open http://127.0.0.1:3000 in a browser.

5. Clean up (optional)

Delete the CoderAIProvider, CoderAIGatewayKey and CoderMCPServer objects first, if you created any, and then the control plane, while the operator still runs. The operator then deletes the providers, keys and MCP servers in Coder, cleans up, and removes its finalizers. A provider, key or MCP server deleted after its control plane stays in Coder. A CoderAIGatewayKey can take up to 5 minutes after its last key create. After that, remove the bundle. The commands set BASE again, because you can be in a new shell.

Warning

Delete all other CoderAIGatewayKey, CoderAIProvider, CoderControlPlane, CoderMCPServer, CoderProvisioner, and CoderWorkspaceProxy resources before you delete the bundle. Delete CoderAIProvider, CoderAIGatewayKey and CoderMCPServer resources before their control plane. When you delete the bundle, you also delete the coder.com CRDs, and Kubernetes then removes all remaining resources of these kinds in the cluster. When you delete the coder namespace, you also delete all other objects in it, for example Secrets and PersistentVolumeClaims.

BASE="https://raw.githubusercontent.com/coder/coder-k8s/main"

kubectl delete coderaiproviders --all -n coder --wait --timeout=120s
kubectl delete coderaigatewaykeys --all -n coder --wait --timeout=420s
kubectl delete codermcpservers --all -n coder --wait --timeout=120s
kubectl delete -f "$BASE/config/samples/coder_v1alpha1_codercontrolplane.yaml" --ignore-not-found
kubectl wait --for=delete codercontrolplane/codercontrolplane-sample -n coder --timeout=120s
kubectl delete -f "$BASE/dist/install.yaml" --ignore-not-found
kubectl delete namespace coder --ignore-not-found

Next steps