# CircleCI release agent overview

Using the CircleCI release agent, you can integrate CircleCI 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.

## How it works

Configure an environment integration to install the CircleCI release agent into your Kubernetes cluster. 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.

Using the release agent, you have access to the following deploy management tools from CircleCI:

*   Restore version
    
*   Scale component
    
*   Restart component
    

For progressive delivery, the release agent supports [Argo Rollouts](https://argoproj.github.io/argo-rollouts/) using the [canary deployment strategy](https://argo-rollouts.readthedocs.io/en/stable/concepts/#canary). Some further controls are available for projects that use Argo Rollouts:

*   Retry Rollout
    
*   Promote Rollout
    
*   Cancel Rollout
    

## Getting started

To get started with the release agent, refer to the following guides:

*   [Set up the CircleCI release agent](https://circleci.com/docs/guides/deploy/set-up-the-circleci-release-agent/)
    
*   [Configure your Kubernetes components](https://circleci.com/docs/guides/deploy/configure-your-kubernetes-components/)
    
*   [How-to: Manage releases](https://circleci.com/docs/guides/deploy/manage-releases/)
    

## 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: `revisionHistoryLimit` for Kubernetes and Argo Rollouts, and `$HELM_MAX_HISTORY` for 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](https://circleci.com/docs/guides/deploy/configure-your-kubernetes-components/). 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.  Select **Configure Environments** to enter the release environments view
        
    3.  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](https://circleci.com/docs/guides/deploy/configure-your-kubernetes-components/#operation-timeout) 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](https://circleci.com/docs/guides/deploy/configure-your-kubernetes-components/#configure-release-management).