cdkd local start-microvm

cdkd local start-microvm [target] runs AWS Lambda MicroVMs from an AWS::Lambda::MicrovmImage in your CDK app until you press Ctrlc. It builds the image's Dockerfile once, starts --count containers, drives each one's lifecycle hooks in the order the cloud does, and serves each MicroVM on its own local URL.

# one MicroVM on a free port
cdkd local start-microvm MyStack/Image

# three MicroVMs on 8000, 8001 and 8002
cdkd local start-microvm MyStack/Image --count 3 --port 8000

# the runHookPayload the /run hook receives
cdkd local start-microvm MyStack/Image --run-hook-payload tenant-a

# make container port 5005 routable
cdkd local start-microvm MyStack/Image --proxy-port 5005

# run under an execution role
cdkd local start-microvm MyStack/Image --assume-role arn:aws:iam::123456789012:role/MicrovmExec

Docker is required. Local Execution lists the requirements.

Run a MicroVM image

The image's code is an s3assets.Asset of a directory holding a Dockerfile and the app:

import * as path from 'node:path';
import * as s3assets from 'aws-cdk-lib/aws-s3-assets';
import { CfnMicrovmImage } from 'aws-cdk-lib/aws-lambda';

const code = new s3assets.Asset(this, 'Code', {
  path: path.join(__dirname, '../app'),
});

new CfnMicrovmImage(this, 'Image', {
  name: 'my-image',
  codeArtifact: { uri: code.s3ObjectUrl },
  cpuConfigurations: [{ architecture: 'ARM_64' }],
  environmentVariables: [{ key: 'GREETING', value: 'hello' }],
  hooks: {
    port: 9001,
    microvmImageHooks: { ready: 'ENABLED' },
    microvmHooks: { run: 'ENABLED', terminate: 'ENABLED' },
  },
  // ...the image's other required properties
});

cdkd local start-microvm MyStack/Image --port 8000
curl http://127.0.0.1:8000/hello

Once the hooks have answered, cdkd prints one line per MicroVM:

MicroVM mvm-<uuid> listening on http://127.0.0.1:8000  (control: http://127.0.0.1:8000/_cdkl/microvm)

Nothing is deployed. The code comes from the asset staged in cdk.out.

Options

--run-hook-payload and --run-hook-payload-file are mutually exclusive. The command also accepts the common flags listed in Local Execution, except --container-host.

Code and build

CodeArtifact.Uri must be the s3:// URI of a CDK asset of this app, an s3assets.Asset of a directory passing asset.s3ObjectUrl. cdkd finds the staged directory, or .zip, in cdk.out by its object key and never downloads deployed code. The bundle needs a Dockerfile at its root.

The image is built with your local Docker engine for the image's CpuConfigurations architecture (ARM_64 is linux/arm64, X86_64 is linux/amd64; --platform overrides it). The container starts the app with the image's own ENTRYPOINT / CMD.

Note

Lambda's container base public.ecr.aws/lambda/microvms:al2023-minimal is published for arm64 only and has no language runtime. On an amd64 host, build from a multi-arch base image or pass --platform.

Lifecycle hooks

Hooks are the POSTs to /aws/lambda-microvms/runtime/v1/<hook> on Hooks.Port. For each MicroVM, in order:

Without a /ready hook, the app must answer any HTTP request on Hooks.Port (or 8080 when the image has no hooks) within --timeout. A hook that is not ENABLED is skipped, and an enabled hook without a literal Hooks.Port fails before anything is built. A hook without its own TimeoutInSeconds gets --timeout, except /terminate, which gets 10 seconds.

A failure removes the containers and prints the container's last output.

Port routing

Each MicroVM's URL forwards a request to one container port, chosen in this order:

Before the app sees the request, every X-aws-proxy-* header and the MicroVM subprotocols (lambda-microvms, lambda-microvms.authentication.*, lambda-microvms.port.*) are removed. When a WebSocket client offered only MicroVM subprotocols, the 101 response selects lambda-microvms if the client offered that base protocol, and no protocol if it offered only, say, lambda-microvms.port.9000.

Reachable ports are 8080, Hooks.Port, every port the image EXPOSEs, and every --proxy-port. Errors match the cloud endpoint's:

Hooks.Port is reachable through X-aws-proxy-port locally. Whether the cloud endpoint routes to the hooks port is not verified, so do not rely on it.

The control endpoint

Each MicroVM's URL reserves /_cdkl/microvm:

An action the current state does not allow answers 409, and a hook failure 502. While a MicroVM is suspending, suspended or resuming, its requests get 503. A failed /resume leaves it suspended; a failed /terminate is reported and the container is removed anyway.

The 403 guard

The control path answers only requests addressed to this URL, so a web page open in your browser cannot drive it. Anything else gets 403:

• Host must carry this URL's port and an allowed name. Under --host 0.0.0.0 or ::, any IP literal or loopback name is allowed; under a loopback bind, the loopback names; under any other bind, only that host.
• Origin, when present, must be http://<that Host>, so Origin: null is refused.
• Sec-Fetch-Site, when present, must be same-origin or none.

Requests to the app itself are not checked.

--count and --auto-resume

--count <n> runs n independent MicroVMs from one build, each with its own microvmId, its own /run call and its own URL: the first on --port, the next on --port + 1, and so on. With more than one, each container's output is prefixed with its MicroVM ID.

--auto-resume is the idle policy's autoResumeEnabled. A request to a suspended MicroVM is held instead of answered 503, and every held request shares ONE resume. A held request gets 502 when the resume fails.

What is not emulated

cdkd warns once at startup about each of these; none of them fails the run.

Environment and credentials

The image's EnvironmentVariables reach every container. --env-vars overrides them. --from-state reads cdkd's S3 state for the stack and replaces the Ref, Fn::GetAtt, Fn::Sub, Fn::ImportValue and Fn::GetStackOutput references in them with the deployed values. --from-cfn-stack, for a stack deployed with the AWS CDK CLI, resolves only Ref and Fn::ImportValue there. The two flags are mutually exclusive. What each flag can resolve compares them.

The containers get your own AWS credentials. The execution role is a parameter of running a MicroVM, not part of the template, so --assume-role takes the role's ARN explicitly; there is no form that reads it from state.

Note

Under --role-arn, the containers and what cdkd resolves for them use your own identity, not the role. See Credentials and --role-arn.

Stopping

Ctrlc or SIGTERM calls /terminate on every running MicroVM, then removes the containers. A second signal while the containers are being removed is ignored, except while a container's docker run is still in flight: then cdkd exits at once, with 130 for Ctrlc and 143 for SIGTERM, and prints the docker rm -f command for the container it may leave behind. A container that exits on its own ends the command with an error quoting its last output.

Exit codes

An error here is a target that does not exist, a synthesis failure, code that is not a staged asset, a build failure, a hook that failed or timed out, or a container that exited while running.

The CLI Reference has the exit-code table for every command.

Related

• cdkd local start-web-function: serve a Lambda Web Function locally
• cdkd local start-service: run ECS services locally
• Local Execution: choosing a command, value resolution, and the flags every command shares
• CLI Reference: every command and the full exit-code table