無料でビルドを開始
CircleCI.comアカデミーブログコミュニティサポート

Manual install - configure your Kubernetes components

2 weeks ago4 min read
Cloud
このページの内容

The steps outlined on this page guide you to configure your Kubernetes resources for integration with your environment integration. This is an alternative to using the in-app releases set up process as described in the Set up CircleCI releases page.

Introduction

In this tutorial you will configure your Kubernetes components, adding labels and annotation to enable visibility and control over your deployments.

To set up a component for your environment, you can do one of the following:

  • Follow the steps on this page.

  • Follow the in-app component setup guide, which can be found as follows:

    1. Select Releases in the CircleCI web app sidebar

    2. Select the Components tab

    3. Select Add Component, choose your environment integration and follow the in-app guide.

Prerequisites

Before following the steps below, ensure the following:

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 and circleci.com/version label in the Kubernetes object Metadata.Labels

  • Specify the circleci.com/component-name and circleci.com/version label in the Kubernetes object Spec.Template.Metadata.Labels

  • Add the circleci.com/project-id annotation with the value set to your project ID

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

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 by adding a release job to your workflow. By adding a release job to your deployment workflow, you can also:

  • Monitor the in-cluster release process as part of the overall deployment workflow in CircleCI, making it easier to find releases for a given pipeline.

  • Orchestrate releases across multiple environments (for example, deploy to production only after a successful release in a staging environment).

To add a release job, follow these steps:

  1. Add a plan release step at the end of your existing deployment job so CircleCI knows to expect a release to happen as an outcome of that job:

    jobs:
      deploy-my-service:
        executor: some-executor
        steps:
          ...
          (existing deployment commands)
          ...
          - circleci run release plan --environment-name=some-environment-name --component-name=some-component-name --target-version=<some-version-name> <my-service-release>

    Substitute the placeholders above based on your application’s details:

    • The environment-name parameter should match the name of your environment integration created via the CircleCI UI.

    • The component-name parameter should match the name of your component as displayed in the CircleCI UI.

    • The target-version parameter should match the name of the version being released (same as the value of the circleci.com/version label)

    • The name of the "release plan" (my-service-release in the example above) can be any arbitrary value you would like. The release plan name is used to reference the "release plan" as part of the release job config.

      [Optional] You can also add the following parameters if required:

    • namespace - Use this parameter to use a value other than default.

    • release-strategy - Use this parameter to provide a value other than deployment (available options are deployment and progressive).

  2. Define a new job to monitor the release, referencing the release plan created above as part of the deployment job:

    jobs:
      release-my-service:
        type: release
        plan_name: <my-service-release>
  3. Add this new job to your workflow, referencing your deployment job as a dependency:

    workflows:
      deploy-service:
        jobs:
          - deploy-my-service
          - release-my-service:
              requires:
                - deploy-my-service

The final configuration will look something like:

jobs:
  deploy-my-service:
    executor: some-executor
    steps:
      - ./deploy.sh
      - circleci run release plan --environment-name=some-environment-name --component-name=some-component-name --target-version=some-version-name my-service-release
  release-my-service:
    type: release
    plan_name: my-service-release

workflows:
  deploy-service:
    jobs:
      - deploy-my-service
      - release-my-service:
          requires:
            - deploy-my-service

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

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

All UI-based release management features are enabled by default, no action is required to enable them.

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.

  • 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 with all required labels and annotations. In this example the Cancel Release option in the UI has been disabled.

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    circleci.com/cancel-release-enabled: "false"
    circleci.com/helm-revision-number: "1"
    circleci.com/job-number: "1"
    circleci.com/operation-timeout: 30m
    circleci.com/project-id: 9da0c100-3295-49a4-827f-7892f3e8dc83
  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.


Suggest an edit to this page

Make a contribution
Learn how to contribute