AWS Lambda Tutorial

AWS Lambda supports deploying functions as Docker container images via Amazon ECR. Container images allow richer dependency management and a higher size limit (10 GB) than zip-based deployments, but Lambda requires images to conform to a specific format. See AWS docs This tutorial builds a Python Lambda function using a multi-stage Dockerfile: the build stage uses reg.mini.dev/python:latest-dev for access to pip, and the runtime stage uses the fully distroless production image for a minimal, secure final artifact. Learn more about multi-stage builds

What this guide demonstrates

Minimus Python images can run on AWS Lambda
Amazon Linux is not required
Non-root execution is supported
Buildx defaults must be overridden

Prerequisites

Access to an AWS account
Permission to:
- Create ECR repositories
- Push images to ECR
- Create and invoke Lambda functions
  - Access to create or use a role for the function
- Read CloudWatch logs

Process

Create Python app

Create a Python app app.py:

app.py

import sys
import os

def handler(event, context):
    return {
        "ok": True,
        "python": sys.version,
        "cwd": os.getcwd(),
        "uid": os.getuid(),
        "event": event,
    }

Create Dockerfile

Save the following Dockerfile. The build stage creates an isolated venv (virtual environment) so runtime dependencies can be copied cleanly to the production image:

Dockerfile

# === Build Stage ===

FROM reg.mini.dev/python:latest-dev AS builder

WORKDIR /var/task

# Create an isolated venv for runtime dependencies (including awslambdaric)

RUN python -m venv /opt/venv

ENV PATH="/opt/venv/bin:\$PATH"

# Install the Lambda Runtime Interface Client (RIC) into the venv
# Add other dependencies if relevant (requirements.txt)

RUN pip install --no-cache-dir awslambdaric

# === Runtime Stage ===

FROM reg.mini.dev/python:latest

# Lambda expects code in /var/task

WORKDIR /var/task

COPY app.py .

# Copy the pre-built venv from the builder stage

COPY --from=builder /opt/venv /opt/venv

# Use venv python and packages at runtime

ENV PATH="/opt/venv/bin:\$PATH"

ENV HOME=/home/python

USER 1000

# Lambda container contract:
# ENTRYPOINT starts the runtime interface client
# CMD names the handler

ENTRYPOINT ["python", "-m", "awslambdaric"]

CMD ["app.handler"]

Create an ECR repository

Create an ECR repository. See AWS docs In the AWS Console:

Go to Elastic Container Registry (ECR)
Create a private repository. For this guide, we assume you named it: minimus-lambda-example
Note the full repository URI, for example: 123456789012.dkr.ecr.eu-north-1.amazonaws.com/minimus-lambda-example

Authenticate to your default registry

Authenticate the Docker CLI to your default registry so the docker command can push and pull images with Amazon ECR. See AWS docs

aws ecr get-login-password --region eu-north-1 \
  | docker login --username AWS --password-stdin \
    123456789012.dkr.ecr.eu-north-1.amazonaws.com

Replace the example URI in the above command with your own before running the command.

Build and push the image

Build the image using buildx. Buildx is an extended Docker build command that uses BuildKit under the hood, handling multi-architecture builds, remote push, and more.

docker buildx build \
  --platform linux/arm64 \
  --provenance=false \
  --sbom=false \
  -t 123456789012.dkr.ecr.eu-north-1.amazonaws.com/minimus-lambda-example:lambda-arm64 \
  --push \
  .

Create the Lambda function

In the AWS Console:

Go to Lambda
Click Create function
Select container image
Select minimus-lambda-example:lambda-arm64
Set Architecture to arm64
Create or select an execution role
Create the function

Invoke via AWS CLI

Create a test event:

echo '{"hello":"lambda"}' > event.json

Invoke the function:

aws lambda invoke \
  --function-name minimus-lambda-example \
  --payload file://event.json \
  --cli-binary-format raw-in-base64-out \
  --region eu-north-1 \
  response.json

View the response:

cat response.json

{"ok": true, "python": "3.14.2 (tags/v3.14.2-0-gdf79316-dirty:df79316, Dec  5 2025, 20:23:01) [GCC 15.2.0]", "cwd": "/var/task", "uid": 993, "event": {"hello": "lambda"}}%

Invoke via AWS console

Open the Lambda function
Click Test
Create a new test event:

{

  "hello": "lambda"

}

Invocation type: Synchronous
Click Test

Required Buildx flags

Lambda requires a single-architecture image manifest, not an OCI index with attestations. Docker Buildx adds provenance and SBOM attestations by default, which results in the pushed image becoming an OCI image index containing an extra attestation manifest (often shown as unknown/unknown platform). Since AWS Lambda does not support this image format, it is necessary to add the following Buildx flags:

--provenance=false
--sbom=false

If the above flags are omitted, Lambda creation fails with the error: The image manifest, config or layer media type is not supported.

Building Secure Apps

Tutorials

K8s Guides

TLS Guides

Troubleshooting

Debugging

What this guide demonstrates

Prerequisites

Process

Required Buildx flags

​What this guide demonstrates

​Prerequisites

​Process

​Required Buildx flags

What this guide demonstrates

Prerequisites

Process

Required Buildx flags