Managing EKS deployments with CircleCI deploys
AWS Delivery Consultant
Development teams managing Kubernetes-based applications face challenges in maintaining visibility and control over their deployment processes. Without a centralized interface, teams struggle to track, monitor, and manage releases across their Kubernetes clusters, leading to potential deployment errors, and difficulties in maintaining consistent deployment workflows. Additionally, teams using different deployment strategies, including traditional Kubernetes deployments and Argo Rollouts, need a unified solution to effectively orchestrate their release processes.
CircleCI deploys aims to bring that visibility into your Kubernetes deployments within CircleCI, as well as access to commands and visualizations for release management. We will be looking into some of the capabilities provided by the feature and how it can integrate with the changes going on with your Kubernetes-based applications and help you modify the configuration if needed.
Prerequisites
- A free CircleCI account connected to your code
- An Amazon Elastic Kubernetes Service (EKS) Cluster
- A CircleCI project to track the deployments connected to your code
- Helm installed in the machine running the commands we will use below.
Which teams can use this tutorial?
The sections below include steps that could be performed by teams that may have different scopes or responsibilities within an organization. You can broadly classify them as:
- Platform engineering team: Configuring the EKS cluster and release agent for teams to use.
- Application development team: Component setup and release management with minimal updates to existing Kubernetes manifest. They would typically use a self-service model requesting access to a namespace in an EKS cluster tied to a lifecycle (dev, test, prod) in their organization.
Configure deploys
Release management in CircleCI starts with an environment configuration that allows CircleCI to interact with the target platform. In this post we will look at a Kubernetes-based setup to identify some of the core capabilities of CircleCI deploys.
For CircleCI to track and manage deployment versions, a Kubernetes release agent needs to be installed into the EKS cluster. For updates and additional details around supported Kubernetes and Helm versions, please refer to the CircleCI Kubernetes release agent.
Create environment integration
From the CircleCI deploys page, you should be able to initiate a new environment integration.
- Name: “dev”
- Description: “Development environment”
- Type: Kubernetes Cluster ( selected by default)
Release agent setup
Kubernetes release agent monitors the EKS cluster for deployments or rollout events and supports running common Kubernetes commands from the CircleCI platform. These include restoring an old successful version( in case of failed deployments), scaling deployments, and so on. Once the cluster is stood up, the release agent can be installed from any machine that has CLI access to the Kubernetes control plane. For an EKS cluster named circleci, you can run this command to get the latest kubeconfig:
aws eks update-kubeconfig --region us-east-1 --name circleci
Update the local Helm repository to include the cci-k8s-release-agent and update the cache to ensure you have the latest version.
helm repo add release-agent https://circleci-public.github.io/cci-k8s-release-agent
helm repo update
Installing the release agent into the EKS cluster requires a few parameters.
- Environment integration token
- Namespace to install the agent in ( default:
circleci-release-agent-system) - Namespaces to manage or monitor ( default:
default)
You can use the Helm provider with Terraform and run the command in your CircleCI config along with the EKS cluster creation. We are using the Helm CLI commands here.
helm upgrade --install circleci-release-agent-system release-agent/circleci-release-agent \
--set tokenSecret.token=<token> \
--create-namespace \
--namespace circleci-release-agent-system \
--set managedNamespaces="{default}" # you can specify a comma separated list of namespaces
Release "circleci-release-agent-system" does not exist. Installing it now.
NAME: circleci-release-agent-system
LAST DEPLOYED: Tue Jan 23 23:24:17 2025
NAMESPACE: circleci-release-agent-system
STATUS: deployed
REVISION: 1
TEST SUITE: None
Once the agent is installed and the cluster can communicate with the release agent, the agent setup should update the status to ONLINE.
Component setup
A component in CircleCI is a collection of code and configurations 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.
To enable tracking releases and deployments in CircleCI, the only change you would need to introduce to your existing Kubernetes deployment manifest are the annotations and labels required for the CircleCI deploys.
annotations:
circleci.com/project-id: {{ your-project-ID }}
labels:
circleci.com/component-name: example-deployment
circleci.com/version: 1.0.0
Here’s a sample deployment and service configuration from the Kubernetes tutorials to explore the release feature further. This is a rendered template with the component-name and a version specified.
#nginx.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
annotations:
circleci.com/project-id: e6e31da9-5007-409b-88dd-6263c3dc5e8d
labels:
app: nginx
circleci.com/component-name: nginx
circleci.com/version: 1.0.1
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
circleci.com/component-name: nginx
circleci.com/version: 1.0.1
spec:
containers:
- name: nginx
image: nginx:1.14.2
ports:
- containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
name: nginx-service
spec:
selector:
app: nginx
ports:
- name: https
protocol: TCP
port: 80
targetPort: 9376
You could apply the Kubernetes manifest from your local machine or via your CircleCI pipelines, which could add the project id using the environment var substitution. For this example, we are deploying it from our command line.
kubectl apply -f nginx.yaml
You can also:
- Configure component release triggers to a CircleCI deployment job.
- Or customize the actions available on CircleCI using custom annotations.
Complete the setup and you should be able to track any deployments or releases based on the component labels.
Release management
Once you have a few deployments for an app deployed into your EKS cluster, you can review the status of each version, version number, and release trigger (if configured) available within CircleCI.
Restore a version
CircleCI allows you to restore a previously successful version with just one click: Restore this version. This is one of the user-initiated actions CircleCI can perform to manipulate a component. It is equivalent to a Helm rollback (if you use Helm for your deployments). Version restorations are initiated from CircleCI using the release agent, which reports the results back to CircleCI’s platform.
We recommend replicating the changes from the commit in your Git repository that triggered the pipeline for this release in a real-life scenario.
Scale a component
Users are able to scale a component from the active versions.
Once the command is issued from CircleCI, the command along with the author and time the command was issued are captured for your audit trail.
Conclusion
In this post, we walked you through the steps of managing an EKS-based deployment using CircleCI deploys for a standard deployment pattern. CircleCI deploys also support Argo Rollouts, which extends the controls available on the CircleCI platform, including provisions to retry a rollout, promote, or cancel a deployment.
Ready to streamline your Kubernetes deployments? Start with CircleCI deploys on your own EKS cluster using our quick-start guide. Benefit from enhanced release management—including support for Argo Rollouts and Amazon SageMaker integrations for ML model deployments. For more details, please refer to our comprehensive documentation.
