Configure your Kubernetes components
The steps outlined on this page guide you to configure your Kubernetes resources for integration with your release environment.
Introduction
In this tutorial you will configure your Kubernetes components, adding labels and annotation, to enable visibility and control over your deployments.
Prerequisites
Before following the steps below, ensure the release environment is set up. Refer to the Set up a release environment page.
1. Add required labels and annotation to your Deployment/Rollout
To enable your release to show up on the releases UI in the CircleCI web app, add the following labels and annotation to your Kubernetes Deployment or Argo Rollout:
-
Specify the
circleci.com/component-name
andcircleci.com/version
label in the Kubernetes objectMetadata.Labels
-
Specify the
circleci.com/component-name
andcircleci.com/version
label in the Kubernetes objectSpec.Template.Metadata.Labels
-
Add the
circleci.com/project-id
annotation with the value set to your project IDFind your project ID:
-
Click Projects in the CircleCI web app sidebar and use the search function to find your project
-
Click the ellipsis menu next to your project and click Project Settings
-
Your project ID is available to copy from the overview page
-
For example:
apiVersion: apps/v1
kind: Deployment
metadata:
annotations:
circleci.com/project-id: <your-project-ID>
labels:
circleci.com/component-name: example-deployment
circleci.com/version: 1.0.0
name: example-deployment
namespace: default
spec:
selector:
matchLabels:
...
template:
metadata:
labels:
...
circleci.com/component-name: example-deployment
circleci.com/version: 1.0.0
Do not add circleci.com/version and circleci.com/component-name to the selector labels. These labels can not be changed later, and circleci.com//version should change for every new release. |
If you were using the release agent prior to version Support for the old labels will be dropped in one of the next releases. After migrating to the new labels, rolling back to versions that used the old labels will be supported only for deployments and rollouts managed through Helm. |
Once you have updated your Deployment or Rollout, check the CircleCI releases dashboard and you should see your release in the timeline view.
2. Link release to deployment job trigger (optional)
You can link your release with the CircleCI deployment job that triggered it. To do this, add the following annotations to your Deployment/Rollout. The method for incorporating these values and variables will depend on your configuration and tooling:
-
circleci.com/job-number
should be set to theCIRCLE_BUILD_NUM
environment variable. -
circleci.com/pipeline-id
should be set to thepipeline.id
pipeline value. -
circleci.com/workflow-id
should be set to theCIRCLE_WORKFLOW_ID
environment variable.
Once these values and variables are rendered, the configuration will look something like:
apiVersion: apps/v1
kind: Deployment
metadata:
annotations:
circleci.com/job-number: "1"
circleci.com/pipeline-id: 88dfee99-0348-407f-b113-dbf270cad093
circleci.com/workflow-id: 5b8c4de8-fd5f-4be2-80a4-3d0c03fc138c
3. Configure release management (optional)
By adding annotations to your Kubernetes objects (Deployment/Rollout), you can enable additional actions on your releases dashboard, including the ability to restore, scale, and restart component versions.
a. Use Helm rollback
This option is only available when using Helm to configure your Kubernetes resources. |
By default the built-in logic for Kubernetes Deployments or Argo Rollouts is used for the restore version feature. If you manage your component with Helm, you can choose to use the Helm rollback strategy instead. To do so, add the circleci.com/helm-revision-number
annotation to the Kubernetes object metadata in your Helm chart template:
annotations:
circleci.com/helm-revision-number: {{ .Release.Revision | quote }}
b. Custom operation timeout
This option is only available when using Helm to configure your Kubernetes resources. |
The circleci.com/operation-timeout
annotation allows a custom timeout to be specified for Helm Rollback operations performed as part of a Restore Version command. Valid values are Go duration strings (for example, 5m, 10m15s). This option is available if you are using Helm to manage your Kubernetes resources.
For example,
apiVersion: apps/v1
kind: Deployment
metadata:
annotations:
...
circleci.com/operation-timeout: 10m
c. Opt out of UI-based actions
If you would like to disable any release management features for a specific component, you can do so by adding any of the following annotations with the value false
to the related Kubernetes Deployment or Argo Rollout.
If an annotation is either not specified or is specified with any value other than false , the associated feature is enabled. Release management features are enabled by default unless explicitly disabled, as follows: |
-
circleci.com/restore-version-enabled
toggles the restore version feature on the annotated Kubernetes Deployment or Argo Rollout -
circleci.com/scale-component-enabled
toggles the scale component feature on the annotated Kubernetes Deployment or Argo Rollout -
circleci.com/restart-component-enabled
toggles the restart component feature on the annotated Kubernetes Deployment or Argo Rollout -
circleci.com/retry-release-enabled
toggles the retry release feature on the annotated Argo Rollout -
circleci.com/promote-release-enabled
toggles the promote release feature on the annotated Argo Rollout -
circleci.com/cancel-release-enabled
toggles the cancel release feature on the annotated Argo Rollout
In the following example, all features are explicitly disabled for the annotated Deployment:
apiVersion: apps/v1
kind: Deployment
metadata:
name: Demo
namespace: default
annotations:
circleci.com/restore-version-enabled: false
circleci.com/scale-component-enabled: false
circleci.com/restart-component-enabled: false
circleci.com/retry-release-enabled: false
circleci.com/promote-release-enabled: false
circleci.com/cancel-release-enabled: false
Example deployment
The following snippet shows an example deployment showing all required and optional labels and annotations.
apiVersion: apps/v1
kind: Deployment
metadata:
annotations:
circleci.com/cancel-release-enabled: "true"
circleci.com/helm-revision-number: "1"
circleci.com/job-number: "1"
circleci.com/operation-timeout: 30m
circleci.com/pipeline-id: 88dfee99-0348-407f-b113-dbf270cad093
circleci.com/project-id: 9da0c100-3295-49a4-827f-7892f3e8dc83
circleci.com/promote-release-enabled: "true"
circleci.com/restart-component-enabled: "true"
circleci.com/restore-version-enabled: "true"
circleci.com/retry-release-enabled: "true"
circleci.com/scale-component-enabled: "true"
circleci.com/workflow-id: 5b8c4de8-fd5f-4be2-80a4-3d0c03fc138c
labels:
circleci.com/component-name: example-deployment
circleci.com/version: 1.0.0
name: example-deployment
namespace: default
spec:
replicas: 3
selector:
matchLabels:
app: example-deployment
template:
metadata:
labels:
app: example-deployment
circleci.com/component-name: example-deployment
circleci.com/version: 1.0.0
spec:
containers:
- name: example-deployment
image: nginx:latest
ports:
- containerPort: 80
Next steps
In this tutorial you have configured your Kubernetes components for visibility and control from the CircleCI releases dashboard. Next, learn how to manage your releases in the Manage releases how-to guide.