2026/10/14 - EC2 Image Builder - 4 updated api methods
Changes This release adds parentInstance to infrastructure configurations, so builds can use an already-running instance from an Amazon EC2 Auto Scaling group. It also adds terminateInstanceOnCompletion, which keeps build and test instances running after image creation ends.
{'parentInstance': {'autoScalingGroup': {'capacityWaitTimeoutSeconds': 'integer',
'name': 'string'}},
'terminateInstanceOnCompletion': 'boolean'}
Creates a new infrastructure configuration. An infrastructure configuration defines the environment in which your image will be built and tested.
See also: AWS API Documentation
Request Syntax
client.create_infrastructure_configuration(
name='string',
description='string',
instanceTypes=[
'string',
],
instanceProfileName='string',
securityGroupIds=[
'string',
],
subnetId='string',
logging={
's3Logs': {
's3BucketName': 'string',
's3KeyPrefix': 'string'
}
},
keyPair='string',
terminateInstanceOnFailure=True|False,
terminateInstanceOnCompletion=True|False,
snsTopicArn='string',
resourceTags={
'string': 'string'
},
instanceMetadataOptions={
'httpTokens': 'string',
'httpPutResponseHopLimit': 123
},
tags={
'string': 'string'
},
placement={
'availabilityZone': 'string',
'tenancy': 'default'|'dedicated'|'host',
'hostId': 'string',
'hostResourceGroupArn': 'string'
},
parentInstance={
'autoScalingGroup': {
'name': 'string',
'capacityWaitTimeoutSeconds': 123
}
},
clientToken='string',
dryRun=True|False
)
string
[REQUIRED]
The name of the infrastructure configuration. Infrastructure configuration names must be unique to your account in each Amazon Web Services Region. Image Builder generates the infrastructure configuration ARN from a normalized form of the name, so names that differ only in case, spaces, or underscores count as the same name.
string
The description of the infrastructure configuration.
list
The instance types of the infrastructure configuration. You can specify one or more instance types to use for this build. Image Builder picks one of these instance types based on availability. If you don't specify instance types, Image Builder selects compatible instance types automatically. If you specify a Dedicated Host, Image Builder uses only instance types that the host supports.
(string) --
string
[REQUIRED]
The instance profile to associate with the instance used to customize your Amazon EC2 AMI. The instance profile must exist in your account.
list
The security group IDs to associate with the instance used to customize your Amazon EC2 AMI.
(string) --
string
The subnet ID in which to place the instance used to customize your Amazon EC2 AMI. If you specify subnetId, you must also specify one or more security group IDs in securityGroupIds. Otherwise, the request fails.
dict
The logging configuration of the infrastructure configuration. When you configure S3 logs, Image Builder writes logs from the build and test process to the specified bucket under the key prefix.
s3Logs (dict) --
The Amazon S3 logging configuration.
s3BucketName (string) --
The name of an existing Amazon S3 bucket where Image Builder saves build logs. The bucket isn't validated when you create or update the configuration, and Image Builder doesn't create it. The instance profile associated with this infrastructure configuration must have permission to write to the bucket.
s3KeyPrefix (string) --
The Amazon S3 key prefix under which Image Builder writes build and test logs in the bucket.
string
The key pair of the infrastructure configuration. You can use this to log on to and debug the instance used to create your image.
boolean
Specifies whether to terminate the instance on failure. Set to false if you want Image Builder to retain the instance used to configure your AMI if the build or test phase of your workflow fails. Defaults to true.
boolean
Specifies whether Image Builder terminates build and test instances when image creation ends without a failure (success, cancellation, or expiration). Defaults to true.
string
The Amazon Resource Name (ARN) of the SNS topic to which Image Builder sends image build event notifications. Specify a standard topic. Image Builder doesn't support FIFO topics. Image Builder validates the topic when you create or update the configuration. You must have permission to publish to the topic.
dict
The metadata tags to assign to the Amazon EC2 instance that Image Builder launches during the build process. Tags are formatted as key value pairs. Tag keys can't begin with aws: or match one of the following reserved keys: CreatedBy, Ec2ImageBuilderArn, Name, or Tags.
(string) --
(string) --
dict
The instance metadata service (IMDS) settings that Image Builder applies to the EC2 build and test instances it launches during image creation. If you don't set these options, the EC2 launch defaults for the instance apply. For more information about instance metadata options, see one of the following links:
Configure the instance metadata options in the Amazon EC2 User Guide for Linux instances.
Configure the instance metadata options in the Amazon EC2 Windows Guide for Windows instances.
httpTokens (string) --
Indicates whether a signed token header is required for instance metadata retrieval requests. The values affect the response as follows:
required – When you retrieve the IAM role credentials, version 2.0 credentials are returned in all cases.
optional – You can include a signed token header in your request to retrieve instance metadata, or you can leave it out. If you include it, version 2.0 credentials are returned for the IAM role. Otherwise, version 1.0 credentials are returned.
If you don't set a value, the EC2 launch default applies to the build and test instances. That default depends on the base AMI and any account-level instance metadata defaults. For more information, see Configure the instance metadata options in the Amazon EC2 User Guide .
httpPutResponseHopLimit (integer) --
Limit the number of hops that an instance metadata request can traverse to reach its destination. If you don't set a value, the EC2 launch default for the instance applies. If HTTP tokens are required, container image builds need a minimum of two hops.
dict
The metadata tags to assign to the infrastructure configuration resource that Image Builder creates as output. Tags are formatted as key value pairs.
(string) --
(string) --
dict
The instance placement settings that define where the build and test instances that Image Builder launches during image creation run. These settings don't affect instances that you launch from the output image.
availabilityZone (string) --
The Availability Zone where your build and test instances will launch.
tenancy (string) --
The tenancy of the instance. An instance with a tenancy of dedicated runs on single-tenant hardware. An instance with a tenancy of host runs on a Dedicated Host.
If tenancy is set to host, then you can optionally specify one target for placement – either host ID or host resource group ARN. If automatic placement is enabled for your host, and you don't specify any placement target, Amazon EC2 will try to find an available host for your build and test instances.
hostId (string) --
The ID of the Dedicated Host on which build and test instances run. This only applies if tenancy is host.
hostResourceGroupArn (string) --
The Amazon Resource Name (ARN) of the host resource group in which to launch build and test instances. This only applies if tenancy is host.
dict
The Amazon EC2 Auto Scaling group that Image Builder takes the build instance from, instead of launching a new instance. This applies only to the build phase.
To use this feature, the execution role for the build must have permissions to describe the Auto Scaling group, tag the instance while it's still in the group, and detach it from the group. For more information, see Build on an instance from an Auto Scaling group in the EC2 Image Builder User Guide.
autoScalingGroup (dict) -- [REQUIRED]
The Amazon EC2 Auto Scaling group that Image Builder takes the build instance from. This is required when you specify parentInstance.
name (string) -- [REQUIRED]
The name of the Auto Scaling group, in the same account and Amazon Web Services Region as the infrastructure configuration. To specify a group, you must have permissions to describe it.
capacityWaitTimeoutSeconds (integer) --
The number of seconds that Image Builder waits for an instance to become available in the group before the build fails. If you set this value to 0 or omit it, the build fails as soon as the group has no instance available.
string
[REQUIRED]
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.
This field is autopopulated if not provided.
boolean
Validates the required permissions and request parameters without performing the operation. If validation succeeds, the operation returns a DryRunOperationException error response.
dict
Response Syntax
{
'requestId': 'string',
'clientToken': 'string',
'infrastructureConfigurationArn': 'string'
}
Response Structure
(dict) --
requestId (string) --
The request ID that uniquely identifies this request.
clientToken (string) --
The client token that uniquely identifies the request.
infrastructureConfigurationArn (string) --
The Amazon Resource Name (ARN) of the infrastructure configuration that was created by this request.
{'image': {'infrastructureConfiguration': {'parentInstance': {'autoScalingGroup': {'capacityWaitTimeoutSeconds': 'integer',
'name': 'string'}},
'terminateInstanceOnCompletion': 'boolean'}}}
Retrieves an image.
See also: AWS API Documentation
Request Syntax
client.get_image(
imageBuildVersionArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the image that you want to get. You can specify a full build version ARN, or a version ARN with or without wildcards ( x.x.x, 1.x.x, or 1.0.x). A version or wildcard ARN resolves to the latest matching build version that has reached AVAILABLE status. Builds that were later deprecated, disabled, or deleted don't resolve. To get an image in any other state, such as a failed or in-progress build, specify the full build version ARN.
dict
Response Syntax
{
'requestId': 'string',
'image': {
'arn': 'string',
'type': 'AMI'|'DOCKER',
'name': 'string',
'version': 'string',
'platform': 'Windows'|'Linux'|'macOS',
'enhancedImageMetadataEnabled': True|False,
'osVersion': 'string',
'state': {
'status': 'PENDING'|'CREATING'|'BUILDING'|'TESTING'|'DISTRIBUTING'|'INTEGRATING'|'AVAILABLE'|'CANCELLED'|'FAILED'|'DEPRECATED'|'DELETED'|'DISABLED',
'reason': 'string',
'failureContext': {
'imageStatus': 'PENDING'|'CREATING'|'BUILDING'|'TESTING'|'DISTRIBUTING'|'INTEGRATING'|'AVAILABLE'|'CANCELLED'|'FAILED'|'DEPRECATED'|'DELETED'|'DISABLED',
'workflowExecutionId': 'string',
'workflowArn': 'string',
'stepExecutionId': 'string',
'failedStep': 'string',
'componentFailure': {
'componentArn': 'string',
'phaseName': 'string',
'stepName': 'string',
'action': 'string',
'errorMessage': 'string'
},
'distributionFailure': {
'errorMessage': 'string',
'regionFailures': [
{
'region': 'string',
'status': 'FAILED'|'CANCELLED'|'TIMED_OUT',
'imageConfigurationStep': 'ASSOCIATE_LICENSES'|'UPDATE_LAUNCH_TEMPLATES'|'PUT_SSM_PARAMETERS'|'UPDATE_FAST_LAUNCH_CONFIGURATIONS'|'EXPORT_AMI',
'errorMessage': 'string',
'targetAccountId': 'string'
},
]
}
}
},
'imageRecipe': {
'arn': 'string',
'type': 'AMI'|'DOCKER',
'name': 'string',
'description': 'string',
'platform': 'Windows'|'Linux'|'macOS',
'owner': 'string',
'version': 'string',
'components': [
{
'componentArn': 'string',
'parameters': [
{
'name': 'string',
'value': [
'string',
]
},
]
},
],
'parentImage': 'string',
'blockDeviceMappings': [
{
'deviceName': 'string',
'ebs': {
'encrypted': True|False,
'deleteOnTermination': True|False,
'iops': 123,
'kmsKeyId': 'string',
'snapshotId': 'string',
'volumeSize': 123,
'volumeType': 'standard'|'io1'|'io2'|'gp2'|'gp3'|'sc1'|'st1',
'throughput': 123
},
'virtualName': 'string',
'noDevice': 'string'
},
],
'dateCreated': 'string',
'tags': {
'string': 'string'
},
'workingDirectory': 'string',
'additionalInstanceConfiguration': {
'systemsManagerAgent': {
'uninstallAfterBuild': True|False
},
'userDataOverride': 'string'
},
'amiTags': {
'string': 'string'
},
'amiWatermarks': [
'string',
]
},
'containerRecipe': {
'arn': 'string',
'containerType': 'DOCKER',
'name': 'string',
'description': 'string',
'platform': 'Windows'|'Linux'|'macOS',
'owner': 'string',
'version': 'string',
'components': [
{
'componentArn': 'string',
'parameters': [
{
'name': 'string',
'value': [
'string',
]
},
]
},
],
'instanceConfiguration': {
'image': 'string',
'blockDeviceMappings': [
{
'deviceName': 'string',
'ebs': {
'encrypted': True|False,
'deleteOnTermination': True|False,
'iops': 123,
'kmsKeyId': 'string',
'snapshotId': 'string',
'volumeSize': 123,
'volumeType': 'standard'|'io1'|'io2'|'gp2'|'gp3'|'sc1'|'st1',
'throughput': 123
},
'virtualName': 'string',
'noDevice': 'string'
},
]
},
'dockerfileTemplateData': 'string',
'kmsKeyId': 'string',
'encrypted': True|False,
'parentImage': 'string',
'dateCreated': 'string',
'tags': {
'string': 'string'
},
'workingDirectory': 'string',
'targetRepository': {
'service': 'ECR',
'repositoryName': 'string'
}
},
'sourcePipelineName': 'string',
'sourcePipelineArn': 'string',
'infrastructureConfiguration': {
'arn': 'string',
'name': 'string',
'description': 'string',
'instanceTypes': [
'string',
],
'instanceProfileName': 'string',
'securityGroupIds': [
'string',
],
'subnetId': 'string',
'logging': {
's3Logs': {
's3BucketName': 'string',
's3KeyPrefix': 'string'
}
},
'keyPair': 'string',
'terminateInstanceOnFailure': True|False,
'snsTopicArn': 'string',
'dateCreated': 'string',
'dateUpdated': 'string',
'resourceTags': {
'string': 'string'
},
'instanceMetadataOptions': {
'httpTokens': 'string',
'httpPutResponseHopLimit': 123
},
'tags': {
'string': 'string'
},
'placement': {
'availabilityZone': 'string',
'tenancy': 'default'|'dedicated'|'host',
'hostId': 'string',
'hostResourceGroupArn': 'string'
},
'terminateInstanceOnCompletion': True|False,
'parentInstance': {
'autoScalingGroup': {
'name': 'string',
'capacityWaitTimeoutSeconds': 123
}
}
},
'distributionConfiguration': {
'arn': 'string',
'name': 'string',
'description': 'string',
'distributions': [
{
'region': 'string',
'amiDistributionConfiguration': {
'name': 'string',
'description': 'string',
'targetAccountIds': [
'string',
],
'amiTags': {
'string': 'string'
},
'kmsKeyId': 'string',
'launchPermission': {
'userIds': [
'string',
],
'userGroups': [
'string',
],
'organizationArns': [
'string',
],
'organizationalUnitArns': [
'string',
]
}
},
'containerDistributionConfiguration': {
'description': 'string',
'containerTags': [
'string',
],
'targetRepository': {
'service': 'ECR',
'repositoryName': 'string'
}
},
'licenseConfigurationArns': [
'string',
],
'launchTemplateConfigurations': [
{
'launchTemplateId': 'string',
'accountId': 'string',
'setDefaultVersion': True|False
},
],
's3ExportConfiguration': {
'roleName': 'string',
'diskImageFormat': 'VMDK'|'RAW'|'VHD',
's3Bucket': 'string',
's3Prefix': 'string'
},
'fastLaunchConfigurations': [
{
'enabled': True|False,
'snapshotConfiguration': {
'targetResourceCount': 123
},
'maxParallelLaunches': 123,
'launchTemplate': {
'launchTemplateId': 'string',
'launchTemplateName': 'string',
'launchTemplateVersion': 'string'
},
'accountId': 'string'
},
],
'ssmParameterConfigurations': [
{
'amiAccountId': 'string',
'parameterName': 'string',
'dataType': 'text'|'aws:ec2:image'
},
]
},
],
'timeoutMinutes': 123,
'dateCreated': 'string',
'dateUpdated': 'string',
'tags': {
'string': 'string'
}
},
'imageTestsConfiguration': {
'imageTestsEnabled': True|False,
'timeoutMinutes': 123
},
'dateCreated': 'string',
'outputResources': {
'amis': [
{
'region': 'string',
'image': 'string',
'name': 'string',
'description': 'string',
'state': {
'status': 'PENDING'|'CREATING'|'BUILDING'|'TESTING'|'DISTRIBUTING'|'INTEGRATING'|'AVAILABLE'|'CANCELLED'|'FAILED'|'DEPRECATED'|'DELETED'|'DISABLED',
'reason': 'string',
'failureContext': {
'imageStatus': 'PENDING'|'CREATING'|'BUILDING'|'TESTING'|'DISTRIBUTING'|'INTEGRATING'|'AVAILABLE'|'CANCELLED'|'FAILED'|'DEPRECATED'|'DELETED'|'DISABLED',
'workflowExecutionId': 'string',
'workflowArn': 'string',
'stepExecutionId': 'string',
'failedStep': 'string',
'componentFailure': {
'componentArn': 'string',
'phaseName': 'string',
'stepName': 'string',
'action': 'string',
'errorMessage': 'string'
},
'distributionFailure': {
'errorMessage': 'string',
'regionFailures': [
{
'region': 'string',
'status': 'FAILED'|'CANCELLED'|'TIMED_OUT',
'imageConfigurationStep': 'ASSOCIATE_LICENSES'|'UPDATE_LAUNCH_TEMPLATES'|'PUT_SSM_PARAMETERS'|'UPDATE_FAST_LAUNCH_CONFIGURATIONS'|'EXPORT_AMI',
'errorMessage': 'string',
'targetAccountId': 'string'
},
]
}
}
},
'accountId': 'string'
},
],
'containers': [
{
'region': 'string',
'imageUris': [
'string',
]
},
]
},
'tags': {
'string': 'string'
},
'buildType': 'USER_INITIATED'|'SCHEDULED'|'IMPORT'|'IMPORT_ISO',
'imageSource': 'AMAZON_MANAGED'|'AWS_MARKETPLACE'|'IMPORTED'|'CUSTOM',
'scanState': {
'status': 'PENDING'|'SCANNING'|'COLLECTING'|'COMPLETED'|'ABANDONED'|'FAILED'|'TIMED_OUT',
'reason': 'string'
},
'imageScanningConfiguration': {
'imageScanningEnabled': True|False,
'ecrConfiguration': {
'repositoryName': 'string',
'containerTags': [
'string',
]
}
},
'deprecationTime': datetime(2015, 1, 1),
'lifecycleExecutionId': 'string',
'executionRole': 'string',
'workflows': [
{
'workflowArn': 'string',
'parameters': [
{
'name': 'string',
'value': [
'string',
]
},
],
'parallelGroup': 'string',
'onFailure': 'CONTINUE'|'ABORT'
},
],
'loggingConfiguration': {
'logGroupName': 'string'
}
},
'latestVersionReferences': {
'latestVersionArn': 'string',
'latestMajorVersionArn': 'string',
'latestMinorVersionArn': 'string',
'latestPatchVersionArn': 'string'
}
}
Response Structure
(dict) --
requestId (string) --
The request ID that uniquely identifies this request.
image (dict) --
The image object.
arn (string) --
The Amazon Resource Name (ARN) of the image.
type (string) --
Specifies whether this image produces an AMI or a container image.
name (string) --
The name of the image.
version (string) --
The semantic version of the image.
platform (string) --
The image operating system platform, such as Linux or Windows.
enhancedImageMetadataEnabled (boolean) --
Indicates whether Image Builder collects additional information about the image, such as the operating system (OS) version and package list.
osVersion (string) --
The operating system version for instances that launch from this image. For example, Amazon Linux 2, Ubuntu 18, or Microsoft Windows Server 2019.
state (dict) --
The state of the image.
status (string) --
The status of the image. A new image moves through build, test, and distribution statuses during creation, and ends in the AVAILABLE, FAILED, or CANCELLED state. The DEPRECATED, DISABLED, and DELETED statuses come from later resource management actions.
reason (string) --
The reason for the status of the image.
failureContext (dict) --
The details about the failure, for images that failed to complete. Image Builder only sets this property when the image status is FAILED.
imageStatus (string) --
The status that the image had when the failure occurred. This indicates the stage of the image creation process where the image failed, for example BUILDING or DISTRIBUTING.
workflowExecutionId (string) --
The unique identifier of the workflow execution that was running when the image failed.
workflowArn (string) --
The Amazon Resource Name (ARN) of the workflow build version that was running when the image failed.
stepExecutionId (string) --
The unique identifier of the workflow step execution that failed.
failedStep (string) --
The name of the workflow step that failed, as it appears in the workflow document.
componentFailure (dict) --
The details about the component that failed, if the failure occurred while a component was running.
componentArn (string) --
The Amazon Resource Name (ARN) of the component build version that failed.
phaseName (string) --
The name of the phase in the component document where the failure occurred, such as build, validate, or test.
stepName (string) --
The name of the step in the component document that failed.
action (string) --
The action that the failed step runs, for example ExecuteBash.
errorMessage (string) --
The error message from the step that failed. Image Builder truncates messages that are longer than 1024 characters. The component log in Amazon CloudWatch Logs contains the full output.
distributionFailure (dict) --
The details about the distribution failure, if the failure occurred while Image Builder distributed or configured the image.
errorMessage (string) --
The error message for the distribution failure.
regionFailures (list) --
The details about the failure for each Region where the image didn't finish distribution or configuration.
(dict) --
Contains details about a distribution or image configuration failure for a single Region.
region (string) --
The Region where the failure occurred.
status (string) --
The failure status for the Region. Indicates whether the process failed, was canceled, or timed out.
imageConfigurationStep (string) --
The image configuration step where the failure occurred. Image Builder sets this property when the failure happened during post-distribution configuration, such as launch template updates or virtual machine (VM) export. This property doesn't appear for failures that occurred while Image Builder copied the image to the Region.
errorMessage (string) --
The error message for the failure in the Region.
targetAccountId (string) --
The account ID of the account that the image was distributed to in the Region.
imageRecipe (dict) --
For images that distribute an AMI, this is the image recipe that Image Builder used to create the image. For container images, this is empty.
arn (string) --
The Amazon Resource Name (ARN) of the image recipe.
type (string) --
The output image type. For an image recipe, this is always AMI. Container images are built from container recipes, a separate resource. This field isn't currently returned in responses.
name (string) --
The name of the image recipe.
description (string) --
The description of the image recipe.
platform (string) --
The platform of the image recipe.
owner (string) --
The owner of the image recipe.
version (string) --
The version of the image recipe.
components (list) --
The components that are included in the image recipe. A recipe can contain a maximum of 20 build and test components in any combination, by default. This maximum is an adjustable quota. For more information, see EC2 Image Builder endpoints and quotas in the Amazon Web Services General Reference.
(dict) --
Configuration details of the component. You can specify each component only once in a recipe, regardless of version. Components with a status of DEPRECATED or DISABLED can't be added to new recipes.
componentArn (string) --
The Amazon Resource Name (ARN) of the component. You can specify a build version ARN, or a component version ARN whose version segments can use x wildcards, for example 1.x.x.
parameters (list) --
A group of parameter settings that Image Builder uses to configure the component for a specific recipe. You must supply a value for every component parameter that has no default value, and you can only supply parameters that the component defines.
(dict) --
Contains a key/value pair that sets the named component parameter.
name (string) --
The name of the component parameter to set.
value (list) --
Sets the value for the named component parameter.
(string) --
parentImage (string) --
The base image for customizations specified in the image recipe. You can specify the parent image using one of the following options:
AMI ID
Image Builder image Amazon Resource Name (ARN)
Amazon Web Services Systems Manager (SSM) Parameter Store Parameter, prefixed by ssm:, followed by the parameter name or ARN.
Amazon Web Services Marketplace product ID
blockDeviceMappings (list) --
The block device mappings to apply when creating images from this recipe.
(dict) --
Defines block device mappings for the instance used to configure your image.
deviceName (string) --
The device to which these mappings apply.
ebs (dict) --
The Amazon EBS-specific configuration for this mapping.
encrypted (boolean) --
Specifies whether to encrypt the device.
deleteOnTermination (boolean) --
Specifies whether to delete the associated device on termination.
iops (integer) --
The IOPS value for the device. Required only when volumeType is io1 or io2.
kmsKeyId (string) --
The Amazon Resource Name (ARN) that uniquely identifies the KMS key to use when encrypting the device. This can be either the Key ARN or the Alias ARN. For more information, see Key identifiers (KeyId) in the Key Management Service Developer Guide.
snapshotId (string) --
The snapshot that defines the device contents.
volumeSize (integer) --
Overrides the volume size for the device.
volumeType (string) --
Overrides the volume type for the device.
throughput (integer) --
For GP3 volumes only – The throughput in MiB/s that the volume supports.
virtualName (string) --
The virtual device name for instance ephemeral devices.
noDevice (string) --
Specifies a mapping to remove from the base image.
dateCreated (string) --
The date on which this image recipe was created.
tags (dict) --
The tags of the image recipe.
(string) --
(string) --
workingDirectory (string) --
The working directory used during build and test workflows. If you don't specify a working directory, Image Builder uses /tmp for Linux and macOS build instances, and C:/ for Windows build instances.
additionalInstanceConfiguration (dict) --
Before you create a new AMI, Image Builder launches temporary Amazon EC2 instances to build and test your image configuration. Instance configuration adds a layer of control over those instances. You can define settings and add scripts to run when Image Builder launches your build instance.
systemsManagerAgent (dict) --
The Systems Manager agent settings for your build instance. This setting applies to Linux and macOS build instances only. Requests that set it for a recipe with a Windows base image are rejected.
uninstallAfterBuild (boolean) --
Specifies whether the Systems Manager agent is removed from your final build image before Image Builder creates the new AMI. If true, the agent is removed. If false, the agent is kept, so that it's included in the AMI. If you don't set this property, Image Builder removes the agent only if Image Builder installed the agent during the build. An agent that was pre-installed on the base image is kept.
userDataOverride (string) --
Use this property to provide commands or a command script to run when you launch your build instance.
The userDataOverride property replaces any commands that Image Builder might have added to ensure that Systems Manager is installed on your Linux build instance. If you override the user data, make sure that you add commands to install Systems Manager, if it is not pre-installed on your base image.
amiTags (dict) --
Tags that are applied to the AMI that Image Builder creates during the Build phase prior to image distribution.
(string) --
(string) --
amiWatermarks (list) --
The AMI watermark names attached to the output AMI from this recipe. AMI watermarks are lineage markers that automatically propagate to derivative AMIs when the source AMI is copied or distributed.
(string) --
The name of an AMI watermark. AMI watermarks are lineage markers that Image Builder attaches to output AMIs during the build process. AMI watermarks automatically propagate to derivative AMIs when the source AMI is copied or distributed.
containerRecipe (dict) --
For container images, this is the container recipe that Image Builder used to create the image. For images that distribute an AMI, this is empty.
arn (string) --
The Amazon Resource Name (ARN) of the container recipe.
containerType (string) --
Specifies the type of container, such as Docker.
name (string) --
The name of the container recipe.
description (string) --
The description of the container recipe.
platform (string) --
The system platform for the container. Container recipes support only the Linux and Windows platforms.
owner (string) --
The owner of the container recipe.
version (string) --
The semantic version of the container recipe.
components (list) --
Build and test components that are included in the container recipe. A recipe can contain a maximum of 20 build and test components in any combination, by default. This maximum is an adjustable quota. For more information, see EC2 Image Builder endpoints and quotas in the Amazon Web Services General Reference.
(dict) --
Configuration details of the component. You can specify each component only once in a recipe, regardless of version. Components with a status of DEPRECATED or DISABLED can't be added to new recipes.
componentArn (string) --
The Amazon Resource Name (ARN) of the component. You can specify a build version ARN, or a component version ARN whose version segments can use x wildcards, for example 1.x.x.
parameters (list) --
A group of parameter settings that Image Builder uses to configure the component for a specific recipe. You must supply a value for every component parameter that has no default value, and you can only supply parameters that the component defines.
(dict) --
Contains a key/value pair that sets the named component parameter.
name (string) --
The name of the component parameter to set.
value (list) --
Sets the value for the named component parameter.
(string) --
instanceConfiguration (dict) --
A group of options that can be used to configure an instance for building and testing container images.
image (string) --
The base image for a container build and test instance. This can contain an AMI ID or it can specify an Amazon Web Services Systems Manager (SSM) Parameter Store Parameter, prefixed by ssm:, followed by the parameter name or ARN.
If not specified, Image Builder uses the appropriate ECS-optimized AMI as a base image.
blockDeviceMappings (list) --
Defines the block device mappings for the EC2 instance that Image Builder launches to build and test your container image.
(dict) --
Defines block device mappings for the instance used to configure your image.
deviceName (string) --
The device to which these mappings apply.
ebs (dict) --
The Amazon EBS-specific configuration for this mapping.
encrypted (boolean) --
Specifies whether to encrypt the device.
deleteOnTermination (boolean) --
Specifies whether to delete the associated device on termination.
iops (integer) --
The IOPS value for the device. Required only when volumeType is io1 or io2.
kmsKeyId (string) --
The Amazon Resource Name (ARN) that uniquely identifies the KMS key to use when encrypting the device. This can be either the Key ARN or the Alias ARN. For more information, see Key identifiers (KeyId) in the Key Management Service Developer Guide.
snapshotId (string) --
The snapshot that defines the device contents.
volumeSize (integer) --
Overrides the volume size for the device.
volumeType (string) --
Overrides the volume type for the device.
throughput (integer) --
For GP3 volumes only – The throughput in MiB/s that the volume supports.
virtualName (string) --
The virtual device name for instance ephemeral devices.
noDevice (string) --
Specifies a mapping to remove from the base image.
dockerfileTemplateData (string) --
The Dockerfile template that Image Builder uses to build the container image. The template can include contextual variables that Image Builder replaces with build information at build time. For the contextual variables that the template can include, see Create a new version of a container recipe in the EC2 Image Builder User Guide.
kmsKeyId (string) --
The KMS key that Image Builder uses to encrypt the recipe's Dockerfile template data at rest. This can be either the Key ARN or the Alias ARN. For more information, see Key identifiers (KeyId) in the Key Management Service Developer Guide. If you don't specify a key, Image Builder encrypts the template data with a KMS key that Image Builder owns. This key isn't used to encrypt the output container image.
encrypted (boolean) --
Specifies whether the recipe's Dockerfile template data is encrypted at rest. Image Builder encrypts all Dockerfile template data at rest, so this value is always true. This field is retained for backward compatibility, and doesn't describe encryption of the output container image.
parentImage (string) --
The base image for customizations specified in the container recipe. This can contain an Image Builder image resource ARN or a container image URI, for example amazonlinux:latest.
dateCreated (string) --
The date when this container recipe was created.
tags (dict) --
Tags that are attached to the container recipe.
(string) --
(string) --
workingDirectory (string) --
The working directory for use during build and test workflows.
targetRepository (dict) --
The destination repository for the container image.
service (string) --
Specifies the service in which this image was registered.
repositoryName (string) --
The name of the container repository where the output container image is stored. Provide the repository name only (a namespace path such as team-a/my-repo is allowed, but not the registry hostname).
sourcePipelineName (string) --
The name of the image pipeline that created this image. Image Builder doesn't return this field for new images. Use sourcePipelineArn instead.
sourcePipelineArn (string) --
The Amazon Resource Name (ARN) of the image pipeline that created this image. This field is only present for images that a pipeline execution created.
infrastructureConfiguration (dict) --
The infrastructure that Image Builder used to create this image.
arn (string) --
The Amazon Resource Name (ARN) of the infrastructure configuration.
name (string) --
The name of the infrastructure configuration.
description (string) --
The description of the infrastructure configuration.
instanceTypes (list) --
The instance types of the infrastructure configuration.
(string) --
instanceProfileName (string) --
The instance profile of the infrastructure configuration.
securityGroupIds (list) --
The security group IDs of the infrastructure configuration.
(string) --
subnetId (string) --
The subnet ID of the infrastructure configuration.
logging (dict) --
The logging configuration of the infrastructure configuration. When you configure S3 logs, Image Builder writes logs from the build and test process to the specified bucket under the key prefix.
s3Logs (dict) --
The Amazon S3 logging configuration.
s3BucketName (string) --
The name of an existing Amazon S3 bucket where Image Builder saves build logs. The bucket isn't validated when you create or update the configuration, and Image Builder doesn't create it. The instance profile associated with this infrastructure configuration must have permission to write to the bucket.
s3KeyPrefix (string) --
The Amazon S3 key prefix under which Image Builder writes build and test logs in the bucket.
keyPair (string) --
The Amazon EC2 key pair of the infrastructure configuration.
terminateInstanceOnFailure (boolean) --
Indicates whether Image Builder terminates the build and test instances when the image build fails. When false, Image Builder retains the instance so that you can debug it.
snsTopicArn (string) --
The Amazon Resource Name (ARN) of the SNS topic to which Image Builder sends image build event notifications. Specify a standard topic. Image Builder doesn't support FIFO topics.
dateCreated (string) --
The date on which the infrastructure configuration was created.
dateUpdated (string) --
The date on which the infrastructure configuration was last updated.
resourceTags (dict) --
The metadata tags assigned to the Amazon EC2 build and test instances that Image Builder launches during image creation.
(string) --
(string) --
instanceMetadataOptions (dict) --
The instance metadata option settings for the infrastructure configuration.
httpTokens (string) --
Indicates whether a signed token header is required for instance metadata retrieval requests. The values affect the response as follows:
required – When you retrieve the IAM role credentials, version 2.0 credentials are returned in all cases.
optional – You can include a signed token header in your request to retrieve instance metadata, or you can leave it out. If you include it, version 2.0 credentials are returned for the IAM role. Otherwise, version 1.0 credentials are returned.
If you don't set a value, the EC2 launch default applies to the build and test instances. That default depends on the base AMI and any account-level instance metadata defaults. For more information, see Configure the instance metadata options in the Amazon EC2 User Guide .
httpPutResponseHopLimit (integer) --
Limit the number of hops that an instance metadata request can traverse to reach its destination. If you don't set a value, the EC2 launch default for the instance applies. If HTTP tokens are required, container image builds need a minimum of two hops.
tags (dict) --
The tags of the infrastructure configuration.
(string) --
(string) --
placement (dict) --
The instance placement settings that define where the build and test instances that Image Builder launches during image creation run. These settings don't affect instances that you launch from the output image.
availabilityZone (string) --
The Availability Zone where your build and test instances will launch.
tenancy (string) --
The tenancy of the instance. An instance with a tenancy of dedicated runs on single-tenant hardware. An instance with a tenancy of host runs on a Dedicated Host.
If tenancy is set to host, then you can optionally specify one target for placement – either host ID or host resource group ARN. If automatic placement is enabled for your host, and you don't specify any placement target, Amazon EC2 will try to find an available host for your build and test instances.
hostId (string) --
The ID of the Dedicated Host on which build and test instances run. This only applies if tenancy is host.
hostResourceGroupArn (string) --
The Amazon Resource Name (ARN) of the host resource group in which to launch build and test instances. This only applies if tenancy is host.
terminateInstanceOnCompletion (boolean) --
Specifies whether Image Builder terminates build and test instances when image creation ends without a failure.
parentInstance (dict) --
The Amazon EC2 Auto Scaling group that Image Builder takes the build instance from, instead of launching a new instance. This applies only to the build phase.
autoScalingGroup (dict) --
The Amazon EC2 Auto Scaling group that Image Builder takes the build instance from. This is required when you specify parentInstance.
name (string) --
The name of the Auto Scaling group, in the same account and Amazon Web Services Region as the infrastructure configuration. To specify a group, you must have permissions to describe it.
capacityWaitTimeoutSeconds (integer) --
The number of seconds that Image Builder waits for an instance to become available in the group before the build fails. If you set this value to 0 or omit it, the build fails as soon as the group has no instance available.
distributionConfiguration (dict) --
The distribution configuration that Image Builder used to create this image.
arn (string) --
The Amazon Resource Name (ARN) of the distribution configuration.
name (string) --
The name of the distribution configuration.
description (string) --
The description of the distribution configuration.
distributions (list) --
The distribution objects that apply Region-specific settings for the deployment of the image to targeted Regions.
(dict) --
Defines the settings for a specific Region.
region (string) --
The target Region.
amiDistributionConfiguration (dict) --
The specific AMI settings; for example, launch permissions or AMI tags.
name (string) --
The name of the output AMI. The name must include the {{ imagebuilder:buildDate }} dynamic tag so that each build produces a uniquely named AMI. If you don't specify a name, Image Builder names the output AMI with the image name followed by the build timestamp, for example my-image 2022-10-26T22-30-05.912619Z.
description (string) --
The description to apply to the distributed AMI. Image Builder sets this as the output AMI's description in each target Region and account. If you don't specify a description, the AMI in the build Region uses the image recipe's description, if the recipe has one. Copies distributed to other Regions and accounts don't receive a default description.
targetAccountIds (list) --
The Amazon Web Services account IDs to distribute the AMI to in this Region. Each listed account receives its own copy of the output AMI. If you don't specify accounts, Image Builder distributes the AMI only to your own account.
(string) --
amiTags (dict) --
The tags to apply to AMIs distributed to this Region.
(string) --
(string) --
kmsKeyId (string) --
The Amazon Resource Name (ARN) that uniquely identifies the KMS key used to encrypt the distributed image. This can be either the Key ARN or the Alias ARN. For more information, see Key identifiers (KeyId) in the Key Management Service Developer Guide.
launchPermission (dict) --
Launch permissions can be used to configure which Amazon Web Services accounts can use the AMI to launch instances.
userIds (list) --
The Amazon Web Services account IDs to grant launch permission to. Each listed account can use the distributed AMI to launch instances.
(string) --
userGroups (list) --
The name of the group that you want to grant launch permission to. The only supported value is all, which makes the distributed AMI public.
(string) --
organizationArns (list) --
The ARN for an Amazon Web Services Organization that you want to share your AMI with. For more information, see What is Organizations?.
(string) --
organizationalUnitArns (list) --
The ARN for an Organizations organizational unit (OU) that you want to share your AMI with. For more information about key concepts for Organizations, see Organizations terminology and concepts.
(string) --
containerDistributionConfiguration (dict) --
Container distribution settings for encryption, licensing, and sharing in a specific Region.
description (string) --
The description of the container distribution configuration.
containerTags (list) --
Tags that Image Builder applies to the distributed container image in the target repository. These are repository image tags, not resource tags.
(string) --
targetRepository (dict) --
The destination repository for the container distribution configuration.
service (string) --
Specifies the service in which this image was registered.
repositoryName (string) --
The name of the container repository where the output container image is stored. Provide the repository name only (a namespace path such as team-a/my-repo is allowed, but not the registry hostname).
licenseConfigurationArns (list) --
The License Manager Configuration to associate with the AMI in the specified Region.
(string) --
launchTemplateConfigurations (list) --
A group of launchTemplateConfiguration settings that apply to image distribution for specified accounts.
(dict) --
Identifies an Amazon EC2 launch template to use for a specific account.
launchTemplateId (string) --
Identifies the Amazon EC2 launch template to use.
accountId (string) --
The account ID that this configuration applies to.
setDefaultVersion (boolean) --
Specifies whether to make the new launch template version that Image Builder creates the default version of the launch template. If you don't set a value, Image Builder treats it as true.
s3ExportConfiguration (dict) --
Configure export settings to deliver disk images created from your image build, using a file format that is compatible with your VMs in that Region.
roleName (string) --
The name of the role that grants VM Import/Export permission to export images to your S3 bucket.
diskImageFormat (string) --
Export the updated image to one of the following supported disk image formats:
Virtual Hard Disk (VHD) – Compatible with Citrix Xen and Microsoft Hyper-V virtualization products.
Stream-optimized ESX Virtual Machine Disk (VMDK) – Compatible with VMware ESX and VMware vSphere versions 4, 5, and 6.
Raw – Raw format.
s3Bucket (string) --
The S3 bucket in which to store the output disk images for your VM.
s3Prefix (string) --
The Amazon S3 path for the bucket where the output disk images for your VM are stored.
fastLaunchConfigurations (list) --
The Windows faster-launching configurations to use for AMI distribution.
(dict) --
Defines and configures EC2 Fast Launch for output Windows AMIs.
enabled (boolean) --
Specifies whether to enable Windows fast launch on the output AMI during distribution. A value of false means Image Builder takes no fast-launch action for this configuration.
snapshotConfiguration (dict) --
Configuration settings for managing the number of snapshots that are created from pre-provisioned instances for the Windows AMI when Windows fast launch is enabled.
targetResourceCount (integer) --
The number of pre-provisioned snapshots to keep on hand for a fast-launch enabled Windows AMI.
maxParallelLaunches (integer) --
The maximum number of parallel instances that are launched for creating resources.
launchTemplate (dict) --
The launch template that the fast-launch enabled Windows AMI uses when it launches Windows instances to create pre-provisioned snapshots.
launchTemplateId (string) --
The ID of the launch template to use for Windows fast launch for a Windows AMI.
launchTemplateName (string) --
The name of the launch template to use for Windows fast launch for a Windows AMI.
launchTemplateVersion (string) --
The version of the launch template to use for Windows fast launch for a Windows AMI.
accountId (string) --
The owner account ID for the fast-launch enabled Windows AMI.
ssmParameterConfigurations (list) --
Contains settings to update Amazon Web Services Systems Manager (SSM) Parameter Store Parameters with output AMI IDs from the build by target Region.
(dict) --
Configuration for a single Parameter in the Amazon Web Services Systems Manager (SSM) Parameter Store in a given Region.
amiAccountId (string) --
Specify the account that will own the Parameter in a given Region. During distribution, this account must be specified in distribution settings as a target account for the Region.
parameterName (string) --
This is the name of the Parameter in the target Region or account. The image distribution creates the Parameter if it doesn't already exist. Otherwise, it updates the parameter.
dataType (string) --
The type of value the parameter contains. We recommend the aws:ec2:image data type.
timeoutMinutes (integer) --
A property that Image Builder doesn't use. You can't set this property when you create or update a distribution configuration, and it has no effect on distribution behavior.
dateCreated (string) --
The date on which this distribution configuration was created.
dateUpdated (string) --
The date on which this distribution configuration was last updated.
tags (dict) --
The tags of the distribution configuration.
(string) --
(string) --
imageTestsConfiguration (dict) --
The image test settings that Image Builder used when it created this image.
imageTestsEnabled (boolean) --
Specifies whether tests run after building the image. When enabled, tests run after the image build and before image distribution. Defaults to true.
timeoutMinutes (integer) --
The maximum time in minutes that tests are permitted to run. If you don't specify a value, Image Builder stores and returns 720.
dateCreated (string) --
The date on which Image Builder created this image.
outputResources (dict) --
The output resources that Image Builder produces for this image.
amis (list) --
The Amazon EC2 AMIs created by this image. The list contains one entry per AMI, including copies that distribution created in each target Amazon Web Services Region and account.
(dict) --
Details of an Amazon EC2 AMI.
region (string) --
The Amazon Web Services Region of the Amazon EC2 AMI.
image (string) --
The AMI ID of the Amazon EC2 AMI.
name (string) --
The name of the Amazon EC2 AMI.
description (string) --
The description of the Amazon EC2 AMI. Minimum and maximum length are in characters.
state (dict) --
The state of the AMI, which includes the status and, if applicable, the reason for that status.
status (string) --
The status of the image. A new image moves through build, test, and distribution statuses during creation, and ends in the AVAILABLE, FAILED, or CANCELLED state. The DEPRECATED, DISABLED, and DELETED statuses come from later resource management actions.
reason (string) --
The reason for the status of the image.
failureContext (dict) --
The details about the failure, for images that failed to complete. Image Builder only sets this property when the image status is FAILED.
imageStatus (string) --
The status that the image had when the failure occurred. This indicates the stage of the image creation process where the image failed, for example BUILDING or DISTRIBUTING.
workflowExecutionId (string) --
The unique identifier of the workflow execution that was running when the image failed.
workflowArn (string) --
The Amazon Resource Name (ARN) of the workflow build version that was running when the image failed.
stepExecutionId (string) --
The unique identifier of the workflow step execution that failed.
failedStep (string) --
The name of the workflow step that failed, as it appears in the workflow document.
componentFailure (dict) --
The details about the component that failed, if the failure occurred while a component was running.
componentArn (string) --
The Amazon Resource Name (ARN) of the component build version that failed.
phaseName (string) --
The name of the phase in the component document where the failure occurred, such as build, validate, or test.
stepName (string) --
The name of the step in the component document that failed.
action (string) --
The action that the failed step runs, for example ExecuteBash.
errorMessage (string) --
The error message from the step that failed. Image Builder truncates messages that are longer than 1024 characters. The component log in Amazon CloudWatch Logs contains the full output.
distributionFailure (dict) --
The details about the distribution failure, if the failure occurred while Image Builder distributed or configured the image.
errorMessage (string) --
The error message for the distribution failure.
regionFailures (list) --
The details about the failure for each Region where the image didn't finish distribution or configuration.
(dict) --
Contains details about a distribution or image configuration failure for a single Region.
region (string) --
The Region where the failure occurred.
status (string) --
The failure status for the Region. Indicates whether the process failed, was canceled, or timed out.
imageConfigurationStep (string) --
The image configuration step where the failure occurred. Image Builder sets this property when the failure happened during post-distribution configuration, such as launch template updates or virtual machine (VM) export. This property doesn't appear for failures that occurred while Image Builder copied the image to the Region.
errorMessage (string) --
The error message for the failure in the Region.
targetAccountId (string) --
The account ID of the account that the image was distributed to in the Region.
accountId (string) --
The account ID of the owner of the AMI.
containers (list) --
The container images that Image Builder created when it built this image, stored in the output Amazon ECR repository.
(dict) --
Details of the container images that are output resources of an image build in a given Amazon Web Services Region: the Region, and the URIs of the container images.
region (string) --
Containers and container images are Region-specific. This is the Region context for the container.
imageUris (list) --
A list of URIs for containers created in the context Region.
(string) --
tags (dict) --
The tags that apply to this image.
(string) --
(string) --
buildType (string) --
Indicates the type of build that created this image. The build can be initiated in the following ways:
USER_INITIATED – A manual pipeline build request.
SCHEDULED – A pipeline build initiated by a cron expression in the Image Builder pipeline, or from EventBridge.
IMPORT – A VM import created the image to use as the base image for the recipe.
IMPORT_ISO – An ISO disk import created the image.
imageSource (string) --
The origin of the base image that Image Builder used to build this image.
scanState (dict) --
Contains information about the current state of scans for this image.
status (string) --
The current state of vulnerability scans for the image. The scan starts as PENDING and moves through SCANNING and COLLECTING to COMPLETED. Image Builder sets the status to ABANDONED if the image reaches a terminal state before the scan finding collection completes. A scan can also end as FAILED or TIMED_OUT.
reason (string) --
The reason for the scan status for the image.
imageScanningConfiguration (dict) --
Settings for the vulnerability scans that Amazon Inspector runs for this image. For AMI output, Amazon Inspector scans the test instance during image creation. For container output, Amazon Inspector scans the container image in its Amazon ECR repository.
imageScanningEnabled (boolean) --
Specifies whether Amazon Inspector scans for vulnerabilities when you create a new image, and whether Image Builder saves the findings. Amazon Inspector must be enabled in the account. Image tests must also be enabled. For AMI output, Amazon Inspector scans the test instance. For container output, Amazon Inspector scans the container image that Image Builder pushes to the Amazon ECR repository from your ecrConfiguration settings.
ecrConfiguration (dict) --
Contains Amazon ECR settings for vulnerability scans.
repositoryName (string) --
The name of the container repository where Image Builder pushes the container image for the vulnerability scan. Provide the repository name only (a namespace path is allowed, but not the registry hostname); the repository must already exist in your account. If you don't specify a repository name, Image Builder creates the default repository image-builder-image-scanning-repository in your account.
containerTags (list) --
Tags for Image Builder to apply to the output container image that Amazon Inspector scans. Tags can help you identify and manage your scanned images.
(string) --
deprecationTime (datetime) --
The time when deprecation occurs for an image resource. This can be a past or future date.
lifecycleExecutionId (string) --
Identifies the last runtime instance of the lifecycle policy to take action on the image.
executionRole (string) --
The name or Amazon Resource Name (ARN) for the IAM role you create that grants Image Builder access to perform workflow actions.
workflows (list) --
The build, test, and distribution workflow configurations that are associated with the image.
(dict) --
Contains control settings and configurable inputs for a workflow resource.
workflowArn (string) --
The Amazon Resource Name (ARN) of the workflow resource.
parameters (list) --
Contains parameter values for each of the parameters that the workflow document defined for the workflow resource.
(dict) --
Contains a key/value pair that sets the named workflow parameter.
name (string) --
The name of the workflow parameter to set.
value (list) --
Sets the value for the named workflow parameter.
(string) --
parallelGroup (string) --
Test workflows are defined within named runtime groups called parallel groups. The parallel group is the named group that contains this test workflow. Test workflows within a parallel group can run at the same time. Image Builder starts up to five test workflows in the group at the same time, and starts additional workflows as others complete, until all workflows in the group have completed. This field only applies for test workflows.
onFailure (string) --
The action to take if the workflow fails. With CONTINUE, a failed workflow is logged and image creation proceeds to the next workflow. If you don't set a value, the image build fails when the workflow fails. You can only set this property for test workflows.
loggingConfiguration (dict) --
The logging configuration that's defined for the image. Image Builder uses the defined settings to direct execution log output during image creation.
logGroupName (string) --
The log group name that Image Builder uses for image creation. If not specified, the log group name defaults to /aws/imagebuilder/image-name.
latestVersionReferences (dict) --
A set of wildcard version ARNs that always reference the latest version of the resource. ARNs are included for the latest version overall, and for the latest versions within the same major, minor, and patch levels.
latestVersionArn (string) --
The latest version Amazon Resource Name (ARN) of the Image Builder resource.
latestMajorVersionArn (string) --
The latest version Amazon Resource Name (ARN) with the same major version of the Image Builder resource.
latestMinorVersionArn (string) --
The latest version Amazon Resource Name (ARN) with the same minor version of the Image Builder resource.
latestPatchVersionArn (string) --
The latest version Amazon Resource Name (ARN) with the same patch version of the Image Builder resource.
{'infrastructureConfiguration': {'parentInstance': {'autoScalingGroup': {'capacityWaitTimeoutSeconds': 'integer',
'name': 'string'}},
'terminateInstanceOnCompletion': 'boolean'}}
Retrieves an infrastructure configuration.
See also: AWS API Documentation
Request Syntax
client.get_infrastructure_configuration(
infrastructureConfigurationArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the infrastructure configuration that you want to retrieve.
dict
Response Syntax
{
'requestId': 'string',
'infrastructureConfiguration': {
'arn': 'string',
'name': 'string',
'description': 'string',
'instanceTypes': [
'string',
],
'instanceProfileName': 'string',
'securityGroupIds': [
'string',
],
'subnetId': 'string',
'logging': {
's3Logs': {
's3BucketName': 'string',
's3KeyPrefix': 'string'
}
},
'keyPair': 'string',
'terminateInstanceOnFailure': True|False,
'snsTopicArn': 'string',
'dateCreated': 'string',
'dateUpdated': 'string',
'resourceTags': {
'string': 'string'
},
'instanceMetadataOptions': {
'httpTokens': 'string',
'httpPutResponseHopLimit': 123
},
'tags': {
'string': 'string'
},
'placement': {
'availabilityZone': 'string',
'tenancy': 'default'|'dedicated'|'host',
'hostId': 'string',
'hostResourceGroupArn': 'string'
},
'terminateInstanceOnCompletion': True|False,
'parentInstance': {
'autoScalingGroup': {
'name': 'string',
'capacityWaitTimeoutSeconds': 123
}
}
}
}
Response Structure
(dict) --
GetInfrastructureConfiguration response object.
requestId (string) --
The request ID that uniquely identifies this request.
infrastructureConfiguration (dict) --
The infrastructure configuration object.
arn (string) --
The Amazon Resource Name (ARN) of the infrastructure configuration.
name (string) --
The name of the infrastructure configuration.
description (string) --
The description of the infrastructure configuration.
instanceTypes (list) --
The instance types of the infrastructure configuration.
(string) --
instanceProfileName (string) --
The instance profile of the infrastructure configuration.
securityGroupIds (list) --
The security group IDs of the infrastructure configuration.
(string) --
subnetId (string) --
The subnet ID of the infrastructure configuration.
logging (dict) --
The logging configuration of the infrastructure configuration. When you configure S3 logs, Image Builder writes logs from the build and test process to the specified bucket under the key prefix.
s3Logs (dict) --
The Amazon S3 logging configuration.
s3BucketName (string) --
The name of an existing Amazon S3 bucket where Image Builder saves build logs. The bucket isn't validated when you create or update the configuration, and Image Builder doesn't create it. The instance profile associated with this infrastructure configuration must have permission to write to the bucket.
s3KeyPrefix (string) --
The Amazon S3 key prefix under which Image Builder writes build and test logs in the bucket.
keyPair (string) --
The Amazon EC2 key pair of the infrastructure configuration.
terminateInstanceOnFailure (boolean) --
Indicates whether Image Builder terminates the build and test instances when the image build fails. When false, Image Builder retains the instance so that you can debug it.
snsTopicArn (string) --
The Amazon Resource Name (ARN) of the SNS topic to which Image Builder sends image build event notifications. Specify a standard topic. Image Builder doesn't support FIFO topics.
dateCreated (string) --
The date on which the infrastructure configuration was created.
dateUpdated (string) --
The date on which the infrastructure configuration was last updated.
resourceTags (dict) --
The metadata tags assigned to the Amazon EC2 build and test instances that Image Builder launches during image creation.
(string) --
(string) --
instanceMetadataOptions (dict) --
The instance metadata option settings for the infrastructure configuration.
httpTokens (string) --
Indicates whether a signed token header is required for instance metadata retrieval requests. The values affect the response as follows:
required – When you retrieve the IAM role credentials, version 2.0 credentials are returned in all cases.
optional – You can include a signed token header in your request to retrieve instance metadata, or you can leave it out. If you include it, version 2.0 credentials are returned for the IAM role. Otherwise, version 1.0 credentials are returned.
If you don't set a value, the EC2 launch default applies to the build and test instances. That default depends on the base AMI and any account-level instance metadata defaults. For more information, see Configure the instance metadata options in the Amazon EC2 User Guide .
httpPutResponseHopLimit (integer) --
Limit the number of hops that an instance metadata request can traverse to reach its destination. If you don't set a value, the EC2 launch default for the instance applies. If HTTP tokens are required, container image builds need a minimum of two hops.
tags (dict) --
The tags of the infrastructure configuration.
(string) --
(string) --
placement (dict) --
The instance placement settings that define where the build and test instances that Image Builder launches during image creation run. These settings don't affect instances that you launch from the output image.
availabilityZone (string) --
The Availability Zone where your build and test instances will launch.
tenancy (string) --
The tenancy of the instance. An instance with a tenancy of dedicated runs on single-tenant hardware. An instance with a tenancy of host runs on a Dedicated Host.
If tenancy is set to host, then you can optionally specify one target for placement – either host ID or host resource group ARN. If automatic placement is enabled for your host, and you don't specify any placement target, Amazon EC2 will try to find an available host for your build and test instances.
hostId (string) --
The ID of the Dedicated Host on which build and test instances run. This only applies if tenancy is host.
hostResourceGroupArn (string) --
The Amazon Resource Name (ARN) of the host resource group in which to launch build and test instances. This only applies if tenancy is host.
terminateInstanceOnCompletion (boolean) --
Specifies whether Image Builder terminates build and test instances when image creation ends without a failure.
parentInstance (dict) --
The Amazon EC2 Auto Scaling group that Image Builder takes the build instance from, instead of launching a new instance. This applies only to the build phase.
autoScalingGroup (dict) --
The Amazon EC2 Auto Scaling group that Image Builder takes the build instance from. This is required when you specify parentInstance.
name (string) --
The name of the Auto Scaling group, in the same account and Amazon Web Services Region as the infrastructure configuration. To specify a group, you must have permissions to describe it.
capacityWaitTimeoutSeconds (integer) --
The number of seconds that Image Builder waits for an instance to become available in the group before the build fails. If you set this value to 0 or omit it, the build fails as soon as the group has no instance available.
{'parentInstance': {'autoScalingGroup': {'capacityWaitTimeoutSeconds': 'integer',
'name': 'string'}},
'terminateInstanceOnCompletion': 'boolean'}
Updates an infrastructure configuration. An infrastructure configuration defines the environment in which Image Builder builds and tests your image.
See also: AWS API Documentation
Request Syntax
client.update_infrastructure_configuration(
infrastructureConfigurationArn='string',
description='string',
instanceTypes=[
'string',
],
instanceProfileName='string',
securityGroupIds=[
'string',
],
subnetId='string',
logging={
's3Logs': {
's3BucketName': 'string',
's3KeyPrefix': 'string'
}
},
keyPair='string',
terminateInstanceOnFailure=True|False,
terminateInstanceOnCompletion=True|False,
snsTopicArn='string',
resourceTags={
'string': 'string'
},
instanceMetadataOptions={
'httpTokens': 'string',
'httpPutResponseHopLimit': 123
},
placement={
'availabilityZone': 'string',
'tenancy': 'default'|'dedicated'|'host',
'hostId': 'string',
'hostResourceGroupArn': 'string'
},
parentInstance={
'autoScalingGroup': {
'name': 'string',
'capacityWaitTimeoutSeconds': 123
}
},
clientToken='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the infrastructure configuration that you want to update.
string
The description of the infrastructure configuration.
list
The instance types of the infrastructure configuration. You can specify one or more instance types to use for this build. Image Builder picks one of these instance types based on availability. If you don't specify instance types, Image Builder selects compatible instance types automatically. If you specify a Dedicated Host, Image Builder uses only instance types that the host supports.
(string) --
string
[REQUIRED]
The instance profile to associate with the instance used to customize your Amazon EC2 AMI. The instance profile must exist in your account.
list
The security group IDs to associate with the instance used to customize your Amazon EC2 AMI.
(string) --
string
The subnet ID in which to place the instance used to customize your Amazon EC2 AMI. If you specify subnetId, you must also specify one or more security group IDs in securityGroupIds. Otherwise, the request fails.
dict
The logging configuration of the infrastructure configuration. When you configure S3 logs, Image Builder writes logs from the build and test process to the specified bucket under the key prefix.
s3Logs (dict) --
The Amazon S3 logging configuration.
s3BucketName (string) --
The name of an existing Amazon S3 bucket where Image Builder saves build logs. The bucket isn't validated when you create or update the configuration, and Image Builder doesn't create it. The instance profile associated with this infrastructure configuration must have permission to write to the bucket.
s3KeyPrefix (string) --
The Amazon S3 key prefix under which Image Builder writes build and test logs in the bucket.
string
The key pair of the infrastructure configuration. You can use this to log on to and debug the instance used to create your image.
boolean
Specifies whether to terminate the instance on failure. Set to false if you want Image Builder to retain the instance used to configure your AMI if the build or test phase of your workflow fails. Defaults to true.
boolean
Specifies whether Image Builder terminates build and test instances when image creation ends without a failure (success, cancellation, or expiration). Defaults to true.
string
The Amazon Resource Name (ARN) of the SNS topic to which Image Builder sends image build event notifications. Specify a standard topic. Image Builder doesn't support FIFO topics. Image Builder validates the topic when you create or update the configuration. You must have permission to publish to the topic.
dict
The metadata tags to assign to the Amazon EC2 instance that Image Builder launches during the build process. Tags are formatted as key value pairs. Tag keys can't begin with aws: or match one of the following reserved keys: CreatedBy, Ec2ImageBuilderArn, Name, or Tags.
(string) --
(string) --
dict
The instance metadata service (IMDS) settings that Image Builder applies to the EC2 build and test instances it launches during image creation. If you don't set these options, the EC2 launch defaults for the instance apply. For more information about instance metadata options, see one of the following links:
Configure the instance metadata options in the Amazon EC2 User Guide for Linux instances.
Configure the instance metadata options in the Amazon EC2 Windows Guide for Windows instances.
httpTokens (string) --
Indicates whether a signed token header is required for instance metadata retrieval requests. The values affect the response as follows:
required – When you retrieve the IAM role credentials, version 2.0 credentials are returned in all cases.
optional – You can include a signed token header in your request to retrieve instance metadata, or you can leave it out. If you include it, version 2.0 credentials are returned for the IAM role. Otherwise, version 1.0 credentials are returned.
If you don't set a value, the EC2 launch default applies to the build and test instances. That default depends on the base AMI and any account-level instance metadata defaults. For more information, see Configure the instance metadata options in the Amazon EC2 User Guide .
httpPutResponseHopLimit (integer) --
Limit the number of hops that an instance metadata request can traverse to reach its destination. If you don't set a value, the EC2 launch default for the instance applies. If HTTP tokens are required, container image builds need a minimum of two hops.
dict
The instance placement settings that define where the build and test instances that Image Builder launches during image creation run. These settings don't affect instances that you launch from the output image.
availabilityZone (string) --
The Availability Zone where your build and test instances will launch.
tenancy (string) --
The tenancy of the instance. An instance with a tenancy of dedicated runs on single-tenant hardware. An instance with a tenancy of host runs on a Dedicated Host.
If tenancy is set to host, then you can optionally specify one target for placement – either host ID or host resource group ARN. If automatic placement is enabled for your host, and you don't specify any placement target, Amazon EC2 will try to find an available host for your build and test instances.
hostId (string) --
The ID of the Dedicated Host on which build and test instances run. This only applies if tenancy is host.
hostResourceGroupArn (string) --
The Amazon Resource Name (ARN) of the host resource group in which to launch build and test instances. This only applies if tenancy is host.
dict
The Amazon EC2 Auto Scaling group that Image Builder takes the build instance from, instead of launching a new instance. This applies only to the build phase.
To use this feature, the execution role for the build must have permissions to describe the Auto Scaling group, tag the instance while it's still in the group, and detach it from the group. For more information, see Build on an instance from an Auto Scaling group in the EC2 Image Builder User Guide.
autoScalingGroup (dict) -- [REQUIRED]
The Amazon EC2 Auto Scaling group that Image Builder takes the build instance from. This is required when you specify parentInstance.
name (string) -- [REQUIRED]
The name of the Auto Scaling group, in the same account and Amazon Web Services Region as the infrastructure configuration. To specify a group, you must have permissions to describe it.
capacityWaitTimeoutSeconds (integer) --
The number of seconds that Image Builder waits for an instance to become available in the group before the build fails. If you set this value to 0 or omit it, the build fails as soon as the group has no instance available.
string
[REQUIRED]
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.
This field is autopopulated if not provided.
dict
Response Syntax
{
'requestId': 'string',
'clientToken': 'string',
'infrastructureConfigurationArn': 'string'
}
Response Structure
(dict) --
requestId (string) --
The request ID that uniquely identifies this request.
clientToken (string) --
The client token that uniquely identifies the request.
infrastructureConfigurationArn (string) --
The Amazon Resource Name (ARN) of the infrastructure configuration that was updated by this request.