Deployment and deploy management overview
7 days ago
With CircleCI you can deploy to any target and manage your deployments in the CircleCI web app. Track deployments using deploy markers and rollback deployments to a previous version.
Introduction
Once a software application has been developed and tested, it needs to be deployed and made available for its intended audience. With CircleCI, you can deploy to virtually any target and configure CircleCI to integrate with other services for:
-
QA and testing.
-
Feature management.
-
Deployment strategies such as canary deployment.
Customize your configuration to match your requirements, whether you need a fully automated process or one that requires manual approval.
Set up deploy markers to track deployments in the CircleCI web app and rollback to previous versions as required.
The basics of deployment
Here are the core concepts you need to get a deployment set up:
-
Deployment job: To deploy your application, add a job to your
.circleci/config.ymlfile and configure the job to run the steps you require.Add a deployment log step to your deployment job to view a log of deployments in the CircleCI web app. See the Deployment markers guide to learn more. -
Deployment parameters: You may need to add environment variables and SSH keys to fulfill your deployment steps. Environment variables can be:
-
Defined within your configuration
-
Added to the project itself through the CircleCI web app:
-
Add project-level environment variables
-
Add project-level SSH keys.
-
-
-
Manual approval: If your deployment strategy requires a manual approval step, you can include a hold/approve job in your workflow. This job will create a manual approval button visible in the CircleCI web app workflows map.
If you need to restrict connections, consider enabling IP ranges for your deployment job.
Using orbs to simplify deployment
Orbs are packages of reusable configuration. For simpler deployment pipelines, you can use orbs to achieve the results you need with minimal configuration. Orbs are available for many common deployment targets.
For example, the AWS CodeDeploy orb has a pre-configured deploy job that you can include in your configuration with the single line: aws-code-deploy/deploy. Orb jobs can be used once the orb has been invoked by adding the orbs stanza:
version: 2.1
orbs:
aws-code-deploy: circleci/aws-code-deploy@x.y
aws-cli: circleci/aws-cli@x.z
workflows:
deploy_application:
jobs:
- aws-code-deploy/deploy:
auth:
- aws-cli/setup
application-name: myApplication
bundle-bucket: myApplicationS3Bucket
bundle-key: myS3BucketKey
deployment-group: myDeploymentGroup
service-role-arn: myDeploymentGroupRoleARNUnder the hood, this orb creates, bundles, and deploys your application using your specified parameters set under the aws-code-deploy/deploy job declaration.
Check out the full range of available orbs in the orbs registry. If the orb you need has not been created yet, consider authoring one!
Using images to simplify deployment
CircleCI provides maintained Docker images (convenience images) that contain the tools required for common deployment scenarios. Convenience images provide fast spin-up times, reliability, and stability. Visit the CircleCI Developer Hub to learn more about each convenience image:
Handling common deployment scenarios
Use the how-to guides in this section (select how-to guides from the left-hand navigation) to manage common deployment use cases.
Go to the orbs registry to simplify your configuration by using an orb for your deployment target.
Deploys management
CircleCI deploys gives you visibility into your deployments within the CircleCI web app. When setting up deploys you will add CLI commands to your config to enable logging and tracking of deploys and deployment status in the CircleCI UI. Use rollbacks to rollback to a previous version of a component.
If you are deploying to Kubernetes you can choose to use the CircleCI release agent, which you install in your cluster to enable you to manage your deployments through CircleCI. If you choose the release agent approach, you will have access to the following deploy management tools from CircleCI:
-
Restore version
-
Scale component
-
Restart component
The release agent supports Argo Rollouts for progressive delivery. Currently the canary deployment strategy is supported. Some further controls are available for projects that use Argo Rollouts:
-
Retry Rollout
-
Promote Rollout
-
Cancel Rollout
Quickstart
To get started with CircleCI deploys right away, refer to the following guides:
If you would like to install the release agent in your cluster, refer to the following guides:
Release agent overview
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.
Configure environment integrations to install the CircleCI release agent into your Kubernetes clusters. Configure the release agent to only monitor the namespaces you require.
Developers can monitor deployments in the CircleCI web app, and run commands to manage those deployments from the UI. Commands are monitored by CircleCI and relayed to the release agent, which then runs the commands for you.
Concepts
The sections below explain some key software delivery concepts. Understanding these concepts will help you take full advantage of CircleCI deploys.
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 circleci.com/component-name 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 to be deployed to an environment at a subsequent time.
Deployment
Deployment is the act of putting a new component version into an environment, regardless of whether users and other services interact with the new version or a previous one. Depending on the deployment type, a release may happen either:
-
As a later task, such as switching over traffic shaping rules for a blue/green deployment.
-
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. Actions are run asynchronously via our release agent and the results are reported back to the CircleCI web app. You can see the results in the deployments dashboard, similarly 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 deployments (when using Argo Rollouts). These are:
-
Retry deployment
-
Promote deployment
-
Cancel deployment
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 deploys dashboard, deployments are tagged as Progressive if they refer to an Argo Rollout.
A deployment 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 deployment, this happens when the Rollout completes. In the case of a Kubernetes Deployment, this happens when the Deployment replicas are all available and ready.
The deploys UI
The CircleCI deploys UI is a powerful tool for visualising, monitoring and managing your deployments. The pages included in the deploys UI are described below.
The dashboard
Select Deploys in the CircleCI web app sidebar to enter the deploys dashboard. The dashboard shows the following:
-
Timeline: A timeline of deploys across your organization’s components and environments. You can use the filter dropdown menus at the top of the page to select a component and/or environment. You will see live status updates, deployment trigger source, deployment version version, deployment type (for example, progressive, when you are using an Argo Rollout). From here you can access the following:
-
The deployment details page for a specific deployment by clicking on the status badge or version number.
-
The component or environment details pages by clicking on the respective names.
-
The project dashboard for the CircleCI project associated with a deployment.
-
The job details page for the job that started the deployment.
-
The commit details page in your VCS for the commit that started the deployment.
-
-
Environments: List of environment integrations set up for your organization. From here you can:
-
Set up a new environment integration by selecting Create Environment Integration.
-
Access settings for each environment
. -
Access the environment details view by selecting an environment name.
-
-
Components: A list of components and their associated projects. From here you can:
-
Set up a new component by selecting Create Component. From here you can select and environment that has a successful environment integration set up, and from there you can add a new component.
-
Get straight to the component’s project building on CircleCI by selecting the project name.
-
Access setting for each component
.
-
Filter and group components and environments with labels
Add labels to your components and environments to provide teams with a way to filter and group content in the deploys UI. Once a label is added, you can use this to filter your view to focus on the content relevant to your team.
Labels are composed of two values separated by a colon, for example, team:my-team-name. To specify multiple labels for a component or environment, you can separate them with a comma. For example, team:my-team-name, role:web. You can add up to 20 labels to a component or environment.
Use labels to filter components and environments
Once you have added labels to your components and environments, you can use them to filter your view in the deploys UI. In the timeline, environments, or components view, select a filter to reduce the content in the tab to only your selection. You can also use the label filter dropdown menu at the top of the page.
Add or edit labels
To add or edit labels follow the steps below.
Component labels
To add or edit labels for a component, follow these steps:
-
Select Deploys in the CircleCI web app sidebar.
-
You are now in the timeline view. Select the Components tab.
-
Select the cog icon
for your component. You can use the filter at the top of the page to help find the component you want. -
You are now on the component settings page. Select the edit button
in the labels panel. -
Enter or edit your label(s) and select Done.
Environment labels
To add or edit labels for an environment, follow these steps:
-
Select Deploys in the CircleCI web app sidebar.
-
You are now in the timeline view. Select the Environments tab.
-
Select the cog icon
for your environment. -
You are now on the environment settings page. Select the edit button
in the labels panel. -
Enter or edit your label(s) and select Done.
View all deployments for an environment
To view all deployments for an environment, follow these steps:
-
Select Deploys in the CircleCI web app sidebar.
-
You are now in the timeline view. Select the Environments tab.
-
Select your environment by name.
-
You are now on the environment details page. Select the Deployments tab to view a list of all deployments for your chosen environment.
View all commands run for an environment
To view all commands run for an environment, follow these steps:
-
Select Deploys in the CircleCI web app sidebar.
-
You are now in the timeline view. Select the Environments tab.
-
Select your environment by name.
-
You are now on the environment details page. Select the Commands tab to view a list of all commands that have been run for your chosen environment.
View all deployments for a component
To view all deployments for a component, follow these steps:
-
Select Deploys in the CircleCI web app sidebar.
-
You are now in the timeline view. Select the Components tab.
-
Select your component by name. You can use the filter at the top of the page to help.
-
You are now on the component details page. Select the Deployments tab to view a list of all deployments for your chosen component.
View all commands run for a component
To view all commands run for a component, follow these steps:
-
Select Deploys in the CircleCI web app sidebar.
-
You are now in the timeline view. Select the Components tab.
-
Select your component by name. You can use the filter at the top of the page to help.
-
You are now on the component details page. Select the Commands tab to view a list of all commands run for your chosen component.
Requirements
The following section describes the requirements for using the release agent.
Tooling
We test the versions listed here. Older versions may work but are not guaranteed.
| Tool | Tested versions |
|---|---|
Kubernetes |
1.29.0 |
Helm |
3.12.0 |
Argo Rollouts (optional) |
1.6.0 |
Labels and annotations
The following table shows a complete list of labels and annotations either required or available for configuring your environment integration.
| Label/annotation | Value | Required? | |
|---|---|---|---|
|
|
A name for your application |
Yes |
|
|
Current version |
Yes |
|
|
See above |
Yes |
|
|
See above |
Yes |
|
|
Project ID for the CircleCI project associated with the job that deploys your component |
Yes |
|
|
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. |
|
|
|
No. Only set if you want to disable the restore version feature for your component. |
|
|
|
No. Only set if you want to disable the scale component feature for your component. |
|
|
|
No. Only set if you want to disable the restart component feature for your component. |
|
|
|
No. Only set if you want to disable the retry deployment feature for your component. |
|
|
|
No. Only set if you want to disable the promote deployment feature for your component. |
|
|
|
No. Only set if you want to disable the cancel deployment feature for your component. |
Deploy markers
Deploy markers provide a lightweight way to log your deployments. Deploy markers generate a log of all deployments in one place, for a clear overview of what has changed, without the need to search through your CI/CD pipelines. Deploy markers log all new deployments in one place and link back to the CI/CD pipelines that caused them.
See the Configure deploy markers page for full setup details.
Deploy status
A deployment can be in one of the following states:
| Status | Notes |
|---|---|
RUNNING |
The deployment 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 deployment has been cancelled, either using the |
EXPIRED |
Deployment commands failed to be picked up by the release agent within the required time window. |
LOGGED |
Deployment has been logged using a deploy marker and is available in the CircleCI deploys UI. |
Known limitations
-
Restarting the release agent while a deployment is ongoing causes the release agent to lose track of the deployment status and fail to update the CircleCI services accordingly.
-
In the CircleCI deploys UI it is currently possible for you to attempt to restore a version that does not exist. All deployments are presented in the UI, including those outside of the scope of any version history limits you might have set. We do not currently filter out deployments for which there is no longer any data.
Depending on your setup, you will have options for configuring revision history limits:
revisionHistoryLimitfor Kubernetes and Argo Rollouts, and$HELM_MAX_HISTORYfor Helm.If you have these limits set, you can’t restore a version outside the limit. For example, if your limit is set to the last 10 deployments, you can not restore the 11th deployment back.
We are working on updates to:
-
Indicate out-of-scope deployments.
-
Prevent you from attempting to restore unavailable deployments
-
Provide a manual way for you to mark deployments as unavailable
-
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 with0replicas are not reported as releases, even if they are scaled up subsequently. The configured value can be seen on the release agent deployment in thecircleci-release-agent-systemnamespace. 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_NAMESPACESenvironment variable on the release agent deployment in thecircleci-release-agent-systemnamespace. 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:
-
Select Releases in the CircleCI web app sidebar
-
Select Configure Environments to enter the release environments view
-
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:
-
Retrieve the token value from the token field in the
circleci-release-agentsecret in thecircleci-release-agent-systemnamespace -
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 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.