CircleCI has a new container runner in open preview, which will replace the self-hosted runner on Kubernetes solution detailed on this page.

Repository with various files to install CircleCI's runner on Kubernetes via Helm chart.

• Generate a token and resource class for your runner. For each different type of runner you want to run, you will need to repeat these same steps.
  • For example, if you want ten runners that pull the same types of jobs or run the same parallel job based on availability, you only need to create one runner resource class. All ten runners would share the same token.
  • If you want to run ten separate runners that pull different jobs that do different things, we recommend creating ten different runner resource classes. Each one would have a different name and use a different token, and you would a copy of this Helm chart for each type of runner resource.
• Have a Kubernetes cluster (and nodes) you would like to install the runner pod(s) in.

1. Clone this repository.
2. Modify values as needed in values.yaml:

3. Using the resource class name and token you created in the Prerequisites section, you'll want to set parameters as you install the Helm chart:

$ helm install "circleci-runner" ./ \
  --set runnerToken=$CIRCLECI_RUNNER_TOKEN \
  --set resourceClass=$CIRCLECI_RUNNER_RESOURCE_CLASS \
  --namespace your-namespace

4. Call your runner class(es) in your job(s). Example:

version: 2.1

executors:
  my-runner:
    machine: true
    resource_class: my-namespace/my-runner-resource-class
  
workflows:
  my-workflow:
    jobs:
      - my-job

jobs:
  my-job:
    executor: my-runner
    steps:
      - checkout
      - run: echo "Hello from my custom runner!"

Environment variables can be configured in env section of the values.yaml file. Environment variables can be used to further configure the CircleCI Runner using the environment variables described in the configuration reference page. It's also possible to add additional Kubernetes secret references (see example in env section of values.yaml.

There may be cases where you do not want Helm to create the Secret resource for you. One case would be if you were using a GitOps deployment tool such as ArgoCD or Flux. In these cases you would need to create a secret manually in the same namespace and cluster where the Helm managed runner resources will be deployed.

1. Create the secret

$ kubectl create secret generic config-values \
  --namespace your-namespace \
  --from-literal resourceClass=$CIRCLECI_RUNNER_RESOURCE_CLASS \
  --from-literal runnerToken=$CIRCLECI_RUNNER_TOKEN

2. Install the Helm chart

$ helm install "circleci-runner" ./ \
  --set configSecret.create=false \
  --namespace your-namespace

There may be cases where a service account does not need to be created, or one already exists that should be reused. The values.yaml file can be modified to accommodate this scenario.

A new service account is created by default with the suggested values.yaml file. Setting the account name to circleci-runner. The serviceAccount.name value in values.yaml can be modified to a different name as required for deployment.

An existing service account can be reused by setting the serviceAccount.name parameter in the values.yaml file to the name of the existing account, and setting serviceAccount.create to false. This may be required when creating multiple helm releases from this chart.

More details about using and configuring a service account can be found in the Helm documentation.

• Customers who modify the chart beyond values in values.yaml do so at their own risk. The type of support CircleCI provides for those customizations will be limited.

• Customers are encouraged to open issues here to report bugs or problems, and open support tickets to receive specific help from support engineers.

• Autoscaling is not yet implemented - for now, you'll need to manually modify the replicaCount in values.yaml and update the cluster and run:

$ helm upgrade "circleci-runner" ./ \
  --set runnerToken=$CIRCLECI_RUNNER_TOKEN \
  --set resourceClass=$CIRCLECI_RUNNER_RESOURCE_CLASS \
  --namespace your-namespace

• Containers are not currently privileged, so you would not be able to execute privileged workloads (e.g., Docker in Docker).