View a markdown version of this page

Amazon Lambda MicroVMs core concepts - Amazon Lambda
Key conceptsHow Lambda builds your imageMicroVM lifecycle
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon Lambda MicroVMs core concepts

Amazon Lambda MicroVMs uses several resource types that you create and manage. This page describes each resource type, how Lambda builds your MicroVM image into a snapshot, and the lifecycle states a MicroVM transitions through at runtime – the foundation for building applications with MicroVMs.

Key concepts

MicroVM

A MicroVM is a resource that represents an isolated compute environment for a single tenant, user session, or job. Each MicroVM runs an Amazon Linux 2023 operating system with operating system capabilities, providing near-instant launch and resume. MicroVMs receive requests through inbound HTTPS connections and can be suspended when idle, preserving memory and disk state. A suspended MicroVM resumes when traffic returns.

MicroVM image

A MicroVM image is a resource that defines the application environment of a MicroVM. When you create an image, Lambda builds it into a snapshot that enables near-instant launch (see How Lambda builds your image below).

To create a MicroVM image, you provide a zip package containing a Dockerfile and your application artifacts, uploaded to Amazon S3. You must use a Lambda-published managed base image as the foundation – specify it with the base-image-arn parameter. Your Dockerfile defines the application layers that Lambda builds on top of the managed base.

MicroVM images are versioned. Each version represents a single build produced from a specific code artifact and base image. A version progresses through build states (PENDING → IN_PROGRESS → SUCCESSFUL or FAILED), and successful versions can be set to ACTIVE or INACTIVE. For details on image states and management, see MicroVM Images.

Network connectors

Network connectors are resources that control how traffic reaches your MicroVM and how your MicroVM reaches external services. You associate connectors with a MicroVM at run time to configure inbound and outbound access independently.

Build-time and run-time connectors can differ, enabling your MicroVM to reach different environments during image build versus runtime.

Use Lambda-provided defaults for inbound port access (with JWE authentication), shell access, and public internet egress. Create your own network connector to route outbound traffic through your VPC.

How Lambda builds your image

When you create or update a MicroVM image, Lambda performs a build process that produces a Firecracker snapshot. This snapshot captures the fully initialized state of your application, enabling near-instant launch and resume for MicroVMs that run from it.

The build process:

  1. Lambda provisions a fresh MicroVM using the managed base image you specified.

  2. Lambda executes your Dockerfile instructions to install dependencies and configure your environment.

  3. Lambda starts your application using the ENTRYPOINT or CMD command.

  4. If you enabled the /ready hook, Lambda waits for your application to signal readiness (HTTP 200).

  5. Lambda captures a snapshot of the disk and memory state, including all running processes.

When you run a MicroVM, Lambda restores it from this snapshot. Your application resumes from its pre-initialized state without repeating startup.

If your application generates unique content during the build (such as unique IDs, secrets, or network connections), that content is shared across all MicroVMs run from the same image version. To avoid this, generate unique content after the MicroVM starts using the /run lifecycle hook. For details, see the snapshot compatibility section in MicroVM Images.

MicroVM lifecycle

At runtime, a MicroVM transitions through the following stages:

  1. Run – You call run-microvm. Lambda restores the MicroVM from the image snapshot, assigns a unique ID, and creates an endpoint. The MicroVM transitions from PENDING to RUNNING.

  2. Running – Your application receives and processes requests through its endpoint URL.

  3. Suspend – After a configurable idle period (or via the suspend-microvm API), the MicroVM transitions through SUSPENDING to SUSPENDED. Memory and disk state are preserved.

  4. Resume – The MicroVM transitions from SUSPENDED directly back to RUNNING when traffic arrives (if autoResumeEnabled=true) or you call resume-microvm.

  5. Terminate – The MicroVM transitions through TERMINATING to TERMINATED when you call terminate-microvm or the maximum duration is exceeded.

States

The following table describes each MicroVM state. These states enable you to build reliable applications and implement proper error handling.

State Description
PENDING MicroVM is being provisioned. Resources are being allocated and the snapshot is loading.
RUNNING MicroVM is active and accepting traffic through its endpoint URL. The /run hook has completed.
SUSPENDING MicroVM is being suspended. The /suspend hook is executing. Disk and memory are being checkpointed.
SUSPENDED MicroVM is suspended. State is preserved. No compute charges accrue. Can be resumed or terminated.
TERMINATING MicroVM is being terminated. The /terminate hook is executing. Resources are being released.
TERMINATED MicroVM has been terminated. This is a terminal state. The MicroVM cannot be resumed or restarted.

State transitions

The following table shows the valid transitions between MicroVM states and what triggers each transition.

Initial state Target state Trigger
PENDING RUNNING Provisioning complete, /run hook succeeded.
RUNNING SUSPENDING Idle duration exceeded, or explicit suspend-microvm API call.
SUSPENDING SUSPENDED /suspend hook completed, memory and disk state checkpointed.
SUSPENDED RUNNING Traffic arrives (autoResumeEnabled=true) or explicit resume-microvm API call.
RUNNING TERMINATING Explicit terminate-microvm API call, or maximumDurationInSeconds exceeded.
SUSPENDED TERMINATING suspendedDurationSeconds exceeded, or explicit terminate-microvm API call.
TERMINATING TERMINATED /terminate hook completed, all resources released.
Important

If your /run hook fails or times out, the MicroVM may transition directly to TERMINATING without ever reaching RUNNING. Implement timeout and error handling in your hooks to avoid silent failures.