Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Releases overview - Open preview

3 months ago7 min read
Cloud

Visualise and control your deployments with CircleCI release environments. The CircleCI releases feature currently supports deployments to Kubernetes, and Amazon SageMaker.

Introduction

CircleCI release environments give you visibility into your Kubernetes deployments in the CircleCI web app, as well as access to commands for release management. From the CircleCI web app, you can:

  • Restore version

  • Scale component

  • Restart component

We support Argo Rollouts for progressive delivery. Currently the canary deployment strategy is supported, but in a future release blue-green will also be supported. Some further controls are available for projects that use Argo Rollouts:

  • Retry release

  • Promote release

  • Cancel release

Quickstart

If you want to get started with CircleCI releases for Kubernetes right away, you can jump to:

To get set up with releases for Amazon SageMaker, refer to the Deploy to Amazon SageMaker page.

How it works

CircleCI integrates with your Kubernetes cluster to give you visibility and control over your release process through the CircleCI web app. We currently support Kubernetes Deployments and Argo Rollouts.

Diagram showing the architecture of CircleCI releases

Configure a release environment to install the CircleCI release agent into your Kubernetes cluster. Configure the release agent to only monitor the namespaces you require.

Developers can monitor releases in the CircleCI web app, and run commands to manage those releases from the UI. Commands are monitored by CircleCI and relayed to the release agent, which then runs the commands for you.

Requirements

Tooling

The following versions have been tested and proven to work. Older versions may work but are not guaranteed.

ToolTested versions

Kubernetes

1.27.0
1.26.0

Helm

3.12.0
3.11.0

Argo Rollouts (optional)

1.6.0
1.5.0

Labels and annotations

The following table shows a complete list of labels and annotations either required or available for configuring your release environment.

Label/annotationValueRequired?

Metadata.Labels

app

A name for your application

Yes

Metadata.Labels

version

Current version

Yes

Spec.Template.Metadata.Labels

app

See above

Yes

Spec.Template.Metadata.Labels

version

See above

Yes

Metadata.Annotations

circleci.com/job-number

CIRCLE_BUILD_NUM environment variable

No. Used to enable linking between deploy job and release

Metadata.Annotations

circleci.com/pipeline-id

pipeline.id pipeline value

No. Used to enable linking between deploy job and release

Metadata.Annotations

circleci.com/workflow-id

CIRCLE_WORKFLOW_ID environment variable

No. Used to enable linking between deploy job and release

Metadata.Annotations

circleci.com/project-id

Project ID for the CircleCI project associated with the job that deploys your component

No. Used to enable release management controls

Metadata.Annotations

circleci.com/operation-timeout

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.

Metadata.Annotations

circleci.com/restore-version-enabled

false

No. Only set if you want to disable the restore version feature for your component.

Metadata.Annotations

circleci.com/scale-component-enabled

false

No. Only set if you want to disable the scale component feature for your component.

Metadata.Annotations

circleci.com/restart-component-enabled

false

No. Only set if you want to disable the restart component feature for your component.

Metadata.Annotations

circleci.com/retry-release-enabled

false

No. Only set if you want to disable the retry release feature for your component.

Metadata.Annotations

circleci.com/promote-release-enabled

false

No. Only set if you want to disable the promote release feature for your component.

Metadata.Annotations

circleci.com/cancel-release-enabled

false

No. Only set if you want to disable the cancel release feature for your component.

Concepts

The following sections describe concepts that will help you fully understand your release environment, and how releases fit with your CI/CD pipeline.

Component

A component in CircleCI is a collection of code and configuration that is deployed and released as a single unit. In Kubernetes terms, this would be a Deployment or Rollout object along with the related objects such as Pods, ReplicaSets, etc. that share a common app label.

Delivery

Delivery is the act of packaging code changes and making them available for Deployment. Continuous delivery is the prerequisite step for continuous deployment. With some variations on the technologies being used, the delivery process creates executables from code and then makes them available from a repository to be deployed to an environment at a subsequent time.

Deployment

Deployment is the act of putting a new component version into a particular environment, regardless of whether users and other services immediately interact with the new version or a previous one. Depending on the type of deployment, a release may happen as a later task (such as switching over traffic shaping rules for a blue/green deployment) or as a direct consequence of the deployment (such as a standard Kubernetes rolling update).

Command

A command is a user-initiated action CircleCI performs on the user’s behalf to manipulate a specific component. These actions are run asynchronously via our release agent and the results are reported back to the CircleCI web app where you can see them in the releases dashboard, similar to how step output works for CI jobs.

Some commands are available for all components. These are:

  • Restore version

  • Scale component

  • Restart component

A subset of commands are available for progressive releases (when using Argo Rollouts). These are:

  • Retry release

  • Promote release

  • Cancel release

Release

A release is the act of updating a component to a new version in a specific environment, causing it to become available to an audience of users and other services.

A release can happen when an existing component is updated or when the first version for a new component is deployed.

In the releases dashboard, releases are tagged as Progressive if they refer to an Argo Rollout.

A release starts when the component version is updated, and ends when the new version has reached 100% availability, and all associated validations have been completed. In the case of a progressive release, this happens when the Rollout completes. In the case of a Deployment, this happens when the Deployment replicas are all available and ready.

Release status

Releases can be in one of the following states:

StatusNotes

RUNNING

The release is currently in progress

FAILED

Resources have reached an unhealthy status (pods for the new version of a Kubernetes component)

SUCCESS

The Deployment or Rollout has all desired resources available (all pods specified by a Kubernetes Deployment or Argo Rollout)

CANCELLED

The release has been cancelled, either using the cancel release option, or by being superseded by another release

EXPIRED

Release commands failed to be picked up by the release agent within the required time window

Coming soon

A number of features and improvements are planned to be added through open preview and beyond:

  • Display release environment details in the CircleCI web app

  • Guided release environment setup experience in the CircleCI web app

  • Blue Green deployments via Argo Rollouts

  • Connect releases to your CircleCI workflows

  • Display Argo Rollouts analysis run details in the CircleCI web app

  • Improved searching and filtering on the release dashboard

Known limitations

  • Restarting the release agent while a release is ongoing will cause the release agent to lose track of the release status and fail to update the CircleCI services accordingly.

Troubleshooting

Why is my Deployment/Rollout not showing up in the components tab or releases timeline view?

  • Check that the Deployment/Rollout is annotated with the required labels. More information is available in the Set up guides. If the required labels were not present, then adding them should solve the problem.

  • If you are using a Deployment, check that the desired replicas is not set to 0. Deployments with 0 replicas are not reported as releases, even if they are scaled up subsequently. The configured value can be seen on the release agent deployment in the circleci-release-agent-system namespace. Here is an example in which the number of desired replicas is 2:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: sample-deployment
      namespace: sample-namespace
    spec:
      replicas: 2
  • Check that the Deployment/Rollout is in a namespace managed by the release agent. This can be verified by checking the MANAGED_NAMESPACES environment variable on the release agent deployment in the circleci-release-agent-system namespace. Here is an example in which only the default namespace is being managed:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: circleci-release-agent
      namespace: circleci-release-agent-system
    spec:
      template:
        spec:
          containers:
          - env:
            - name: MANAGED_NAMESPACES
              value: default

Why is my release is stuck in the Running state?

  • If you are using a Deployment, check whether it was deleted before the release could complete. In this scenario, this is an expected behavior. This experience will be improved upon in future release agent updates.

  • If you are using a Deployment, check whether the release agent restarted before all pods for the deployment could become ready. This is a known limitation that will be addressed in future updates of the release agent. Restarting a release agent while a release is ongoing will cause the release agent to lose track of the release status and fail to update the CircleCI services accordingly.

Why are no new releases are showing up? and/or why are component versions not being updated?

  • Check whether the token used by the release agent has been revoked:

    1. Select Releases in the CircleCI web app sidebar

    2. Click Configure Environments to enter the release environments view

    3. Click to select your environment to view valid token details, including when the token was last used.

      If the token has been last used longer than a minute ago, then this is likely to be the problem.

  • Check whether tokens are being shared between multiple release environments. This is not supported. Check this by following these steps:

    1. Retrieve the token value from the token field in the circleci-release-agent secret in the circleci-release-agent-system namespace

    2. Compare the value with the partially obscured value for the available Tokens in the CircleCI web app

      If the token does not show up in the list, then it has been revoked or the value configured on the release agent is incorrect. In either case, creating a new token and reinstalling the Release Agent with the new value should solve the issue.

Why is restore version using Helm is timing out?

The time required for a Helm-based restore version to complete successfully is dependent on the specific configuration of the target component. For example, a large number of replicas will lead to a longer duration, which could cause a timeout. It is possible to specify a different timeout by adding the circleci.com/operation-timeout annotation to the Rollout or Deployment. The default value for this is 10 minutes. For steps see the Configure your Kubernetes components page.

Why is the restore version button not available for a component version?

Check whether the component has been undeployed. If there are currently no live versions for a component, the Restore Version button will not be visible for that component until at least one version has been deployed.

Why are all buttons (Promote, Promote All and Cancel) disabled for a release?

Check whether the release is a Rollback. If this is the case, then this is a known issue that will be solved in a future update to the CircleCI release agent.

Why are all commands for my component failing?

Check if the error message is “invalid or missing project ID“. In this case the component is missing a valid Project ID.


Suggest an edit to this page

Make a contribution
Learn how to contribute