Container Images in AWS Explained: ECR, Lambda, ECS, EKS

Simple explanation

Before containers, the classic problem was “it works on my machine.” The version of Python on your laptop, the library versions, the OS packages — none of it matched production. Containers solve this by packaging everything together.

Three distinct things to keep straight:

• Container image: the static bundle. Built once, never changes. Like a template or blueprint.
• Container: a running instance of that image. Isolated, ephemeral. Stop it and it’s gone.
• Registry: a storage service for images. Amazon ECR is AWS’s registry. Docker Hub is the public alternative.

You build an image locally, push it to a registry, and a runtime (Lambda, ECS, EKS) pulls and runs it. The image itself is never modified. If you need a change, you build a new image.

What a container image actually contains

A container image packages:

• Base OS layer: typically a minimal Linux distribution like Alpine, Debian slim, or Amazon Linux
• Runtime: Python 3.12, Node.js 20, Java 21, or whichever language your app uses
• System libraries: OS-level packages your runtime or app depends on
• Application dependencies: your pip install or npm install output
• Application code: your source files
• Configuration: environment defaults, exposed ports, startup command

The image is immutable. Once built, it does not change. When a container starts from that image, it gets a writable layer on top, but anything written there is discarded when the container stops. Persistent state belongs in a database or S3, not inside the container.

How container images work in AWS

The full workflow from code to running container:

1. Write a Dockerfile: instructions for building the image.
2. Build the image locally: docker build executes those instructions layer by layer.
3. Test it locally: docker run starts a container on your machine before anything goes to AWS.
4. Push to Amazon ECR: authenticate with aws ecr get-login-password, then docker push.
5. Deploy to your runtime: point Lambda, ECS, EKS, or App Runner at the ECR image URI.
6. Update by pushing a new image: tag a new version, push, and update your service to use it.

Dockerfile → docker build → docker run (local test) → ECR → Lambda / ECS / EKS / App Runner

Dockerfile example

A typical Python web application Dockerfile:

# Start from an official Python base image
FROM python:3.12-slim

# Set the working directory inside the container
WORKDIR /app

# Copy requirements first (enables layer caching)
COPY requirements.txt .

# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Copy the application code
COPY . .

# Non-root user for security
RUN useradd -m appuser && chown -R appuser /app
USER appuser

# Expose port
EXPOSE 8000

# Start the application
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Build it:

docker build -t my-app:1.0 .

Test it locally before pushing:

docker run -p 8000:8000 my-app:1.0
# Application available at http://localhost:8000

The name:tag format identifies images. my-app:1.0 means the image named my-app at version 1.0. Tags are typically version numbers or Git commit SHAs, not latest (more on that in the mistakes section).

Image layers explained

Each Dockerfile instruction that modifies the filesystem creates a new layer. Layers stack to form the final image. They are immutable and cached.

Why instruction order matters:

• Docker rebuilds from the first changed instruction downward.
• Put slow, infrequent changes first: base image, system packages, dependency installs.
• Put fast, frequent changes last: copying your application code.
• This way, a code change only rebuilds the final layer, not the full dependency install.

When pushing to ECR, Docker transfers only layers not already present in the registry. A code-only change might push a few MB even if the full image is 500 MB.

AWS services that run container images

The core decision:

• Use Lambda for short-lived, event-driven workloads: API calls, file processing, scheduled jobs.
• Use ECS for running containers without Kubernetes complexity. Lambda vs ECS covers the overlap in detail.
• Use EKS when your team needs the Kubernetes ecosystem. See EKS vs ECS for the full comparison.
• Use App Runner for the simplest path to a running web app or API. Deploy directly from an ECR image with no infrastructure to configure.

For a guided decision, see Choosing Between EC2, Lambda, and Containers in AWS.

When to use container images

Container images are the right choice when:

• Large dependencies: ML libraries, data science stacks, or ORMs that exceed Lambda’s 250 MB zip limit.
• Consistent runtime across environments: you want development, staging, and production to run the exact same image.
• Microservices: each service is independently deployable as its own image.
• Batch jobs: container-based jobs run reproducibly on AWS Batch or ECS.
• Custom runtimes: languages or versions not natively supported by Lambda’s managed runtimes.
• Web apps and APIs: especially when you need long-running processes, WebSockets, or connection pooling.

When a simpler option is better:

• A small Lambda function with standard library dependencies fits comfortably in a zip deployment. No Docker toolchain needed.
• A simple static site or single-file script does not need containerisation.
• If you have no existing container tooling and your workload is small, start with Lambda zip and only move to containers when you hit a real constraint.

Key comparisons

Container image vs container

A container image is static: a file on disk or in a registry. A container is dynamic: a running process created from that image. You can run many containers from the same image simultaneously. Stopping a container leaves the image unchanged. See Containers vs Virtual Machines in AWS for how containers compare to EC2 instances.

Lambda zip deployment vs Lambda container image

Lambda supports two deployment formats: zip files (up to 250 MB) and container images (up to 10 GB). Use zip for small functions with minimal dependencies. It deploys faster and has no Docker toolchain requirement. Use container images when you exceed the 250 MB limit, need a custom runtime, or want consistent builds across Lambda and ECS.

Containers vs virtual machines in AWS

EC2 instances are full virtual machines with a separate OS and kernel. They are heavier but more isolated. Containers share the host kernel, start in seconds, and pack more tightly onto hardware. Containers are not always the right answer. Databases, legacy applications with kernel dependencies, and workloads requiring full OS control often belong on EC2. The full breakdown is in Containers vs Virtual Machines in AWS.

Amazon ECR in context

Amazon ECR (Elastic Container Registry) is AWS’s managed container registry. It stores your images privately, integrates with IAM for access control, and delivers images to Lambda, ECS, EKS, and App Runner from the same region. No cross-region egress costs, no Docker Hub rate limits.

Pushing an image to ECR:

# 1. Create a repository
aws ecr create-repository \
  --repository-name my-app \
  --region us-east-1

# Output includes the repository URI:
# 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app

# 2. Authenticate Docker to ECR
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  123456789012.dkr.ecr.us-east-1.amazonaws.com

# 3. Tag the local image with the ECR URI
docker tag my-app:1.0 \
  123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:1.0

# 4. Push to ECR
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:1.0

Good ECR practices:

• Enable immutable tags: prevents overwriting an existing tag, protecting production from silent changes.
• Enable image scanning: ECR scans for known CVEs on push. Fix high-severity findings before deploying.
• Set lifecycle policies: automatically expire old untagged images to control storage costs.
• Organise by service: one repository per application, not a single catch-all repository.

For automation, see Building Docker Images with AWS CodeBuild and CI/CD Pipelines for Amazon ECS.

Image tags vs digests

Every ECR image URI follows this format:

account-id.dkr.ecr.region.amazonaws.com/repository-name:tag

For example:

123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:1.0

Tags are mutable. Anyone with push access can change what my-app:latest points to. Digests are immutable. A digest is a SHA256 hash of the image content:

123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app@sha256:abc123...