Deploy to Amazon EKS using CircleCI and Helm
Software Engineer
Kubernetes is a container orchestration system for automating deployment and managing containerized applications. Helm is a Kubernetes package manager that helps you define, install, and upgrade Kubernetes applications. It lets you define reusable templates for Kubernetes components (deployment, service, hpa, service account, etc.) that can be published and shared across applications.
In this tutorial, you will learn how to build and install Helm charts for your application to an AWS EKS cluster. We will create and Dockerize a Python Flask app, then create Helm charts for it. Finally you will automate its deployment to an existing AWS EKS cluster using CircleCI.
Prerequisites
For this tutorial, you will need to set up Python on your system so that you can define the Flask app. Also, you need to create an AWS account for deploying the application and a CircleCI account for automating the deployments.
Refer to this list to set up everything required for this tutorial.
- Install Python 3
- Install Helm CLI for building and installing Helm Charts.
- Create an AWS account and a CircleCI account
During development, if you would like to test the set up locally, you will need to set up a few additional things:
- Install Docker for building Docker images locally.
- Install kubectl for testing the cluster locally.
- Install AWS CLI and configure AWS credentials.
- Install eksctl for managing Kubernetes clusters on Amazon EKS.
Our tutorials are platform-agnostic, but use CircleCI as an example. If you don’t have a CircleCI account, sign up for a free one here.
Defining a Flask app
In this section, you will create a sample Flask app using Python 3 and containerize it using Docker. Flask is an open source Python framework for developing web applications. It is a popular choice for building the API service layer for lightweight applications.
Creating the app
First, create a new directory for your Flask project and go to it. Enter:
mkdir flask-helm-charts-circleci
cd flask-helm-charts-circleci
Next, create a requirements.txt file in the flask-helm-charts-circleci directory for defining the app’s library dependencies. The Python app depends on the flask package, so add it in the requirements.txt file.
Flask==3.1.3
Create an app.py file in the flask-helm-charts-circleci directory and add this to it.
from flask import Flask
app = Flask(__name__)
@app.route('/')
def hello_world():
return 'Hello World!'
if __name__ == '__main__':
app.run(debug=False, host='0.0.0.0')
This code snippet defines a GET route that returns a static response. Based on your use case, you can add custom logic in the hello_world method. Also, you can add more routes like this one. Add them above the if __name__ == '__main__': line so they’re registered before the app starts:
@app.route('/health')
def health_check():
return 'Health OK'
You can run the app locally by executing this command. On executing this command, the Flask app will start running on localhost port 5000.
python app.py
Go to http://127.0.0.1:5000 to verify the response.
Dockerizing the app
Now that you have defined the Flask app, add a Dockerfile to containerize the app. We will use the Python 3.14.9 slim base image from Docker Hub. Create a Dockerfile in the flask-helm-charts-circleci directory and add this code snippet to it.
FROM python:3.14.9-slim
ADD . /app
WORKDIR /app
RUN pip install -r requirements.txt
EXPOSE 5000
CMD ["python", "app.py"]
This code snippet has these steps:
- It uses the Python 3.14.9 slim base image.
- The
ADD .step copies all the files from the root directory of the project to the/appdirectory on the container. WORKDIRsets the current working directory of the container to/app. All the subsequent commands will be executed in this directory.RUNstep installs the python dependencies defined in therequirements.txtfile.EXPOSEstep exposes port5000from the Docker container.- Finally,
CMDdefines the container’s startup command. The container will start the Flask app when it is executed.
Building and running the Docker container
Build and run the Docker container locally to verify if it works as expected. If you plan to use CircleCI for your set up, you can skip this step.
To build the Docker image, run this command in the flask-helm-charts-circleci directory.
docker build -t flask-hello-world .
Note: Make sure to have Docker installed on your system before executing the above command. Follow the link in the Prerequisites section for installation steps.
Finally, run this command.
docker run -it --rm -p 5001:5000 flask-hello-world:latest
This command forwards port 5000 from the Docker container to port 5001 locally. Try navigating to http://127.0.0.1:5001 to verify that the app is running as expected.
Creating AWS resources
Before moving on to testing and deployment, make sure that you have the required AWS resources provisioned in your account. You could use existing resources in your account or provision new resources if you don’t have them created.
- Create an AWS ECR repository for hosting your Flask Docker images.
- Create an AWS ECR repository for hosting your Helm chart.
- Create an AWS EKS cluster for running your Kubernetes workload.
The IAM identity that creates the cluster gets cluster admin access automatically. If you configure CircleCI with a different IAM user or role, grant it access to the cluster with an EKS access entry.
Creating Helm charts
Charts are Helm’s packaging format. A chart contains a collection of files that describe a related set of Kubernetes resources. In this section, you will define a Helm chart for your app.
To create a chart for your app, execute this command in the flask-helm-charts-circleci directory.
helm create charts
Note: Install the Helm CLI before executing the previous command. Follow the link in the Prerequisites section for installation steps.
Executing this command will create a charts directory with this structure.
charts/
Chart.yaml
values.yaml
charts/
templates/
The charts/templates/ directory contains several files but you need only _helpers.tpl, deployment.yaml, and service.yaml. Delete the other files from the templates directory.
Next, update the deployment template to remove some variables which are not needed for this tutorial. You also need to update the containerPort to 5000 since your Flask application is running on this port. Replace the contents of the charts/templates/deployment.yaml with this code snippet:
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "charts.fullname" . }}
labels:
{{- include "charts.labels" . | nindent 4 }}
spec:
{{- if not .Values.autoscaling.enabled }}
replicas: {{ .Values.replicaCount }}
{{- end }}
selector:
matchLabels:
{{- include "charts.selectorLabels" . | nindent 6 }}
template:
metadata:
{{- with .Values.podAnnotations }}
annotations:
{{- toYaml . | nindent 8 }}
{{- end }}
labels:
{{- include "charts.selectorLabels" . | nindent 8 }}
spec:
{{- with .Values.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
ports:
- name: http
containerPort: 5000
protocol: TCP
livenessProbe:
httpGet:
path: /
port: http
readinessProbe:
httpGet:
path: /
port: http
Next, update the values.yaml file with values corresponding to your application. Replace the contents of the charts/values.yaml with this code snippet:
replicaCount: 1
image:
repository: <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/<AWS_ECR_REPO_NAME>
pullPolicy: IfNotPresent
tag: "latest"
labels:
env: "staging"
service:
port: 5000
type: LoadBalancer
autoscaling:
enabled: false
ingress:
enabled: false
Replace <AWS_ACCOUNT_ID> with your AWS account ID, <AWS_REGION> with the AWS deployment region and <AWS_ECR_REPO_NAME> with the name of the AWS ECR repository for your Flask Docker image.
Now, update the name in the charts/Chart.yaml.
name: flask-helm-chart
The chart name should match the name of the AWS ECR Helm repository.
Testing locally
You may want to test the setup locally, before automating the deployments using CircleCI. This section describes how to manually push the image and Helm chart to AWS ECR and deploy the Helm chart to the AWS EKS cluster. If you want to directly automate the deployments using CircleCI, you can skip this section.
Pushing the Docker image to ECR
Before pushing the Docker image you need to authenticate Docker with AWS ECR. Execute this command for authentication:
aws ecr get-login-password --region <AWS_REGION> | docker login --username AWS --password-stdin <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com
You need AWS CLI installed and AWS credentials configured before executing the previous command. Follow the links in the Prerequisites section for instructions.
Next, tag the Docker image you built in the previous section using this command:
docker tag flask-hello-world:latest <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/flask-hello-world
Make sure that your AWS account contains an ECR repository named flask-hello-world.
Push the Docker image to the AWS ECR repository by executing this command:
docker push <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/flask-hello-world:latest
Pushing the Helm chart to ECR
Before pushing the Helm chart you need to authenticate helm with AWS ECR. Execute this command for authentication:
aws ecr get-login-password --region <AWS_REGION> | helm registry login --username AWS --password-stdin <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com
Next, package the Helm chart by executing this command from the root directory of the project.
helm package charts
It will generate a flask-helm-chart-0.1.0.tgz file with the compressed version of your helm chart.
The tgz filename could differ based on the name of the chart defined in charts/Chart.yaml.
Next, you can push the Helm chart to AWS ECR repository by executing this command:
helm push flask-helm-chart-0.1.0.tgz oci://<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/
Deploying the Helm chart to AWS EKS
Now that your Helm chart is pushed to the AWS ECR repository, you can deploy it to the AWS EKS cluster. First, update the local kube config using the AWS CLI.
aws eks update-kubeconfig --region <AWS_REGION> --name <AWS_EKS_CLUSTER_NAME>
Replace <AWS_EKS_CLUSTER_NAME> with the name of your AWS EKS cluster and <AWS_REGION> with the name of the selected AWS region.
This command will write the kube config to $HOME/.kube/config.
Finally, execute the helm install command to install the chart to the EKS cluster.
helm install flask-helm oci://<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/flask-helm-chart --version 0.1.0
The command will install the workload to your EKS cluster. You can verify the same by checking the pods on your cluster.
kubectl get pods
Automate deployment using CircleCI
Now that you have tested the Kubernetes cluster locally, automate the workflow so that the changes can be deployed every time you push code. To automate the deployments you need to:
- Choose the Helm deployment command
- Add the configuration script
- Set up the project on CircleCI
Choose the Helm deployment command
When a chart is already installed on a cluster, helm install fails and you need helm upgrade instead. The helm upgrade --install command handles both cases. It installs the flask-helm release if it doesn’t exist yet and upgrades it if it does. The CircleCI configuration in the next section deploys with it:
helm upgrade --install flask-helm oci://$AWS_ECR_ACCOUNT_URL/$AWS_ECR_HELM_REPO_NAME --version 1.0.0
Add the configuration script
First, add a .circleci/config.yml script in the project’s root containing the configuration file for the CI pipeline. Add this code snippet to it.
version: 2.1
orbs:
aws-cli: circleci/aws-cli@5.4.2
aws-ecr: circleci/aws-ecr@10.0.0
jobs:
deploy_helm_chart:
docker:
- image: cimg/python:3.14.9
steps:
- checkout
- aws-cli/setup
- run:
name: Install Helm
command: |
curl -fsSL https://get.helm.sh/helm-v4.3.1-linux-amd64.tar.gz | tar xz
sudo mv linux-amd64/helm /usr/local/bin/helm && rm -rf linux-amd64
helm version
- run:
name: Configure access to the EKS cluster
command: aws eks update-kubeconfig --region $AWS_CLUSTER_REGION --name $AWS_EKS_CLUSTER_NAME
- run:
name: Push the Helm chart to ECR
command: |
aws ecr get-login-password --region $AWS_DEFAULT_REGION | helm registry login --username AWS --password-stdin $AWS_ECR_ACCOUNT_URL
helm package charts --version 1.0.0 --destination dist
helm push dist/*.tgz oci://$AWS_ECR_ACCOUNT_URL
- run:
name: Install or upgrade the Helm release
command: |
helm upgrade --install flask-helm oci://$AWS_ECR_ACCOUNT_URL/$AWS_ECR_HELM_REPO_NAME --version 1.0.0 \
--set image.repository=$AWS_ECR_ACCOUNT_URL/$AWS_ECR_REPO_NAME --set-string image.tag=$CIRCLE_SHA1 \
--wait --timeout 5m
workflows:
build_and_deploy:
jobs:
- aws-ecr/build_and_push_image:
auth:
- aws-cli/setup
repo: ${AWS_ECR_REPO_NAME}
tag: latest,${CIRCLE_SHA1}
- deploy_helm_chart:
requires:
- aws-ecr/build_and_push_image
Take a moment to review the CircleCI configuration. The workflow runs two jobs:
- The
aws-ecr/build_and_push_imagejob uses the aws-ecr orb to build the Flask Docker image and push it to your AWS ECR repository. Itsauthstep uses the aws-cli orb to sign in with the AWS credentials from your project’s environment variables. The image is taggedlatestand with the commit SHA. - The
deploy_helm_chartjob pushes the Helm chart to the AWS ECR Helm repository and installs it on the AWS EKS cluster. It has these steps:- Install the AWS CLI with the aws-cli orb, then install the Helm CLI.
- Use
aws eks update-kubeconfigto write the kube config to$HOME/.kube/config. - Authenticate Helm with AWS ECR, then package the chart and push it.
- Deploy the chart with
helm upgrade --install. It setsimage.repositoryfrom your environment variables andimage.tagto the commit SHA, so every pipeline rolls out the image it just built.
Now that the configuration file has been properly set up, create a repository for the project on GitHub and push all the code to it. Review Pushing a project to GitHub for instructions.
Setting up the project on CircleCI
Next, log in to your CircleCI account. In the CircleCI web app, select your organization, then select Create project. Give your project a name and select Next. Keep the suggested pipeline name or enter your own, then choose your GitHub repository. If CircleCI isn’t connected to GitHub yet, select the + (Add a provider) button and install the CircleCI GitHub App for your repository. If your repository isn’t listed, select Update access on GitHub, then refresh the list.
Keep the default All pushes trigger and select Next. CircleCI detects the .circleci/config.yml file in your repository. Select Next again, review your setup, and select Go to project.
The pipeline runs on your next push to the repository. If it runs before you define the environment variables, it will fail.
Set up environment variables
On the project’s pipelines page, open the Project menu and select Project settings, then select Environment Variables in the side navigation. Select Add to add a new key value.
Add these environment variables:
AWS_ACCESS_KEY_IDto the access key obtained while creating AWS credentials.AWS_SECRET_ACCESS_KEYto the secret obtained while creating AWS credentials.AWS_DEFAULT_REGIONto a region where you wish to deploy your application.AWS_ACCOUNT_IDto your 12-digit AWS account ID. The aws-ecr orb uses it to build the registry URL.AWS_ECR_ACCOUNT_URLto your AWS account URL. Replace the values for AWS account ID and region in<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.comand set it as the account URL.AWS_ECR_HELM_REPO_NAMEto the name of AWS ECR repository for Helm charts.AWS_ECR_REPO_NAMEto the name of AWS ECR repository for your Flask application’s Docker image.AWS_EKS_CLUSTER_NAMEto the name of your AWS EKS cluster.AWS_CLUSTER_REGIONThe region where your cluster was created. This might be different or the same as the default region.
Once the environment variables are configured, push a new commit, or rerun the pipeline if it already ran. This time it should build successfully.
Cleaning up
The EKS cluster, its nodes, and the load balancer created for the LoadBalancer service keep running, and billing, until you delete them. When you’re done, uninstall the release. This also removes the load balancer:
helm uninstall flask-helm
Then delete the EKS cluster. If you no longer need the two ECR repositories, delete them as well:
aws ecr delete-repository --repository-name <AWS_ECR_REPO_NAME> --region <AWS_REGION> --force
aws ecr delete-repository --repository-name <AWS_ECR_HELM_REPO_NAME> --region <AWS_REGION> --force
Conclusion
In this tutorial, you learned how to automatically build and deploy Helm charts to an AWS EKS cluster using CircleCI. Helm charts make it easier to handle the complexities of the cluster with reusable templates and simplify the process of updating a cluster. Also, it is easy to version, share, and host the Helm charts on public or private servers. With CircleCI, you can automate the build and deployment pipeline for continuous delivery. The pipeline can be used to push Docker images and Helm charts to AWS ECR repositories and update the EKS cluster with the new workload.
You can check out the complete source code used in this tutorial on GitHub.