Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

CreateImageBuilder

Creates an image builder. An image builder is a virtual machine that is used to create an image.

The initial state of the builder is PENDING. When it is ready, the state is RUNNING.

Request Syntax


{
   "AccessEndpoints": [ 
      { 
         "EndpointType": "string",
         "VpceId": "string"
      }
   ],
   "AppstreamAgentVersion": "string",
   "Description": "string",
   "DisplayName": "string",
   "DomainJoinInfo": { 
      "DirectoryName": "string",
      "OrganizationalUnitDistinguishedName": "string"
   },
   "EnableDefaultInternetAccess": boolean,
   "IamRoleArn": "string",
   "ImageArn": "string",
   "ImageName": "string",
   "InstanceType": "string",
   "Name": "string",
   "Tags": { 
      "string" : "string" 
   },
   "VpcConfig": { 
      "SecurityGroupIds": [ "string" ],
      "SubnetIds": [ "string" ]
   }
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

AccessEndpoints

The list of interface VPC endpoint (interface endpoint) objects. Administrators can connect to the image builder only through the specified endpoints.

Type: Array of AccessEndpoint objects

Array Members: Minimum number of 1 item. Maximum number of 4 items.

Required: No

AppstreamAgentVersion

The version of the AppStream 2.0 agent to use for this image builder. To use the latest version of the AppStream 2.0 agent, specify [LATEST].

Type: String

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

Required: No

Description

The description to display.

Type: String

Length Constraints: Maximum length of 256.

Required: No

DisplayName

The image builder name to display.

Type: String

Length Constraints: Maximum length of 100.

Required: No

DomainJoinInfo

The name of the directory and organizational unit (OU) to use to join the image builder to a Microsoft Active Directory domain.

Type: DomainJoinInfo object

Required: No

EnableDefaultInternetAccess

Enables or disables default internet access for the image builder.

Type: Boolean

Required: No

IamRoleArn

The Amazon Resource Name (ARN) of the IAM role to apply to the image builder. To assume a role, the image builder calls the AWS Security Token Service (STS) AssumeRole API operation and passes the ARN of the role to use. The operation creates a new session with temporary credentials. AppStream 2.0 retrieves the temporary credentials and creates the appstream_machine_role credential profile on the instance.

For more information, see Using an IAM Role to Grant Permissions to Applications and Scripts Running on AppStream 2.0 Streaming Instances in the Amazon AppStream 2.0 Administration Guide.

Type: String

Pattern: ^arn:aws(?:\-cn|\-iso\-b|\-iso|\-us\-gov)?:[A-Za-z0-9][A-Za-z0-9_/.-]{0,62}:[A-Za-z0-9_/.-]{0,63}:[A-Za-z0-9_/.-]{0,63}:[A-Za-z0-9][A-Za-z0-9:_/+=,@.\\-]{0,1023}$

Required: No

ImageArn

The ARN of the public, private, or shared image to use.

Type: String

Pattern: ^arn:aws(?:\-cn|\-iso\-b|\-iso|\-us\-gov)?:[A-Za-z0-9][A-Za-z0-9_/.-]{0,62}:[A-Za-z0-9_/.-]{0,63}:[A-Za-z0-9_/.-]{0,63}:[A-Za-z0-9][A-Za-z0-9:_/+=,@.\\-]{0,1023}$

Required: No

ImageName

The name of the image used to create the image builder.

Type: String

Length Constraints: Minimum length of 1.

Required: No

InstanceType

The instance type to use when launching the image builder. The following instance types are available:

stream.standard.small
stream.standard.medium
stream.standard.large
stream.compute.large
stream.compute.xlarge
stream.compute.2xlarge
stream.compute.4xlarge
stream.compute.8xlarge
stream.memory.large
stream.memory.xlarge
stream.memory.2xlarge
stream.memory.4xlarge
stream.memory.8xlarge
stream.memory.z1d.large
stream.memory.z1d.xlarge
stream.memory.z1d.2xlarge
stream.memory.z1d.3xlarge
stream.memory.z1d.6xlarge
stream.memory.z1d.12xlarge
stream.graphics-design.large
stream.graphics-design.xlarge
stream.graphics-design.2xlarge
stream.graphics-design.4xlarge
stream.graphics-desktop.2xlarge
stream.graphics.g4dn.xlarge
stream.graphics.g4dn.2xlarge
stream.graphics.g4dn.4xlarge
stream.graphics.g4dn.8xlarge
stream.graphics.g4dn.12xlarge
stream.graphics.g4dn.16xlarge
stream.graphics-pro.4xlarge
stream.graphics-pro.8xlarge
stream.graphics-pro.16xlarge

Type: String

Length Constraints: Minimum length of 1.

Required: Yes

Name

A unique name for the image builder.

Type: String

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,100}$

Required: Yes

Tags

The tags to associate with the image builder. A tag is a key-value pair, and the value is optional. For example, Environment=Test. If you do not specify a value, Environment=.

Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following special characters:

_ . : / = + \ - @

If you do not specify a value, the value is set to an empty string.

For more information about tags, see Tagging Your Resources in the Amazon AppStream 2.0 Administration Guide.

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:).[\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Value Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Required: No

VpcConfig

The VPC configuration for the image builder. You can specify only one subnet.

Type: VpcConfig object

Required: No

Response Syntax


{
   "ImageBuilder": { 
      "AccessEndpoints": [ 
         { 
            "EndpointType": "string",
            "VpceId": "string"
         }
      ],
      "AppstreamAgentVersion": "string",
      "Arn": "string",
      "CreatedTime": number,
      "Description": "string",
      "DisplayName": "string",
      "DomainJoinInfo": { 
         "DirectoryName": "string",
         "OrganizationalUnitDistinguishedName": "string"
      },
      "EnableDefaultInternetAccess": boolean,
      "IamRoleArn": "string",
      "ImageArn": "string",
      "ImageBuilderErrors": [ 
         { 
            "ErrorCode": "string",
            "ErrorMessage": "string",
            "ErrorTimestamp": number
         }
      ],
      "InstanceType": "string",
      "LatestAppstreamAgentVersion": "string",
      "Name": "string",
      "NetworkAccessConfiguration": { 
         "EniId": "string",
         "EniPrivateIpAddress": "string"
      },
      "Platform": "string",
      "State": "string",
      "StateChangeReason": { 
         "Code": "string",
         "Message": "string"
      },
      "VpcConfig": { 
         "SecurityGroupIds": [ "string" ],
         "SubnetIds": [ "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.

ImageBuilder

Information about the image builder.

Type: ImageBuilder object

Errors

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

ConcurrentModificationException

An API error occurred. Wait a few minutes and try again.

HTTP Status Code: 400

IncompatibleImageException

The image can't be updated because it's not compatible for updates.

HTTP Status Code: 400

InvalidAccountStatusException

The resource cannot be created because your AWS account is suspended. For assistance, contact AWS Support.

HTTP Status Code: 400

InvalidParameterCombinationException

Indicates an incorrect combination of parameters, or a missing parameter.

HTTP Status Code: 400

InvalidRoleException

The specified role is invalid.

HTTP Status Code: 400

LimitExceededException

The requested limit exceeds the permitted limit for an account.

HTTP Status Code: 400

OperationNotPermittedException

The attempted operation is not permitted.

HTTP Status Code: 400

RequestLimitExceededException

AppStream 2.0 can’t process the request right now because the Describe calls from your AWS account are being throttled by Amazon EC2. Try again later.

HTTP Status Code: 400

ResourceAlreadyExistsException

The specified resource already exists.

HTTP Status Code: 400

ResourceNotAvailableException

The specified resource exists and is not in use, but isn't available.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource was not found.

HTTP Status Code: 400