Setting the file. One moment.
Skill 113 · AWS Lambda Microvms
Subchapter 113.3
references/lifecycle-model.mdMarkdown9 KBView on GitHub
Two state machines (image and MicroVM) plus the lifecycle hook contract your application can optionally implement.
Image-level state:
CREATING ──▶ CREATED ──▶ DELETINGVersion-level state (state + status):
state: PENDING ──▶ IN_PROGRESS ──▶ SUCCESSFUL
└─▶ FAILED
status: ACTIVE | INACTIVEA single image version can produce multiple Build records — one per (architecture, chipset, chipsetGeneration). Each build has its own buildState: PENDING → IN_PROGRESS → SUCCESSFUL | FAILED. List with list-microvm-image-builds.
UpdateMicrovmImageVersion switches a version’s status between ACTIVE and INACTIVE — RunMicrovm will only resolve ACTIVE versions when no explicit imageVersion is supplied.
PENDING
│
▼
RUNNING ◀──── (auto-resume on ingress, or ResumeMicrovm)
│ ▲
▼ │
SUSPENDING ──▶ SUSPENDED
│
▼ (after suspendedDurationSeconds, or TerminateMicrovm)
TERMINATING ──▶ TERMINATEDTriggers:
RunMicrovm → PENDING → RUNNING.maxIdleDurationSeconds of no proxy traffic → SUSPENDING → SUSPENDED. Or call SuspendMicrovm.autoResumeEnabled: true, or ResumeMicrovm → RUNNING.SUSPENDED for suspendedDurationSeconds → terminated.maximumDurationInSeconds (cap 28,800 s = 8 hr) reached → terminated.TerminateMicrovm from anywhere.Idle is measured by traffic through the proxy endpoint. If your app does outbound work but receives no inbound traffic, the platform will count it as idle. For background workers, set high maxIdleDurationSeconds or disable auto-suspend by omitting idlePolicy in the request.
Your application can implement HTTP endpoints that Lambda invokes at lifecycle transitions. Hooks are opt-in per image via the --hooks parameter. You must specify the port your hooks listen on (commonly 9000).
| Hook | Path | When invoked | Timeout field | Use it for |
|---|---|---|---|---|
/ready | POST /aws/lambda-microvms/runtime/v1/ready | During image build, before snapshot capture | readyTimeoutInSeconds (1–3600) | Confirm app initialized; fail the build if app is broken |
/validate | POST /aws/lambda-microvms/runtime/v1/validate | After build, on a test MicroVM run from the snapshot | validateTimeoutInSeconds (1–3600) | End-to-end smoke test of the snapshot |
Implementing image build hooks is recommended for performance — they ensure your application is fully initialized before the snapshot is captured, resulting in faster runs.
| Hook | Path | When invoked | Timeout field | Use it for |
|---|---|---|---|---|
/run | POST /aws/lambda-microvms/runtime/v1/run | Once, immediately after a MicroVM is run (resumed from snapshot) | runTimeoutInSeconds (1–60) | Create per-VM unique state, fetch secrets, register with discovery. Should be quick — not for long-running work |
/resume | POST /aws/lambda-microvms/runtime/v1/resume | After SUSPENDED → RUNNING | resumeTimeoutInSeconds (1–60) | Re-establish connections, generate new randomness if your application relies on non-CSPRNGs |
/suspend | POST /aws/lambda-microvms/runtime/v1/suspend | Just before RUNNING → SUSPENDED | suspendTimeoutInSeconds (1–60) | Return 200 only when the app is ready to be suspended. Customer decides the strategy: wait for in-flight work to drain within the timeout, or return immediately |
/terminate | POST /aws/lambda-microvms/runtime/v1/terminate | Just before termination | terminateTimeoutInSeconds (1–60) | Flush logs, persist state, deregister |
If you use microVM hooks, you must implement the
/readymicroVM image hook. This ensures your application has booted and can receive hook events.Always set explicit timeout values in
--hookswhen creating the image — especially for/ready(init) and/run//resume(any per-VM init work).
--hooks '{
"port": 9000,
"microvmImageHooks": {
"ready": "ENABLED",
"readyTimeoutInSeconds": 60,
"validate": "ENABLED",
"validateTimeoutInSeconds": 10
},
"microvmHooks": {
"run": "ENABLED",
"runTimeoutInSeconds": 2,
"resume": "ENABLED",
"resumeTimeoutInSeconds": 2,
"suspend": "ENABLED",
"suspendTimeoutInSeconds": 5,
"terminate": "ENABLED",
"terminateTimeoutInSeconds": 5
}
}'A hook left at its default DISABLED is not called even if the application implements the path.
/ready and /validate, return 503 if the application needs more time — the platform will keep retrying until the configured timeout elapses. Returning 503 quickly is preferred over blocking the request until ready: a blocked call holds the connection open and can consume the entire timeout window in one attempt instead of letting the platform poll.
/ready failure (non-200/503 or timeout) fails the build.RunMicrovm to fail or transition the MicroVM through TERMINATING with stateReason set.runHookPayload you pass to RunMicrovm is delivered as the request body of /run. Lambda Your app
│ │
RunMicrovm ───────────▶│ │
│ resume snapshot │
│ POST /run (runHookPayload)│
│────────────────────────────▶│ 200
│ │
client ──── HTTPS ingress ──────────▶│ (request handled)
│ ... no traffic for │
│ maxIdleDurationSeconds ... │
│ POST /suspend │
│────────────────────────────▶│ 200
│ suspend (snapshot RAM+disk)
│ │
client ──── HTTPS ingress ──────────▶│ (auto-resume if enabled)
│ resume │
│ POST /resume │
│────────────────────────────▶│ 200
│ ... eventually ... │
TerminateMicrovm ─────▶│ POST /terminate │
│────────────────────────────▶│ 200
│ stop │The idlePolicy block itself is optional on RunMicrovm — omit it to disable idle-based auto-suspend entirely. If you supply the block, all three fields below are required:
| Field | Range | Notes |
|---|---|---|
maxIdleDurationSeconds | ≥60 | Required if idlePolicy is supplied. Idle threshold from last proxy traffic. |
suspendedDurationSeconds | ≥0 | Required if idlePolicy is supplied. Time-to-terminate while suspended. 0 means “terminate immediately on suspend.” |
autoResumeEnabled | bool | Required if idlePolicy is supplied. If true, proxy resumes the VM transparently when traffic arrives at its endpoint. |
maximumDurationInSeconds is not an idlePolicy field — it is a separate top-level RunMicrovm flag that sets a hard wall-clock lifetime regardless of activity.
0.0.0.0 on the configured port. Lambda calls hooks over the guest’s network namespace; localhost-only listeners are unreachable./suspend should still answer 200 even if your main worker pool is busy./run and /resume fast. These hooks are notification mechanisms. If your application needs to run long-running workflows (> 60s) in response, do so asynchronously./run for long-running init. That work belongs at image build time so it’s captured in the snapshot. Avoid generating random data at build time — if unique random state is needed, invalidate and re-generate using a CSPRNG on /run./suspend or /terminate under failure conditions.runHookPayload): snapshots-and-uniqueness.mdtroubleshooting.md