---
title: "POST /2025-09-09/microvm-images"
method: POST
path: "/2025-09-09/microvm-images"
---

# POST /2025-09-09/microvm-images

`POST /2025-09-09/microvm-images`

Creates a MicroVM image from the specified code artifact and base image. The build is asynchronous — the image transitions from CREATING to CREATED on success, or CREATE_FAILED on failure. Use GetMicrovmImage to poll for completion.

## Request body

- object
  - `baseImageArn` string, required — A string which is not empty or blank (only whitespace).
  - `baseImageVersion` string — The specific version of the base MicroVM image to use.
  - `buildRoleArn` string, required — The ARN of an IAM role that the service assumes to perform actions on behalf of the caller.
  - `description` string — A description of the MicroVM image.
  - `codeArtifact` object, required — Contains the location of the code artifact for a MicroVM image.
    - `uri` string — The URI of the code artifact, such as an Amazon S3 path or Amazon ECR image URI.
  - `logging` object — Configuration for MicroVM logging output. Specify exactly one: cloudWatch to enable CloudWatch logging, or disabled to turn off logging.
    - `disabled` object — Specifies that logging is disabled.
    - `cloudWatch` object — Configuration for sending logs to Amazon CloudWatch Logs.
      - `logGroup` string — The name of the CloudWatch Logs log group to send logs to.
      - `logStream` string — The name of the CloudWatch Logs log stream within the log group.
  - `egressNetworkConnectors` NetworkConnector[] — The list of egress network connectors available to the MicroVM at runtime.
  - `cpuConfigurations` CpuConfiguration[] — List of CPU architectures
    - `architecture` 'ARM_64', required — The CPU architecture.
  - `resources` Resources[] — List of resources
    - `minimumMemoryInMiB` integer, required — The minimum amount of memory in MiB to allocate to the MicroVM.
  - `additionalOsCapabilities` Capability[] — List of capabilities granted to the application when booted
  - `hooks` object — Lifecycle hook configuration for MicroVMs and MicroVM images.
    - `port` integer — The port number on which the hooks listener runs.
    - `microvmHooks` object — The lifecycle hooks for MicroVM events.
      - `run` 'DISABLED' | 'ENABLED' — The path of the hook invoked when the MicroVM starts running.
      - `runTimeoutInSeconds` integer — The maximum time in seconds for the run hook to complete.
      - `resume` 'DISABLED' | 'ENABLED' — The path of the hook invoked when the MicroVM resumes from a suspended state.
      - `resumeTimeoutInSeconds` integer — The maximum time in seconds for the resume hook to complete.
      - `suspend` 'DISABLED' | 'ENABLED' — The path of the hook invoked when the MicroVM is suspended.
      - `suspendTimeoutInSeconds` integer — The maximum time in seconds for the suspend hook to complete.
      - `terminate` 'DISABLED' | 'ENABLED' — The path of the hook invoked when the MicroVM is terminated.
      - `terminateTimeoutInSeconds` integer — The maximum time in seconds for the terminate hook to complete.
    - `microvmImageHooks` object — The hooks for MicroVM image build events.
      - `ready` 'DISABLED' | 'ENABLED' — The path of the hook invoked when the MicroVM image build is ready.
      - `readyTimeoutInSeconds` integer — The maximum time in seconds for the ready hook to complete.
      - `validate` 'DISABLED' | 'ENABLED' — The path of the hook invoked to validate the MicroVM image build.
      - `validateTimeoutInSeconds` integer — The maximum time in seconds for the validate hook to complete.
  - `environmentVariables` object — Environment variables set in the MicroVM runtime environment.
  - `name` string, required — Name of a MicroVM image.
  - `tags` object — A set of key-value pairs that you can attach to the resource. Use tags to categorize resources for cost allocation, access control (ABAC), and organization.
  - `clientToken` string — A unique, case-sensitive identifier you provide to ensure the idempotency of the request. If you retry a request that completed successfully using the same client token, the operation returns the successful response without performing any further actions.

## Response `201`

Success

- CreateMicrovmImageResponse
  - `imageArn` string, required — The ARN of the created MicroVM image.
  - `name` string, required — The name of the MicroVM image.
  - `state` 'CREATING' | 'CREATED' | 'CREATE_FAILED' | 'UPDATING' | 'UPDATED' | 'UPDATE_FAILED' | 'DELETING' | 'DELETE_FAILED' | 'DELETED', required — The current state of the MicroVM image.
  - `latestActiveImageVersion` string — The latest active version of the MicroVM image.
  - `latestFailedImageVersion` string — The latest failed version of the MicroVM image, if any.
  - `createdAt` string, date-time, required — The timestamp when the MicroVM image was created.
  - `baseImageArn` string, required — The ARN of the base MicroVM image.
  - `baseImageVersion` string — The specific version of the base MicroVM image.
  - `buildRoleArn` string, required — The ARN of the IAM build role.
  - `description` string — The description of the MicroVM image.
  - `codeArtifact` object, required — The code artifact containing the application code and metadata for the MicroVM image.
    - `uri` string — The URI of the code artifact, such as an Amazon S3 path or Amazon ECR image URI.
  - `logging` object — The logging configuration for build-time and runtime logs. Specify {"cloudWatch": {"logGroup": "..."}} to stream logs to a custom CloudWatch log group, or {"disabled": {}} to turn off logging.
    - `disabled` object — Specifies that logging is disabled.
    - `cloudWatch` object — Configuration for sending logs to Amazon CloudWatch Logs.
      - `logGroup` string — The name of the CloudWatch Logs log group to send logs to.
      - `logStream` string — The name of the CloudWatch Logs log stream within the log group.
  - `egressNetworkConnectors` NetworkConnector[] — The list of egress network connectors available to the MicroVM at runtime.
  - `cpuConfigurations` CpuConfiguration[] — The list of supported CPU configurations for the MicroVM.
    - `architecture` 'ARM_64', required — The CPU architecture.
  - `resources` Resources[] — The resource requirements for the MicroVM.
    - `minimumMemoryInMiB` integer, required — The minimum amount of memory in MiB to allocate to the MicroVM.
  - `additionalOsCapabilities` Capability[] — Additional OS capabilities granted to the MicroVM runtime environment.
  - `hooks` Hooks — Lifecycle hook configuration for MicroVMs and MicroVM images.
    - `port` integer — The port number on which the hooks listener runs.
    - `microvmHooks` object — The lifecycle hooks for MicroVM events.
      - `run` 'DISABLED' | 'ENABLED' — The path of the hook invoked when the MicroVM starts running.
      - `runTimeoutInSeconds` integer — The maximum time in seconds for the run hook to complete.
      - `resume` 'DISABLED' | 'ENABLED' — The path of the hook invoked when the MicroVM resumes from a suspended state.
      - `resumeTimeoutInSeconds` integer — The maximum time in seconds for the resume hook to complete.
      - `suspend` 'DISABLED' | 'ENABLED' — The path of the hook invoked when the MicroVM is suspended.
      - `suspendTimeoutInSeconds` integer — The maximum time in seconds for the suspend hook to complete.
      - `terminate` 'DISABLED' | 'ENABLED' — The path of the hook invoked when the MicroVM is terminated.
      - `terminateTimeoutInSeconds` integer — The maximum time in seconds for the terminate hook to complete.
    - `microvmImageHooks` object — The hooks for MicroVM image build events.
      - `ready` 'DISABLED' | 'ENABLED' — The path of the hook invoked when the MicroVM image build is ready.
      - `readyTimeoutInSeconds` integer — The maximum time in seconds for the ready hook to complete.
      - `validate` 'DISABLED' | 'ENABLED' — The path of the hook invoked to validate the MicroVM image build.
      - `validateTimeoutInSeconds` integer — The maximum time in seconds for the validate hook to complete.
  - `environmentVariables` object — Environment variables set in the MicroVM runtime environment.
  - `tags` object — A set of key-value pairs that you can attach to the resource. Use tags to categorize resources for cost allocation, access control (ABAC), and organization.
  - `updatedAt` string, date-time — The timestamp when the MicroVM image was last updated.
  - `imageVersion` string, required — The version of the MicroVM image.

## Other responses

- `480` — InternalServerException
- `481` — AccessDeniedException
- `482` — ResourceNotFoundException
- `483` — ThrottlingException
- `484` — ConflictException
- `485` — ValidationException
- `486` — ServiceQuotaExceededException

---

[API](https://skmtc.net/aws/apis/lambda-microvms.md) · [All operations](https://skmtc.net/aws/apis/lambda-microvms/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/lambda-microvms/versions/83f10af82eb8/schema)