Set up a release environment

Cloud

Introduction

In this tutorial you will set up an integration between CircleCI and your Kubernetes cluster. Once configured, release status can be reported to the CircleCI web app, and the following commands can be executed in your cluster by the release agent via controls in the CircleCI UI:

Restore a version
Scale a version
Restart a version
Retry a release (when using Argo Rollouts)
Promote a release (when using Argo Rollouts)
Cancel a release (when using Argo Rollouts)

Prerequisites

Before setting up your release environment with CircleCI, run through the following prerequisites:

A CircleCI account connected to your code. You can sign up for free.
A Kubernetes cluster
A project building on CircleCI that deploys to your Kubernetes cluster. See the Create a project page for steps.
You must have write access to the project associated with the component being deployed. For full details of roles and permissions for GitLab and GitHub App integrations, see the Roles and permissions overview. If your integration is through Bitbucket or the GitHub OAuth app, you will need to be an org admin in Bitbucket/GitHub respectively. To find out which GitHub integration you have, see the GitHub App integration page

CircleCI supports Kubernetes, Helm, and Argo Rollouts. The following versions have been tested and proven to work. Older versions may work but are not guaranteed:

Tool	Tested versions
Kubernetes	1.29.0 1.28.0 1.27.0
Helm	3.12.0 3.11.0
Argo Rollouts (optional)	1.6.0 1.5.0

1. Create your release environment and token

In the CircleCI web app, click Releases in the sidebar
Click Add Release Environment
Enter a name for your release environment and click Create Environment
Click to select the environment you just created
Click Create New Token and click Create Token
The new token will be displayed. Be sure to copy and save this somewhere for use in the next step. Then click Done

2. Add the release agent into your Kubernetes cluster

Use Helm to install the CircleCI release agent into your Kubernetes cluster

Add the CircleCI release agent Helm repository by running the following command:
```
helm repo add release-agent https://circleci-public.github.io/cci-k8s-release-agent
```
Then, update your local Helm chart repository cache
```
helm repo update
```

3. Install the release agent

Install the Helm chart to integrate CircleCI’s release agent into your Kubernetes cluster. Be sure to substitute the token you created in the previous step, and also, if required, include a list of Kubernetes namespaces you want to monitor.

If you only want to monitor the default namespace, you do not need to supply a list with --set manageNamespaces="{namespace1,namespace2}". The default namespace is monitored by default. If you struggle to pass the manageNamespaces value, try enclosing the array value or the whole parameter itself in a string, with double or single quotes.

helm upgrade --install circleci-release-agent-system release-agent/circleci-release-agent \
--set tokenSecret.token=[YOUR_CCI_INTEGRATION_TOKEN] --create-namespace \
--namespace circleci-release-agent-system \
--set managedNamespaces="{namespace1,namespace2}"

You can further customize the agent installation and check all available options here.

Once you have run this command, you can check your environment is set up by navigating to the environment details page to check the "last used" date has been populated:

Click Releases in the CircleCI web app sidebar
Click Configure Environments at the top left
Click on the name of your release environment to view the environment details page