Skip to content

Pushing Container Images and Helm Charts to AWS ECR

ECR logo

Amazon Elastic Container Registry (ECR) is an OCI-compliant registry that securely hosts both container images (Docker/Podman) and packaged Helm v3 charts as OCI artifacts.

This guide demonstrates how to build an application container, package a Helm chart, and push both artifacts to a private AWS ECR repository.

Prerequisites

  • AWS CLI configured with permissions to create/write to ECR (ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability, ecr:PutImage, ecr:InitiateLayerUpload, ecr:UploadLayerPart, ecr:CompleteLayerUpload).
  • Docker or Podman installed locally.
  • Helm v3+ installed.

Step 1. Create and Build the Container Image

Dockerfile 

FROM alpine:latest
RUN apk update && apk add --no-cache curl wget \
    && date > /date.txt

CMD ["tail", "-f", "/dev/null"]

Build and tag the container image locally with your ECR repository URL:

export AWS_ACCOUNT_ID="123456789012"
export AWS_REGION="eu-west-1"
export REPO_NAME="demoapp"
export IMAGE_TAG="v0.1.0"

# Build with Podman or Docker
podman build -t ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/${REPO_NAME}:${IMAGE_TAG} .

Step 2. Authenticate and Push the Container Image to ECR

# 1. Authenticate Podman/Docker to private ECR
aws ecr get-login-password --region ${AWS_REGION} \
  | podman login --username AWS --password-stdin ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com

# 2. Push image to ECR
podman push ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/${REPO_NAME}:${IMAGE_TAG}

Step 3. Create and Package the Helm Chart

# Create chart directory
helm create demoapp

Update demoapp/values.yaml to reference your newly pushed container image:

image:
  repository: 123456789012.dkr.ecr.eu-west-1.amazonaws.com/demoapp
  pullPolicy: IfNotPresent
  tag: "v0.1.0"

Package the chart into a .tgz archive:

helm package demoapp
# Output: Successfully packaged chart and saved it to: ./demoapp-0.1.0.tgz

Step 4. Authenticate Helm and Push OCI Chart to ECR

# 1. Authenticate Helm to ECR OCI registry
aws ecr get-login-password --region ${AWS_REGION} \
  | helm registry login --username AWS --password-stdin ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com

# 2. Push Helm chart package to ECR
helm push demoapp-0.1.0.tgz oci://${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/

ECR repository with Helm chart

OCI Repository Path Structure

When pushing Helm charts via OCI (oci://...), pass the root ECR registry URL. Helm automatically derives the repository name from the chart name inside the .tgz package.

Step 5. Pull and Install the Helm Chart from ECR

# Pull chart package locally
helm pull oci://${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/${REPO_NAME} --version 0.1.0

# Or install directly to a Kubernetes cluster
helm install my-demo-app oci://${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/${REPO_NAME} \
  --version 0.1.0 \
  --namespace default