Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors Examples See Also

ImportDiskImage

Imports a Windows operating system image from a verified Microsoft ISO disk file. The following disk images are supported:

Windows 11 Enterprise

The response returns as soon as Image Builder creates the new image resource in the PENDING state. The conversion from ISO file to AMI then runs asynchronously on an EC2 instance that Image Builder launches with the specified infrastructure configuration.

Request Syntax


PUT /ImportDiskImage HTTP/1.1
Content-type: application/json

{
   "clientToken": "string",
   "description": "string",
   "executionRole": "string",
   "infrastructureConfigurationArn": "string",
   "loggingConfiguration": { 
      "logGroupName": "string"
   },
   "name": "string",
   "osVersion": "string",
   "platform": "string",
   "registerImageOptions": { 
      "secureBootEnabled": boolean,
      "uefiData": "string"
   },
   "semanticVersion": "string",
   "tags": { 
      "string" : "string" 
   },
   "uri": "string",
   "windowsConfiguration": { 
      "imageIndex": number
   }
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

clientToken

A unique, case-sensitive identifier you provide to ensure that the operation runs no more than one time. If you retry a request with the same client token, Image Builder returns the original response without running the operation again. For more information, see Ensuring idempotency in the Amazon EC2 API Reference.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Required: Yes

description

The description for your disk image import.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: No

executionRole

The name or Amazon Resource Name (ARN) for the IAM role you create that grants Image Builder access to perform workflow actions to import an image from a Microsoft ISO file. If you don't provide a role, Image Builder uses the Image Builder service-linked role in your account, and creates it if it doesn't exist.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^(?:arn:aws(?:-[a-z]+)*:iam::[0-9]{12}:role/)?[a-zA-Z_0-9+=,.@\-_/]+$

Required: No

infrastructureConfigurationArn

The Amazon Resource Name (ARN) of the infrastructure configuration resource that's used for launching the EC2 instance on which the ISO image is built.

Type: String

Pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws):infrastructure-configuration/[a-z0-9-_]+$

Required: Yes

loggingConfiguration

The CloudWatch Logs log group where Image Builder sends the import logs. If you specify a log group name outside of the /aws/imagebuilder/ namespace, you must also provide an executionRole that has permission to write to that log group.

Type: ImageLoggingConfiguration object

Required: No

name

The name of the image resource that's created from the import. Image Builder generates the image ARN from a normalized form of the name, so names that differ only in case, spaces, or underscores count as the same name. If an image with the same name and semantic version already exists in your account in the same AWS Region, the import creates a new build version for it.

Type: String

Pattern: ^[-_A-Za-z-0-9][-_A-Za-z0-9 ]{1,126}[-_A-Za-z-0-9]$

Required: Yes

osVersion

The operating system version for the imported image. The only supported value is Microsoft Windows 11.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes

platform

The operating system platform for the imported image. Allowed values include the following: Windows.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: Yes

registerImageOptions

Configures Secure Boot and UEFI settings for the imported image.

Type: RegisterImageOptions object

Required: No

semanticVersion

The semantic version to attach to the image that's created during the import process. This version follows the semantic version syntax.

Type: String

Pattern: ^[0-9]+\.[0-9]+\.[0-9]+$

Required: Yes

tags

Tags that are attached to image resources created from the import.

Type: String to string map

Map Entries: Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: ^(?!aws:)[a-zA-Z0-9\s_.:/=+\-@]*$

Value Length Constraints: Maximum length of 256.

Required: No

uri

The uri of the ISO disk file that's stored in Amazon S3, in s3://bucket/key format. The key must end with the .iso, .ISO, or .Iso extension, and the bucket must be owned by the account that makes the request.

Type: String

Required: Yes

windowsConfiguration

Specifies Windows settings for ISO imports.

Type: WindowsConfiguration object

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "clientToken": "string",
   "imageBuildVersionArn": "string"
}

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.

clientToken

The client token that uniquely identifies the request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

imageBuildVersionArn

The Amazon Resource Name (ARN) of the Image Builder image resource that this request created. The AMI doesn't exist yet when the response returns. The import runs asynchronously, and the output AMI appears in the image's output resources when the import completes.

Type: String

Pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?):image/[a-z0-9-_]+/[0-9]+\.[0-9]+\.[0-9]+/[0-9]+$

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

You do not have permissions to perform the requested operation.

HTTP Status Code: 403

ClientException

A generic client error. This error usually indicates that the request failed a validation check, such as when a downstream service rejects a configured value.

HTTP Status Code: 400

ServiceException

An internal server error occurred while Image Builder processed the request. Retrying the request may succeed.

HTTP Status Code: 500

ServiceUnavailableException

The service is unable to process your request at this time.

HTTP Status Code: 503

TooManyRequestsException

You have attempted too many requests for the specific operation.

HTTP Status Code: 429

Examples

Import a Windows 11 ISO disk image

The following example starts an image build that converts a Windows 11 ISO disk file stored in Amazon S3 into an AMI; the imageBuildVersionArn in the response identifies the Image Builder image resource that tracks the build, not the output AMI.

Sample Request


PUT /ImportDiskImage HTTP/1.1
Content-type: application/json

{
    "name": "my-example-imported-image",
    "semanticVersion": "1.0.0",
    "platform": "Windows",
    "osVersion": "Microsoft Windows 11",
    "uri": "s3://amzn-s3-demo-bucket/Win11_23H2_English_x64.iso",
    "infrastructureConfigurationArn": "arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure",
    "clientToken": "a1b2c3d4-5678-90ab-cdef-EXAMPLE12345"
}

Sample Response


HTTP/1.1 200
Content-type: application/json

{
    "clientToken": "a1b2c3d4-5678-90ab-cdef-EXAMPLE12345",
    "imageBuildVersionArn": "arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-imported-image/1.0.0/1"
}