Kubernetes

Requirements

Before proceeding, please ensure that you have a Kubernetes cluster running K8s 1.19+ and have Helm 3.5+ installed.

You'll also want to install the latest version of Coder locally in order to log in and manage templates.

Install Coder with Helm

Warning: Helm support is new and not yet complete. There may be changes to the Helm chart between releases which require manual values updates. Please file an issue if you run into any issues.

  1. Create a namespace for Coder, such as coder:

    $ kubectl create namespace coder
    
  2. Create a PostgreSQL deployment. Coder does not manage a database server for you.

    • If you're in a public cloud such as Google Cloud, AWS, Azure, or DigitalOcean, you can use the managed PostgreSQL offerings they provide. Make sure that the PostgreSQL service is running and accessible from your cluster. It should be in the same network, same project, etc.

    • You can install Postgres manually on your cluster using the Bitnami PostgreSQL Helm chart. There are some helpful guides on the internet that explain sensible configurations for this chart. Example:

      # Install PostgreSQL
      helm repo add bitnami https://charts.bitnami.com/bitnami
      helm install coder-db bitnami/postgresql \
          --namespace coder \
          --set auth.username=coder \
          --set auth.password=coder \
          --set auth.database=coder \
          --set persistence.size=10Gi
      

      The cluster-internal DB URL for the above database is:

      postgres://coder:[email protected]cluster.local:5432/coder?sslmode=disable
      

      Ensure you set up periodic backups so you don't lose data.

    • You can use Postgres operator to manage PostgreSQL deployments on your Kubernetes cluster.

  3. Download the latest coder_helm package from GitHub releases.

  4. Create a secret with the database URL:

    # Uses Bitnami PostgreSQL example. If you have another database,
    # change to the proper URL.
    kubectl create secret generic coder-db-url -n coder \
       --from-literal=url="postgres://coder:[email protected]:5432/coder?sslmode=disable"
    
  5. Create a values.yaml with the configuration settings you'd like for your deployment. For example:

    coder:
      # You can specify any environment variables you'd like to pass to Coder
      # here. Coder consumes environment variables listed in
      # `coder server --help`, and these environment variables are also passed
      # to the workspace provisioner (so you can consume them in your Terraform
      # templates for auth keys etc.).
      #
      # Please keep in mind that you should not set `CODER_ADDRESS`,
      # `CODER_TLS_ENABLE`, `CODER_TLS_CERT_FILE` or `CODER_TLS_KEY_FILE` as
      # they are already set by the Helm chart and will cause conflicts.
      env:
        - name: CODER_ACCESS_URL
          value: "https://coder.example.com"
        - name: CODER_PG_CONNECTION_URL
          valueFrom:
            secretKeyRef:
              # You'll need to create a secret called coder-db-url with your
              # Postgres connection URL like:
              # postgres://coder:[email protected]:5432/coder?sslmode=disable
              name: coder-db-url
              key: url
    
        # This env variable controls whether or not to auto-import the
        # "kubernetes" template on first startup. This will not work unless
        # coder.serviceAccount.workspacePerms is true.
        - name: CODER_TEMPLATE_AUTOIMPORT
          value: "kubernetes"
    
      #tls:
      #  secretName: my-tls-secret-name
    

    You can view our Helm README for details on the values that are available, or you can view the values.yaml file directly.

  6. Run the following commands to install the chart in your cluster.

    helm install coder ./coder_helm_x.y.z.tgz \
        --namespace coder \
        --values values.yaml
    

    You can watch Coder start up by running kubectl get pods -n coder. Once Coder has started, the coder-* pods should enter the Running state.

  7. Log in to Coder

    Use kubectl get svc -n coder to get the IP address of the LoadBalancer. Visit this in the browser to set up your first account.

    If you do not have a domain, you should set CODER_ACCESS_URL to this URL in the Helm chart and upgrade Coder (see below). This allows workspaces to connect to the proper Coder URL.

Upgrading Coder via Helm

To upgrade Coder in the future or change values, you can run the following command with a new coder_helm_x.y.z.tgz file from GitHub releases:

$ helm upgrade coder ./coder_helm_x.y.z.tgz \
    --namespace coder \
    -f values.yaml

Troubleshooting

You can view Coder's logs by getting the pod name from kubectl get pods and then running kubectl logs <pod name>. You can also view these logs in your Cloud's log management system if you are using managed Kubernetes.

Kubernetes-based workspace is stuck in "Connecting..."

Ensure you have an externally-reachable CODER_ACCESS_URL set in your helm chart. If you do not have a domain set up, this should be the IP address of Coder's LoadBalancer (kubectl get svc -n coder).

See troubleshooting templates for more steps.

Next steps

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