Start Building for Free

Container runner installation (Kubernetes)

2 months ago5 min read
Server v4.3+
On This Page

This page describes how to install CircleCI’s container runner.


To install container runners and run jobs, you will need to have root access, and have the following set up and installed:

Self-hosted runner terms agreement

1. Create namespace and resource class

2. Container runner installation

  1. Add the container runner Helm repository by running the following command:

    helm repo add container-agent
  2. Next, run the following:

    helm repo update
  3. Then, run the following command to create the circleci Kubernetes namespace:

    kubectl create namespace circleci
  4. Create a file called values.yaml file containing the following:

          token: <resource_class_token>
  5. Finally, run the following command:

    helm install container-agent container-agent/container-agent -n circleci -f values.yaml

3. Enable rerun job with SSH (optional) - Open preview

The ability to rerun a job with SSH is in open preview for CircleCI container runner. To enable this optional feature, follow the instructions below after reading through the considerations. Rerunning jobs with SSH allows you to troubleshoot problems through inspecting log files, running processes, and directory paths.

The Rerun job with SSH feature makes use of the Gateway API to facilitate SSH access from outside your cluster. To enable this feature, Gateway API resources must first be provisioned on your cluster, and the CircleCI container agent configuration must be updated.

1. Install Envoy Gateway to your cluster

  1. First, install the Gateway API CRDs and Envoy Gateway, as defined in the Envoy Gateway Helm installation document. To do this, replace <version> with the most recent stable release compatible with your cluster, then run the following command:

    helm install eg oci:// --version <version> -n envoy-gateway-system --create-namespace
  2. Finally, wait for Envoy Gateway to become available:

    kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available

2. Enable the Rerun job with SSH feature

  1. Once all Gateway API prerequisites are installed and available, add the agent.ssh.enabled = "true" parameter to the container runner configuration:

        enabled: "true"

    For a full list of SSH configuration options, refer to the Helm chart values.

  2. Redeploy the updated manifest:

    helm upgrade --wait --timeout=5m <release-name> container-agent/container-agent -n <namespace> -f values.yaml
  3. Wait for the SSH Gateway to be programmed:

    kubectl wait gateway --timeout=5m --all --for=condition=Programmed -n <namespace>

    Container runner is now ready for rerunning jobs with SSH.

Container runner configuration example

Once you have installed the container runner within your cluster, create and trigger a CircleCI job that uses the Docker executor to validate the installation. The fields you must set for a specific job to run using your container runners are:

  • image:

  • resource_class: <namespace>/<resource-class>

Simple example of how you could set up a job (cimg/base:2021.11 is a commonly used CircleCI Docker image):

version: 2.1

      - image: cimg/base:2021.11
    resource_class: <namespace>/<resource-class>
      - checkout
      - run: echo "Hi I'm on Runners!"

      - build


Refer to the Troubleshoot Container Runner section of the Troubleshoot Self-hosted Runner guide if you encounter issues installing or running container runner.

Suggest an edit to this page

Make a contribution
Learn how to contribute