cci-k8s-release-agent
CircleCI Kubernetes Release Agent Helm Chart
A Helm chart for installing CircleCI’s Kubernetes release agent.
Prerequisites
We generally support the two latest minor versions of Kubernetes, Helm, and Argo Rollouts (optional).
- Kubernetes:
- v1.32.0
- v1.31.0
- v1.30.0
- Helm:
- v3.17.0
- v3.16.0
Optional
- Argo Rollouts
- v1.8.0
- v1.7.0
Installing the Agent
Agent Image
Our Kubernetes Release Agent Images are available from CircleCI’s public Docker Hub registry, located here: https://hub.docker.com/r/circleci/k8s-release-agent/tags
The default image for this chart version is:
circleci/k8s-release-agent:1.4.0
Agent Integration Token
The required token can be obtained by navigating to the Releases view of the CircleCI web application, clicking on Configure Integrations in the top-right, and then Configure New Integration.
Ensure that the generated token is accessible for the installation process.
Installing via Helm Chart
- Add the Helm chart repository:
helm repo add release-agent https://circleci-public.github.io/cci-k8s-release-agent - Update your local Helm chart repository cache:
helm repo update - Install the Helm chart:
helm upgrade --install cci-release-agent release-agent/circleci-release-agent \ --set tokenSecret.token=[YOUR_CCI_INTEGRATION_TOKEN] --create-namespace \ --set "managedNamespaces={namespace1,namespace2}" \ --namespace circleci-release-agent-system
Advanced Configuration Examples
Full Configuration with Command-Line Flags
This example demonstrates how to install the agent with all advanced features including priority classes, affinity rules, tolerations, job-specific labels, and a PodDisruptionBudget:
helm upgrade --install cci-release-agent release-agent/circleci-release-agent \
--set tokenSecret.token=[YOUR_CCI_INTEGRATION_TOKEN] \
--set "managedNamespaces={default}" \
--set priorityClassName=high-priority \
--set "affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[0].weight=1" \
--set "affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[0].preference.matchExpressions[0].key=node-type" \
--set "affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[0].preference.matchExpressions[0].operator=In" \
--set "affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[0].preference.matchExpressions[0].values[0]=agent" \
--set "tolerations[0].key=node-type" \
--set "tolerations[0].operator=Equal" \
--set "tolerations[0].value=agent" \
--set "tolerations[0].effect=NoSchedule" \
--set job.priorityClassName=high-priority \
--set "job.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[0].weight=1" \
--set "job.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[0].preference.matchExpressions[0].key=node-type" \
--set "job.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[0].preference.matchExpressions[0].operator=In" \
--set "job.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[0].preference.matchExpressions[0].values[0]=job" \
--set-string "job.labels.example\.com/do-not-disrupt=true" \
--set-string "job.tolerations[0].key=job-node" \
--set-string "job.tolerations[0].operator=Equal" \
--set-string "job.tolerations[0].value=true" \
--set-string "job.tolerations[0].effect=NoSchedule" \
--set podDisruptionBudget.enabled=true \
--set podDisruptionBudget.minAvailable=1 \
--namespace circleci-release-agent-system \
--create-namespace
Full Configuration with Values File
Alternatively, you can create a values.yaml file with the same configuration:
tokenSecret:
token: [YOUR_CCI_INTEGRATION_TOKEN]
managedNamespaces:
- default
# Agent pod configuration
priorityClassName: high-priority
affinity:
nodeAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 1
preference:
matchExpressions:
- key: node-type
operator: In
values:
- agent
tolerations:
- key: node-type
operator: Equal
value: agent
effect: NoSchedule
# Command processing job configuration
job:
priorityClassName: high-priority
labels:
example.com/do-not-disrupt: "true"
affinity:
nodeAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 1
preference:
matchExpressions:
- key: node-type
operator: In
values:
- job
tolerations:
- key: job-node
operator: Equal
value: "true"
effect: NoSchedule
# PodDisruptionBudget configuration
podDisruptionBudget:
enabled: true
minAvailable: 1
Then install using:
helm upgrade --install cci-release-agent release-agent/circleci-release-agent \
-f values.yaml \
--namespace circleci-release-agent-system \
--create-namespace
Configuration Explanation
- priorityClassName: Sets the priority class for agent pods, ensuring they are scheduled appropriately
- job.priorityClassName: Sets the priority class for command processing job pods
- affinity/job.affinity: Controls pod placement preferences (e.g., prefer specific node types)
- tolerations/job.tolerations: Allows pods to be scheduled on nodes with matching taints
- job.labels: Adds labels to command job pods only (e.g.,
do-not-disruptlabels to prevent disruption during releases) - podLabels: Adds labels to agent pods and are inherited by command job pods
- podDisruptionBudget: Ensures minimum availability during voluntary disruptions (e.g., node drains)
Note: When using command-line --set flags with zsh, wrap arguments containing square brackets in quotes. Use --set-string for values that should remain strings (like boolean label values).
Important Update for Upgrading Users
We have made a small but significant change in the helm installation command that you need to be aware of.
The argument name manageNamespaces has been corrected to managedNamespaces. The corrected command is shown above.
Please make sure to use managedNamespaces instead of manageNamespaces when installing or upgrading to the newer versions of the software. If you have any scripts or automation that includes the previous command, they need to be updated to use managedNamespaces.
Updating the Agent
- Update your local Helm cache:
helm repo update - Upgrade to the new version:
helm upgrade --install cci-release-agent release-agent/circleci-release-agent \ --set tokenSecret.token=[YOUR_CCI_INTEGRATION_TOKEN] --create-namespace \ --set "managedNamespaces={namespace1,namespace2}" \ --namespace circleci-release-agent-system
Values
| Key | Type | Default | Description |
|---|---|---|---|
| affinity | object | {} |
Specifies affinity for CircleCI Release Agent pods |
| agentAnnotations | object | {} |
Allows setting additional annotations for CircleCI Release Agent deployment |
| agentLabels | object | {} |
Allows setting additional labels for CircleCI Release Agent deployment |
| agentNamespace | string | "circleci-release-agent-system" |
Define the namespace to be used for the CircleCI Release Agent. if the namespace is defined while using helm upgrade or helm install commands then that value is used intead of this. |
| baseUrl | string | "https://internal.circleci.com/" |
The host of the CircleCI Releases API server |
| env | list | [] |
Define any environment variables to be passed to the agent |
| fullnameOverride | string | "" |
Override the fully qualified app name |
| helm.driver | string | "secret" |
Specifies the Helm storage backend Ref: https://helm.sh/docs/topics/advanced/#storage-backends |
| helm.timeout | string | "10m" |
Specifies the time to wait for Helm operations Ref: https://helm.sh/docs/intro/using_helm/#helpful-options-for-installupgraderollback |
| image.pullPolicy | string | "IfNotPresent" |
The pull policy for the CircleCI Release Agent image |
| image.pullSecrets | list | [] |
Optional list of references to image repository secrets in the same namespace (e.g. Docker registry credentials) |
| image.repository | string | "circleci/k8s-release-agent" |
Repository to use for CircleCI Release Agent image |
| image.tag | string | "1.4.0" |
Specify the CircleCI Release Agent version to use |
| job | object | {"affinity":{},"labels":{},"priorityClassName":"","tolerations":[]} |
Configuration for command processing jobs spawned by the release agent |
| job.affinity | object | {} |
Specifies affinity for command job pods |
| job.labels | object | {} |
Allows setting additional labels for command job pods only (e.g. do-not-disrupt labels to avoid disruption during releases) |
| job.priorityClassName | string | "" |
Specifies the priority class name for command job pods |
| job.tolerations | list | [] |
Specifies tolerations for command job pods |
| logging.level | string | "error" |
|
| managedNamespaces | list | ["default"] |
Specifies the list of namespaces to be monitored by the CircleCI Release Agent |
| nameOverride | string | "" |
Override the name of the app |
| podAnnotations | object | {} |
Allows setting additional annotations for CircleCI Release Agent pods |
| podDisruptionBudget | object | {"enabled":false,"maxUnavailable":null,"minAvailable":1} |
Specifies PodDisruptionBudget configuration |
| podDisruptionBudget.enabled | bool | false |
Specifies whether to create a PodDisruptionBudget |
| podDisruptionBudget.maxUnavailable | string | nil |
Maximum number of pods that can be unavailable during a disruption |
| podDisruptionBudget.minAvailable | int | 1 |
Minimum number of pods that must be available during a disruption |
| podLabels | object | {} |
Allows setting additional labels for CircleCI Release Agent pods. These labels are also inherited by command job pods spawned by the release agent. |
| priorityClassName | string | "" |
Specifies the priority class name for CircleCI Release Agent pods |
| rbac | object | {"clusterRoles":true,"create":true,"extraPermissions":[],"includeArgoRolloutsPermissions":true} |
Specifies the RBAC configuration |
| rbac.clusterRoles | bool | true |
Specifies whether to create the RBAC cluster roles. When set to false, RBAC roles will be created for each of the specified namespaces in `` |
| rbac.create | bool | true |
Specifies whether to create the RBAC resources |
| rbac.extraPermissions | list | [] |
Extra permissions added to the RBAC configuration (Useful when a component is packaged along with custom resources and the rollback operation requires them to restored atomically, such as when using Helm.) |
| rbac.includeArgoRolloutsPermissions | bool | true |
Enable this if at least one of the components are managed by Argo Rollouts |
| replicas | int | 2 |
Number of instances of CircleCI Release Agent |
| resources | object | {} |
Custom container resources request and limit for the CircleCI Release Agent |
| serviceAccount.annotations | object | {} |
Allows setting additional annotations for the service account |
| serviceAccount.create | bool | true |
Specifies whether to create a service account |
| serviceAccount.name | string | "circleci-release-agent" |
The service account name to be used |
| tokenSecret.create | bool | true |
Specifies whether to create a CircleCI Release Agent token secret |
| tokenSecret.token | string | nil |
Your CircleCI Release Agent token |
| tolerations | list | [] |
Specifies tolerations for CircleCI Release Agent pods |