Set up the CircleCI release agent
2 days ago
Visualise and control deployments to your Kubernetes cluster with the CircleCI release agent. The steps outlined on this page guide you to set up the CircleCI release agent for deploy management and monitoring using the CircleCI web app onboarding process. Alternatively, once you have set up an environment integration, you can follow the guides linked below to install the release agent and configure components manually.
Introduction
In this tutorial you will set up an integration between CircleCI and your Kubernetes environment. Deploy status is reported to the CircleCI web app, and the following commands are executable in your cluster or service by the release agent via controls in the CircleCI UI:
-
Restore a version
-
Scale a version
-
Restart a version
-
Retry a Rollout (when using Argo Rollouts)
-
Promote a Rollout (when using Argo Rollouts)
-
Cancel a Rollout (when using Argo Rollouts)
Prerequisites
Before setting up your environment integration 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.
The following versions of Kubernetes, Helm, and Argo Rollouts have been tested and proven to work. Older versions may work but are not guaranteed:
| Tool | Tested versions |
|---|---|
Kubernetes |
1.29.0 |
Helm |
3.12.0 |
Argo Rollouts (optional) |
1.6.0 |
Labels and annotations
The following table shows a complete list of labels and annotations either required or available for configuring your environment integration. You will be guided to set these up in the in-app setup process. These are not strictly a prerequisite but will be required for the release agent to work correctly.
| Label/annotation | Value | Required? | |
|---|---|---|---|
|
|
A name for your application |
Yes |
|
|
Current version |
Yes |
|
|
See above |
Yes |
|
|
See above |
Yes |
|
|
Project ID for the CircleCI project associated with the job that deploys your component |
Yes |
|
|
A Go duration string, for example, 5m, 10m15s |
No. Only needed to set a custom timeout duration. This option is only available if you are using Helm to configure your Kubernetes resources. |
|
|
|
No. Only set if you want to disable the restore version feature for your component. |
|
|
|
No. Only set if you want to disable the scale component feature for your component. |
|
|
|
No. Only set if you want to disable the restart component feature for your component. |
|
|
|
No. Only set if you want to disable the retry deployment feature for your component. |
|
|
|
No. Only set if you want to disable the promote deployment feature for your component. |
|
|
|
No. Only set if you want to disable the cancel deployment feature for your component. |
Set up the CircleCI release agent
-
In the CircleCI web app, select Deploys in the sidebar.
-
Choose the Environments tab and select Create environment integration.
-
Enter a name for your environment, and a description if you would like.
-
Use the dropdown menu to choose your environment integration type: Kubernetes Cluster, then select Next: Release Agent Setup.
-
To install the release agent into your cluster and set up your components, follow the in-app setup steps. If you would rather continue the setup process manually, see the Optional manual setup section on this page.
The in-app setup is now spread across two pages:
-
Release agent setup, which has the following steps:
-
Add CircleCI’s release agent Helm repository.
-
Install CircleCI’s release agent into your Kubernetes cluster with Helm.
-
-
Component setup, which has the following steps:
-
Add CircleCI components and enable deployment tracking.
-
Display component deployment trigger (optional).
-
Configure component deployment actions (optional).
-
-
After completing all the setup steps in the app, you will have done the following:
-
Set up an environment integration.
-
Installed the release agent into your Kubernetes cluster
-
Configured your Kubernetes components.
Alternatively, you can find manual set up instruction for your Kubernetes components in the Configure your Kubernetes components page.
Optional manual setup
This section shows how to manually install the CircleCI release agent into your Kubernetes cluster. This manual installation guide is an alternative to using the in-app deploys set up process as described in the sections above.
1. 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
2. Create an integration token
You will need a CCI_INTEGRATION_TOKEN to install the CircleCI release agent into your cluster. To create an integration token, follow these steps:
-
In the CircleCI web app, select Deploys in the sidebar.
-
Navigate to the Environments tab.
-
Select the gear icon
corresponding to the environment you just created to enter the Environment Integration Settings page. -
Select Create Integration Token and then Create Token
-
The new token will be displayed. Be sure to copy and save this somewhere for use in the next step. Then select Done
3. Install the release agent
Use the following command to install the Helm chart to integrate CircleCI’s release agent into your Kubernetes cluster.
If required, you can 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. It navigate to the environment details page, follow these steps:
-
Select Deploys in the CircleCI web app sidebar.
-
Select the Environments tab.
-
Select the name of your environment integration to view the environment details page.