MicroVM images

This section describes how to build, configure, update, and manage MicroVM images.

A MicroVM image is a resource that defines the filesystem and application environment of a MicroVM. The MicroVM image includes your runtime environment, application code, and supporting programs such as background processes and observability agents. To create a MicroVM image, you provide a zip package that contains a Dockerfile and your application artifacts, which you upload to Amazon S3. Your Dockerfile defines how your application is packaged. Lambda builds your application container image by running your Dockerfile on top of an operating system environment that is provided by a Lambda-managed MicroVM base image. MicroVM base images are described below, in the section titled – MicroVM base images.

You can update your MicroVM base images to update the application code or configuration for your MicroVMs. Each update you trigger creates a new MicroVM image version.

How Lambda builds a MicroVM image

When you create a MicroVM image, Lambda:

Once the snapshot process completes, your MicroVM image enters the CREATED state. You can now use this MicroVM image to create a MicroVM, and each MicroVM image can be used to create multiple independent MicroVMs. A MicroVM run from the MicroVM image resumes directly from the snapshotted state, providing rapid startup times. Each MicroVM image can be used to run multiple MicroVMs, up-to the limit available for your account.

For a step-by-step walkthrough of packaging your code and creating your first MicroVM image, refer to Create your first MicroVM.

MicroVM sizing

Lambda MicroVMs uses a baseline-peak model that removes the need to right-size each compute environment for peak activity. You configure the baseline compute resources for your MicroVM. During peak activity, your MicroVM can automatically scale vertically up to 4x the baseline. You pay the baseline rate while your MicroVM is running and only pay for what you actively use above the baseline, billed per second.

You set the baseline via the memory parameter when creating your MicroVM image. vCPU scales proportionally with memory (2 GB = 1 vCPU). The default baseline is 2 GB / 1 vCPU.

The following table lists the available sizes:

MicroVM base images

A MicroVM base image serves as the foundation for your MicroVM images. Lambda publishes a MicroVM base image which provides the Amazon Linux 2023 operating system and the service components required to run MicroVMs. When you create or update a MicroVM image, Lambda starts a new MicroVM from this base image and runs your Dockerfile instructions within this operating system environment.

Lambda periodically releases new versions of service-managed MicroVM base images, such as when applying security patches, to update the operating system or service components. By default, the latest version of a service-managed base image applies when you are creating/updating your own MicroVM images. For troubleshooting or debugging, you can optionally override the version of the service-managed based images when creating your own MicroVM image using the base-image-version parameter.

Base image versions follow a deprecation lifecycle:

To stay current, monitor for deprecation notifications and rebuild your MicroVM images when a new base image version is released.

Note that the MicroVM base image is distinct from the container base image you specify in your Dockerfiles. While the former defines the operating system environment for your MicroVMs, the latter defines which base container image to use when packaging your application for use with Lambda MicroVMs. See the section on Container base images for more details.

Use the following APIs to discover available managed MicroVM base images and their versions:

# List all managed MicroVM base images
aws lambda-microvms list-managed-microvm-images

# List the versions of a specific managed MicroVM base image
aws lambda-microvms list-managed-microvm-image-versions \
  --image-identifier arn:aws:lambda:us-east-1:aws:microvm-image:al2023-1

MicroVM image build hooks

Lambda provides MicroVM image build hooks that let you verify application correctness and optimize performance during MicroVM image creation. Hooks run before Lambda takes the snapshot that is used to initialize each MicroVM. Each hook is an HTTP endpoint that your application exposes and that Lambda calls during the build. By responding to these requests, you control and validate the MicroVM image build process. Lambda uses HTTP Status codes to determine whether the hooks successfully completed.

Updating a MicroVM image

You can update an existing MicroVM image by calling the update-microvm-image API. Each update triggers a new MicroVM image version build. You typically update a MicroVM image to:

The following CLI command shows how you can update a MicroVM image. The --base-image-arn and --build-role-arn parameters are required on every update-microvm-image call that triggers a new build, even when you are only changing the code artifact – omitting them results in a ValidationException:

aws lambda-microvms update-microvm-image \
  --image-identifier arn:aws:lambda:us-east-1:123456789012:microvm-image:my-microvm-image \
  --code-artifact uri=s3://my-bucket/deployments/app-v2.zip \
  --base-image-arn arn:aws:lambda:us-east-1:aws:microvm-image:al2023-1 \
  --build-role-arn arn:aws:iam::123456789012:role/MicrovmBuildRole \
  --description "Updated with v2 application code"

Image states and build states

Every time you create or update a MicroVM image, Lambda produces a new version built from your code artifact and base image. A MicroVM image can have many versions over time, and you run MicroVMs from a specific version.

Three independent states track different aspects of the lifecycle:

To run a MicroVM from a version, the image state must be CREATED or UPDATED, the version state must be SUCCESSFUL, and the version must be ACTIVE.

# De-activate a version
aws lambda-microvms update-microvm-image-version \
  --image-identifier my-image \
  --image-version 1.0 \
  --state INACTIVE

Environment variables

Environment variables are set at MicroVM image build time via the environmentVariables field (maximum 50 variables). These are injected into the container during the snapshot build process. You can pass dynamically set payloads when running a new MicroVM. Refer to the section on running your MicroVM to learn more.

MicroVM image patching

When there is a new MicroVM base image available, you can issue an update-microvm-image call to trigger a MicroVM image build with the latest patches – either omitting the base-image-version argument (for latest) or specifying the argument with the latest version.

Container base images

Lambda MicroVMs runs your application as a container within the MicroVM operating system environment. You define that container with your Dockerfile, and the FROM instruction in your Dockerfile sets the container base image for your application.

You can either start with Lambda's base container image for Amazon Linux 2023 (public.ecr.aws/lambda/microvms:al2023-minimal) and add your Dockerfile instructions on top of this, or use your own base container image. When using your own container images, validate the following requirements:

Requirements

Snapshot-compatible base images

As Lambda MicroVMs starts each MicroVM from a pre-initialized snapshot, base images must be snapshot compatible. We recommend reviewing the section on Compatibility considerations when using your own base images with Lambda MicroVMs.

Using a private ECR image

Reference your private ECR container base image in the FROM instruction of your Dockerfile:

FROM 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-base:latest
WORKDIR /app
COPY . .
CMD ["./my-app"]

Add the following permissions to your build role:

{
  "Effect": "Allow",
  "Action": [
    "ecr:GetAuthorizationToken",
    "ecr:BatchCheckLayerAvailability",
    "ecr:GetDownloadUrlForLayer",
    "ecr:BatchGetImage"
  ],
  "Resource": "*"
}

Operating system capabilities

By default, Lambda MicroVMs run with a standard set of Linux capabilities. You can grant elevated Linux capabilities using the additionalOsCapabilities field when creating or updating a MicroVM image. The only supported value is ["ALL"]. Elevated capabilities enable operations such as mounting filesystems, creating network namespaces, or running eBPF programs. Capabilities are applied within the VM isolation boundary and do not affect the host or other MicroVMs.

aws lambda-microvms create-microvm-image \
  --name my-network-tool \
  --code-artifact uri=s3://my-bucket/app.zip \
  --base-image-arn arn:aws:lambda:us-east-1:aws:microvm-image:al2023-1 \
  --build-role-arn arn:aws:iam::123456789012:role/BuildRole \
  --additional-os-capabilities '["ALL"]'