UpdateMicrovmImage
Updates the configuration of a MicroVM image and triggers a new version build. This operation uses PUT semantics — all required fields (codeArtifact, baseImageArn, buildRoleArn) must be provided with every request.
Request Syntax
PUT /2025-09-09/microvm-images/imageIdentifier HTTP/1.1
Content-type: application/json
{
"additionalOsCapabilities": [ "string" ],
"baseImageArn": "string",
"baseImageVersion": "string",
"buildRoleArn": "string",
"clientToken": "string",
"codeArtifact": { ... },
"cpuConfigurations": [
{
"architecture": "string"
}
],
"description": "string",
"egressNetworkConnectors": [ "string" ],
"environmentVariables": {
"string" : "string"
},
"hooks": {
"microvmHooks": {
"resume": "string",
"resumeTimeoutInSeconds": number,
"run": "string",
"runTimeoutInSeconds": number,
"suspend": "string",
"suspendTimeoutInSeconds": number,
"terminate": "string",
"terminateTimeoutInSeconds": number
},
"microvmImageHooks": {
"ready": "string",
"readyTimeoutInSeconds": number,
"validate": "string",
"validateTimeoutInSeconds": number
},
"port": number
},
"logging": { ... },
"resources": [
{
"minimumMemoryInMiB": number
}
]
}URI Request Parameters
The request uses the following URI parameters.
- imageIdentifier
-
The unique identifier (ARN or ID) of the MicroVM image to update.
Length Constraints: Minimum length of 1. Maximum length of 256.
Required: Yes
Request Body
The request accepts the following data in JSON format.
- additionalOsCapabilities
-
Additional OS capabilities granted to the MicroVM runtime environment.
Type: Array of strings
Valid Values:
ALLRequired: No
- baseImageArn
-
The ARN of the base MicroVM image.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[^\s]+Required: Yes
- baseImageVersion
-
The specific version of the base MicroVM image to use.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[^\s]+Required: No
- buildRoleArn
-
The ARN of the IAM build role.
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Pattern:
arn:aws[a-z\-]*:iam::[0-9]{12}:role/?[a-zA-Z_0-9+=,.@\-_/]+Required: Yes
- clientToken
-
A unique, case-sensitive identifier you provide to ensure the idempotency of the request.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 128.
Required: No
- codeArtifact
-
The code artifact containing the application code and metadata for the MicroVM image.
Type: CodeArtifact object
Note: This object is a Union. Only one member of this object can be specified or returned.
Required: Yes
- cpuConfigurations
-
The list of supported CPU configurations for the MicroVM.
Type: Array of CpuConfiguration objects
Required: No
- description
-
The description of the MicroVM image.
Type: String
Required: No
- egressNetworkConnectors
-
The list of egress network connectors available to the MicroVM at runtime.
Type: Array of strings
Array Members: Minimum number of 0 items. Maximum number of 1 item.
Length Constraints: Minimum length of 1. Maximum length of 2048.
Required: No
- environmentVariables
-
Environment variables set in the MicroVM runtime environment.
Type: String to string map
Map Entries: Minimum number of 0 items. Maximum number of 50 items.
Key Length Constraints: Minimum length of 1. Maximum length of 256.
Key Pattern:
[^\s]+Value Length Constraints: Minimum length of 0. Maximum length of 4096.
Required: No
- hooks
-
Lifecycle hook configuration for MicroVMs and MicroVM images.
Type: Hooks object
Required: No
- logging
-
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.
Type: Logging object
Note: This object is a Union. Only one member of this object can be specified or returned.
Required: No
- resources
-
The resource requirements for the MicroVM.
Type: Array of Resources objects
Array Members: Minimum number of 0 items. Maximum number of 1 item.
Required: No
Response Syntax
HTTP/1.1 200
Content-type: application/json
{
"additionalOsCapabilities": [ "string" ],
"baseImageArn": "string",
"baseImageVersion": "string",
"buildRoleArn": "string",
"codeArtifact": { ... },
"cpuConfigurations": [
{
"architecture": "string"
}
],
"createdAt": number,
"description": "string",
"egressNetworkConnectors": [ "string" ],
"environmentVariables": {
"string" : "string"
},
"hooks": {
"microvmHooks": {
"resume": "string",
"resumeTimeoutInSeconds": number,
"run": "string",
"runTimeoutInSeconds": number,
"suspend": "string",
"suspendTimeoutInSeconds": number,
"terminate": "string",
"terminateTimeoutInSeconds": number
},
"microvmImageHooks": {
"ready": "string",
"readyTimeoutInSeconds": number,
"validate": "string",
"validateTimeoutInSeconds": number
},
"port": number
},
"imageArn": "string",
"imageVersion": "string",
"latestActiveImageVersion": "string",
"latestFailedImageVersion": "string",
"logging": { ... },
"name": "string",
"resources": [
{
"minimumMemoryInMiB": number
}
],
"state": "string",
"updatedAt": number
}Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- additionalOsCapabilities
-
Additional OS capabilities granted to the MicroVM runtime environment.
Type: Array of strings
Valid Values:
ALL - baseImageArn
-
The ARN of the base MicroVM image.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[^\s]+ - baseImageVersion
-
The specific version of the base MicroVM image.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[^\s]+ - buildRoleArn
-
The ARN of the IAM build role.
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Pattern:
arn:aws[a-z\-]*:iam::[0-9]{12}:role/?[a-zA-Z_0-9+=,.@\-_/]+ - codeArtifact
-
The code artifact containing the application code and metadata for the MicroVM image.
Type: CodeArtifact object
Note: This object is a Union. Only one member of this object can be specified or returned.
- cpuConfigurations
-
The list of supported CPU configurations for the MicroVM.
Type: Array of CpuConfiguration objects
- createdAt
-
The timestamp when the MicroVM image was created.
Type: Timestamp
- description
-
The description of the MicroVM image.
Type: String
- egressNetworkConnectors
-
The list of egress network connectors available to the MicroVM at runtime.
Type: Array of strings
Array Members: Minimum number of 0 items. Maximum number of 1 item.
Length Constraints: Minimum length of 1. Maximum length of 2048.
- environmentVariables
-
Environment variables set in the MicroVM runtime environment.
Type: String to string map
Map Entries: Minimum number of 0 items. Maximum number of 50 items.
Key Length Constraints: Minimum length of 1. Maximum length of 256.
Key Pattern:
[^\s]+Value Length Constraints: Minimum length of 0. Maximum length of 4096.
- hooks
-
Lifecycle hook configuration for MicroVMs and MicroVM images.
Type: Hooks object
- imageArn
-
The ARN of the MicroVM image.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[^\s]+ - imageVersion
-
The version of the MicroVM image.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[^\s]+ - latestActiveImageVersion
-
The latest active version of the MicroVM image.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[^\s]+ - latestFailedImageVersion
-
The latest failed version of the MicroVM image, if any.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[^\s]+ - logging
-
The logging configuration for build-time and runtime logs. Specify