Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Configure your Kubernetes components - Open preview

4 months ago3 min read
Cloud
On This Page

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 annotations to enable visibility and control over your deployments.

Prerequisites

Before following the steps below, ensure the release environment has been set up successfully. Refer to the Set up a release environment page.

1. Add required labels to your Deployment/Rollout

To enable your release to show up on the releases dashboard in the CircleCI web app, add the following labels to your Kubernetes Deployment or Argo Rollout:

  • Specify the app and version label in the Kubernetes object Metadata.Labels

  • Specify the app and version label in the Kubernetes object Spec.Template.Metadata.Labels

For example:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: example-deployment
    version: 1.0.0
  name: example-deployment
  namespace: default
spec:
  selector:
    matchLabels:
      app: example-deployment
  template:
    metadata:
      labels:
        app: example-deployment
        version: 1.0.0

Once you have updated your Deployment or Rollout, check the CircleCI releases dashboard and you should see your release in the timeline view.

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 you config and tooling:

Once these values and variables are rendered, the config 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 an annotation to your Kubernetes objects (Deployment/Rollout), you can enable additional actions on your releases dashboard. This includes restoring, scaling, and restarting component versions. To get started, add the circleci.com/project-id annotation with the value found on the relevant CircleCI project settings page.

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    ...
    circleci.com/project-id: 9da0c100-3295-49a4-827f-7892f3e8dc83

To find your project ID:

  1. Click Projects in the CircleCI web app sidebar

  2. Use the search function to find your project

  3. Click the ellipsis menu next to your project and click Project Settings

  4. Your project ID is available to copy from the overview page

    Screenshot showing where to find the project ID

a. Use Helm rollback

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

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.

  • 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:
    app: example-deployment
    version: 1.0.0
  name: example-deployment
  namespace: default
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example-deployment
  template:
    metadata:
      labels:
        app: example-deployment
        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.


Suggest an edit to this page

Make a contribution
Learn how to contribute