TutorialsLast Updated Oct 28, 202611 min read

Deploy to Amazon EKS using CircleCI and Helm

Vivek Maskara

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.

During development, if you would like to test the set up locally, you will need to set up a few additional things:

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 /app directory on the container.
  • WORKDIR sets the current working directory of the container to /app. All the subsequent commands will be executed in this directory.
  • RUN step installs the python dependencies defined in the requirements.txt file.
  • EXPOSE step exposes port 5000 from the Docker container.
  • Finally, CMD defines 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.

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_image job uses the aws-ecr orb to build the Flask Docker image and push it to your AWS ECR repository. Its auth step uses the aws-cli orb to sign in with the AWS credentials from your project’s environment variables. The image is tagged latest and with the commit SHA.
  • The deploy_helm_chart job 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-kubeconfig to 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 sets image.repository from your environment variables and image.tag to 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.

The CircleCI Create a project page at the Pipeline step, with the pipeline name build-and-test, the flask-helm-charts-circleci GitHub repository selected, and the All pushes trigger.

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_ID to the access key obtained while creating AWS credentials.
  • AWS_SECRET_ACCESS_KEY to the secret obtained while creating AWS credentials.
  • AWS_DEFAULT_REGION to a region where you wish to deploy your application.
  • AWS_ACCOUNT_ID to your 12-digit AWS account ID. The aws-ecr orb uses it to build the registry URL.
  • AWS_ECR_ACCOUNT_URL to your AWS account URL. Replace the values for AWS account ID and region in <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com and set it as the account URL.
  • AWS_ECR_HELM_REPO_NAME to the name of AWS ECR repository for Helm charts.
  • AWS_ECR_REPO_NAME to the name of AWS ECR repository for your Flask application’s Docker image.
  • AWS_EKS_CLUSTER_NAME to the name of your AWS EKS cluster.
  • AWS_CLUSTER_REGION The region where your cluster was created. This might be different or the same as the default region.

The Environment Variables page in CircleCI project settings, listing the nine AWS variables for this tutorial with their values masked.

Once the environment variables are configured, push a new commit, or rerun the pipeline if it already ran. This time it should build successfully.

A CircleCI pipeline with two successful runs of the build_and_deploy workflow, where the expanded run shows the aws-ecr/build_and_push_image and deploy_helm_chart jobs both passed.

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.