get-image¶

Description¶

Retrieves an image.

Synopsis¶

  get-image
--image-build-version-arn <value>
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]
[--cli-error-format <value>]

Options¶

--image-build-version-arn (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.

Constraints:

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

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command. The generated JSON skeleton is not stable between versions of the AWS CLI and there are no backwards compatibility guarantees in the JSON skeleton generated.

Global Options¶

--debug (boolean)

Turn on debug logging.

--endpoint-url (string)

Override command’s default URL with the given URL.

--no-verify-ssl (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

--no-paginate (boolean)

Disable automatic pagination. If automatic pagination is disabled, the AWS CLI will only make one call, for the first page of results.

--output (string)

The formatting style for command output.

json
text
table
yaml
yaml-stream
off

--query (string)

A JMESPath query to use in filtering the response data.

--profile (string)

Use a specific profile from your credential file.

--region (string)

The region to use. Overrides config/env settings.

--version (string)

Display the version of this tool.

--color (string)

Turn on/off color output.

on
off
auto

--no-sign-request (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

--ca-bundle (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

--cli-read-timeout (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

--cli-connect-timeout (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

--cli-binary-format (string)

The formatting style to be used for binary blobs. The default format is base64. The base64 format expects binary blobs to be provided as a base64 encoded string. The raw-in-base64-out format preserves compatibility with AWS CLI V1 behavior and binary values must be passed literally. When providing contents from a file that map to a binary blob fileb:// will always be treated as binary and use the file contents directly regardless of the cli-binary-format setting. When using file:// the file contents will need to properly formatted for the configured cli-binary-format.

base64
raw-in-base64-out

--no-cli-pager (boolean)

Disable cli pager for output.

--cli-auto-prompt (boolean)

Automatically prompt for CLI input parameters.

--no-cli-auto-prompt (boolean)

Disable automatically prompt for CLI input parameters.

--cli-error-format (string)

The formatting style for error output. By default, errors are displayed in enhanced format.

legacy
json
yaml
text
table
enhanced

Examples¶

Note

To use the following examples, you must have the AWS CLI installed and configured. See the Getting started guide in the AWS CLI User Guide for more information.

Unless otherwise stated, all examples have unix-like quotation rules. These examples will need to be adapted to your terminal’s quoting rules. See Using quotation marks with strings in the AWS CLI User Guide .

To get image details

The following get-image example lists the details of an image by specifying its ARN.

aws imagebuilder get-image \
    --image-build-version-arn arn:aws:imagebuilder:us-west-2:123456789012:image/mybasicrecipe/2019.12.03/1

Output:

{
    "requestId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "image": {
        "arn": "arn:aws:imagebuilder:us-west-2:123456789012:image/mybasicrecipe/2019.12.03/1",
        "name": "MyBasicRecipe",
        "version": "2019.12.03/1",
        "platform": "Windows",
        "state": {
            "status": "BUILDING"
        },
        "imageRecipe": {
            "arn": "arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/mybasicrecipe/2019.12.03",
            "name": "MyBasicRecipe",
            "description": "This example image recipe creates a Windows 2016 image.",
            "platform": "Windows",
            "version": "2019.12.03",
            "components": [
                {
                    "componentArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/myexamplecomponent/2019.12.02/1"
                },
                {
                    "componentArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/myimportedcomponent/1.0.0/1"
                }
            ],
            "parentImage": "arn:aws:imagebuilder:us-west-2:aws:image/windows-server-2016-english-full-base-x86/2019.12.17/1",
            "dateCreated": "2020-02-14T19:46:16.904Z",
            "tags": {}
        },
        "infrastructureConfiguration": {
            "arn": "arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/myexampleinfrastructure",
            "name": "MyExampleInfrastructure",
            "description": "An example that will retain instances of failed builds",
            "instanceTypes": [
                "m5.large",
                "m5.xlarge"
            ],
            "instanceProfileName": "EC2InstanceProfileForImageFactory",
            "securityGroupIds": [
                "sg-a1b2c3d4"
            ],
            "subnetId": "subnet-a1b2c3d4",
            "logging": {
                "s3Logs": {
                    "s3BucketName": "bucket-name",
                    "s3KeyPrefix": "bucket-path"
                }
            },
            "keyPair": "Sam",
            "terminateInstanceOnFailure": false,
            "snsTopicArn": "arn:aws:sns:us-west-2:123456789012:sns-name",
            "dateCreated": "2020-02-14T21:21:05.098Z",
            "tags": {}
        },
        "imageTestsConfiguration": {
            "imageTestsEnabled": true,
            "timeoutMinutes": 720
        },
        "dateCreated": "2020-02-14T23:14:13.597Z",
        "outputResources": {
            "amis": []
        },
        "tags": {}
    }
}

For more information, see Setting Up and Managing an EC2 Image Builder Image Pipeline Using the AWS CLI in the EC2 Image Builder Users Guide.

Output¶

requestId -> (string)

The request ID that uniquely identifies this request.

Constraints:

min: 1

max: 1024

image -> (structure)

The image object.

arn -> (string)

The Amazon Resource Name (ARN) of the image.

Note
Semantic versioning is included in each object’s Amazon Resource Name (ARN), at the level that applies to that object as follows:

Versionless ARNs and Name ARNs do not include specific values in any of the nodes. The nodes are either left off entirely, or they are specified as wildcards, for example: x.x.x.

Version ARNs have only the first three nodes: <major>.<minor>.<patch>

Build version ARNs have all four nodes, and point to a specific build for a specific version of an object.

Constraints:

pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?|third-party):(?:image-recipe|container-recipe|infrastructure-configuration|distribution-configuration|component|image|image-pipeline|lifecycle-policy|workflow\/(?:build|test|distribution))/[a-z0-9-_]+(?:/(?:(?:x|[0-9]+)\.(?:x|[0-9]+)\.(?:x|[0-9]+))(?:/[0-9]+)?)?$

type -> (string)

Specifies whether this image produces an AMI or a container image.

Possible values:

AMI

DOCKER

name -> (string)

The name of the image.

Constraints:

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

version -> (string)

The semantic version of the image.

Note
The semantic version has four nodes: <major>.<minor>.<patch>/<build>. You can assign values for the first three, and can filter on all of them.

Assignment: For the first three nodes, you can assign any positive integer value, including zero. The upper limit is 2^30-1, or 1073741823, for each node. Image Builder automatically assigns the build number to the fourth node.

Patterns: You can use any numeric pattern that adheres to the assignment requirements for the nodes that you can assign. For example, you might choose a software version pattern, such as 1.0.0, or a date, such as 2021.01.01.

Filtering: You can use wildcards (x) to specify the most recent versions or nodes when selecting the base image or components for your recipe. When you use a wildcard in any node, all nodes to the right of the first wildcard must also be wildcards.

Constraints:

min: 5

max: 64

pattern: ^[0-9]+\.[0-9]+\.[0-9]+(?:/[0-9]+)?$

platform -> (string)

The image operating system platform, such as Linux or Windows.

Possible values:

Windows

Linux

macOS

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.

Constraints:

min: 1

state -> (structure)

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.

Possible values:

PENDING

CREATING

BUILDING

TESTING

DISTRIBUTING

INTEGRATING

AVAILABLE

CANCELLED

FAILED

DEPRECATED

DELETED

DISABLED

reason -> (string)

The reason for the status of the image.

Constraints:

min: 1

max: 1024

failureContext -> (structure)

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 .

Possible values:

PENDING

CREATING

BUILDING

TESTING

DISTRIBUTING

INTEGRATING

AVAILABLE

CANCELLED

FAILED

DEPRECATED

DELETED

DISABLED

workflowExecutionId -> (string)

The unique identifier of the workflow execution that was running when the image failed.

Constraints:

pattern: ^wf-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

workflowArn -> (string)

The Amazon Resource Name (ARN) of the workflow build version that was running when the image failed.

Constraints:

max: 1024

pattern: ^arn:aws(?:-[a-z]+)*:imagebuilder:[a-z]{2,}(?:-[a-z]+)+-[0-9]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?):workflow/(build|test|distribution)/[a-z0-9-_]+/[0-9]+\.[0-9]+\.[0-9]+/[0-9]+$

stepExecutionId -> (string)

The unique identifier of the workflow step execution that failed.

Constraints:

pattern: ^step-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

failedStep -> (string)

The name of the workflow step that failed, as it appears in the workflow document.

Constraints:

pattern: ^[A-Za-z][A-Za-z0-9-_]{1,99}$

componentFailure -> (structure)

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.

Constraints:

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

phaseName -> (string)

The name of the phase in the component document where the failure occurred, such as build , validate , or test .

Constraints:

min: 1

max: 1024

stepName -> (string)

The name of the step in the component document that failed.

Constraints:

min: 1

max: 1024

action -> (string)

The action that the failed step runs, for example ExecuteBash .

Constraints:

min: 1

max: 1024

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.

Constraints:

min: 1

max: 384000

distributionFailure -> (structure)

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.

Constraints:

min: 1

max: 384000

regionFailures -> (list)

The details about the failure for each Region where the image didn’t finish distribution or configuration.

Constraints:

min: 1

max: 256

(structure)

Contains details about a distribution or image configuration failure for a single Region.

region -> (string)

The Region where the failure occurred.

Constraints:

min: 1

max: 1024

status -> (string)

The failure status for the Region. Indicates whether the process failed, was canceled, or timed out.

Possible values:

FAILED

CANCELLED

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.

Possible values:

ASSOCIATE_LICENSES

UPDATE_LAUNCH_TEMPLATES

PUT_SSM_PARAMETERS

UPDATE_FAST_LAUNCH_CONFIGURATIONS

EXPORT_AMI

errorMessage -> (string)

The error message for the failure in the Region.

Constraints:

min: 1

max: 384000

targetAccountId -> (string)

The account ID of the account that the image was distributed to in the Region.

Constraints:

pattern: ^[0-9]{12}$

imageRecipe -> (structure)

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.

Constraints:

pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?|third-party):(?:image-recipe|container-recipe|infrastructure-configuration|distribution-configuration|component|image|image-pipeline|lifecycle-policy|workflow\/(?:build|test|distribution))/[a-z0-9-_]+(?:/(?:(?:x|[0-9]+)\.(?:x|[0-9]+)\.(?:x|[0-9]+))(?:/[0-9]+)?)?$

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.

Possible values:

AMI

DOCKER

name -> (string)

The name of the image recipe.

Constraints:

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

description -> (string)

The description of the image recipe.

Constraints:

min: 1

max: 1024

platform -> (string)

The platform of the image recipe.

Possible values:

Windows

Linux

macOS

owner -> (string)

The owner of the image recipe.

Constraints:

min: 1

max: 1024

version -> (string)

The version of the image recipe.

Constraints:

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

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 .

Constraints:

min: 1

(structure)

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) [required]

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 .

Constraints:

pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?|third-party):component/[a-z0-9-_]+/(?:(?:([0-9]+|x)\.([0-9]+|x)\.([0-9]+|x))|(?:[0-9]+\.[0-9]+\.[0-9]+/[0-9]+))$

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.

Constraints:

min: 1

(structure)

Contains a key/value pair that sets the named component parameter.

name -> (string) [required]

The name of the component parameter to set.

Constraints:

min: 1

max: 256

pattern: [^\x00]+

value -> (list) [required]

Sets the value for the named component parameter.

(string)

Constraints:

min: 0

pattern: [^\x00]*

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

Constraints:

min: 1

max: 1024

blockDeviceMappings -> (list)

The block device mappings to apply when creating images from this recipe.

(structure)

Defines block device mappings for the instance used to configure your image.

deviceName -> (string)

The device to which these mappings apply.

Constraints:

min: 1

max: 1024

ebs -> (structure)

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.

Constraints:

min: 100

max: 64000

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 .

Constraints:

min: 1

max: 1024

snapshotId -> (string)

The snapshot that defines the device contents.

Constraints:

min: 1

max: 1024

volumeSize -> (integer)

Overrides the volume size for the device.

Constraints:

min: 1

max: 16000

volumeType -> (string)

Overrides the volume type for the device.

Possible values:

standard

io1

io2

gp2

gp3

sc1

st1

throughput -> (integer)

For GP3 volumes only – The throughput in MiB/s that the volume supports.

Constraints:

min: 125

max: 1000

virtualName -> (string)

The virtual device name for instance ephemeral devices.

Constraints:

min: 1

max: 1024

noDevice -> (string)

Specifies a mapping to remove from the base image.

Constraints:

min: 0

max: 0

dateCreated -> (string)

The date on which this image recipe was created.

tags -> (map)

The tags of the image recipe.

Constraints:

min: 1

max: 50

key -> (string)

Constraints:

min: 1

max: 128

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

value -> (string)

Constraints:

max: 256

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.

Constraints:

min: 1

max: 1024

additionalInstanceConfiguration -> (structure)

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 -> (structure)

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.

Note
The user data is always base 64 encoded. For example, the following commands are encoded as IyEvYmluL2Jhc2gKbWtkaXIgLXAgL3Zhci9iYi8KdG91Y2ggL3Zhcg== :

#!/bin/bash

mkdir -p /var/bb/

touch /var

Constraints:

min: 1

max: 21847

pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$

amiTags -> (map)

Tags that are applied to the AMI that Image Builder creates during the Build phase prior to image distribution.

Constraints:

min: 1

max: 50

key -> (string)

Constraints:

min: 1

max: 128

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

value -> (string)

Constraints:

max: 256

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.

Constraints:

min: 1

max: 5

(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.

Constraints:

min: 3

max: 128

pattern: ^[A-Za-z0-9()\[\]./'@_\-][A-Za-z0-9 ()\[\]./'@_\-]{1,126}[A-Za-z0-9()\[\]./'@_\-]$

containerRecipe -> (structure)

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.

Note
Semantic versioning is included in each object’s Amazon Resource Name (ARN), at the level that applies to that object as follows:

Versionless ARNs and Name ARNs do not include specific values in any of the nodes. The nodes are either left off entirely, or they are specified as wildcards, for example: x.x.x.

Version ARNs have only the first three nodes: <major>.<minor>.<patch>

Build version ARNs have all four nodes, and point to a specific build for a specific version of an object.

Constraints:

pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?|third-party):(?:image-recipe|container-recipe|infrastructure-configuration|distribution-configuration|component|image|image-pipeline|lifecycle-policy|workflow\/(?:build|test|distribution))/[a-z0-9-_]+(?:/(?:(?:x|[0-9]+)\.(?:x|[0-9]+)\.(?:x|[0-9]+))(?:/[0-9]+)?)?$

containerType -> (string)

Specifies the type of container, such as Docker.

Possible values:

DOCKER

name -> (string)

The name of the container recipe.

Constraints:

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

description -> (string)

The description of the container recipe.

Constraints:

min: 1

max: 1024

platform -> (string)

The system platform for the container. Container recipes support only the Linux and Windows platforms.

Possible values:

Windows

Linux

macOS

owner -> (string)

The owner of the container recipe.

Constraints:

min: 1

max: 1024

version -> (string)

The semantic version of the container recipe.

Note
The semantic version has four nodes: <major>.<minor>.<patch>/<build>. You can assign values for the first three, and can filter on all of them.

Assignment: For the first three nodes, you can assign any positive integer value, including zero. The upper limit is 2^30-1, or 1073741823, for each node. Image Builder automatically assigns the build number to the fourth node.

Patterns: You can use any numeric pattern that adheres to the assignment requirements for the nodes that you can assign. For example, you might choose a software version pattern, such as 1.0.0, or a date, such as 2021.01.01.

Filtering: You can use wildcards (x) to specify the most recent versions or nodes when selecting the base image or components for your recipe. When you use a wildcard in any node, all nodes to the right of the first wildcard must also be wildcards.

Constraints:

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

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 .

Constraints:

min: 1

(structure)

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) [required]

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 .

Constraints:

pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?|third-party):component/[a-z0-9-_]+/(?:(?:([0-9]+|x)\.([0-9]+|x)\.([0-9]+|x))|(?:[0-9]+\.[0-9]+\.[0-9]+/[0-9]+))$

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.

Constraints:

min: 1

(structure)

Contains a key/value pair that sets the named component parameter.

name -> (string) [required]

The name of the component parameter to set.

Constraints:

min: 1

max: 256

pattern: [^\x00]+

value -> (list) [required]

Sets the value for the named component parameter.

(string)

Constraints:

min: 0

pattern: [^\x00]*

instanceConfiguration -> (structure)

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.

Constraints:

min: 1

max: 1024

blockDeviceMappings -> (list)

Defines the block device mappings for the EC2 instance that Image Builder launches to build and test your container image.

(structure)

Defines block device mappings for the instance used to configure your image.

deviceName -> (string)

The device to which these mappings apply.

Constraints:

min: 1

max: 1024

ebs -> (structure)

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.

Constraints:

min: 100

max: 64000

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 .

Constraints:

min: 1

max: 1024

snapshotId -> (string)

The snapshot that defines the device contents.

Constraints:

min: 1

max: 1024

volumeSize -> (integer)

Overrides the volume size for the device.

Constraints:

min: 1

max: 16000

volumeType -> (string)

Overrides the volume type for the device.

Possible values:

standard

io1

io2

gp2

gp3

sc1

st1

throughput -> (integer)

For GP3 volumes only – The throughput in MiB/s that the volume supports.

Constraints:

min: 125

max: 1000

virtualName -> (string)

The virtual device name for instance ephemeral devices.

Constraints:

min: 1

max: 1024

noDevice -> (string)

Specifies a mapping to remove from the base image.

Constraints:

min: 0

max: 0

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.

Constraints:

min: 1

max: 1024

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 .

Constraints:

min: 1

max: 1024

dateCreated -> (string)

The date when this container recipe was created.

tags -> (map)

Tags that are attached to the container recipe.

Constraints:

min: 1

max: 50

key -> (string)

Constraints:

min: 1

max: 128

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

value -> (string)

Constraints:

max: 256

workingDirectory -> (string)

The working directory for use during build and test workflows.

Constraints:

min: 1

max: 1024

targetRepository -> (structure)

The destination repository for the container image.

service -> (string) [required]

Specifies the service in which this image was registered.

Possible values:

ECR

repositoryName -> (string) [required]

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).

Constraints:

min: 1

max: 1024

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.

Constraints:

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

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 -> (structure)

The infrastructure that Image Builder used to create this image.

arn -> (string)

The Amazon Resource Name (ARN) of the infrastructure configuration.

Constraints:

pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?|third-party):(?:image-recipe|container-recipe|infrastructure-configuration|distribution-configuration|component|image|image-pipeline|lifecycle-policy|workflow\/(?:build|test|distribution))/[a-z0-9-_]+(?:/(?:(?:x|[0-9]+)\.(?:x|[0-9]+)\.(?:x|[0-9]+))(?:/[0-9]+)?)?$

name -> (string)

The name of the infrastructure configuration.

Constraints:

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

description -> (string)

The description of the infrastructure configuration.

Constraints:

min: 1

max: 1024

instanceTypes -> (list)

The instance types of the infrastructure configuration.

(string)

instanceProfileName -> (string)

The instance profile of the infrastructure configuration.

Constraints:

min: 1

max: 256

pattern: ^[\w+=,.@-]+$

securityGroupIds -> (list)

The security group IDs of the infrastructure configuration.

(string)

Constraints:

min: 1

max: 1024

subnetId -> (string)

The subnet ID of the infrastructure configuration.

Constraints:

min: 1

max: 1024

logging -> (structure)

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 -> (structure)

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.

Constraints:

min: 1

max: 1024

s3KeyPrefix -> (string)

The Amazon S3 key prefix under which Image Builder writes build and test logs in the bucket.

Constraints:

min: 1

max: 1024

keyPair -> (string)

The Amazon EC2 key pair of the infrastructure configuration.

Constraints:

min: 1

max: 1024

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.

Note
EC2 Image Builder can’t send notifications to SNS topics that are encrypted using keys from other accounts. If your SNS topic is encrypted, the key must be owned by the same account that owns your Image Builder resources.

Constraints:

min: 1

max: 1024

dateCreated -> (string)

The date on which the infrastructure configuration was created.

dateUpdated -> (string)

The date on which the infrastructure configuration was last updated.

resourceTags -> (map)

The metadata tags assigned to the Amazon EC2 build and test instances that Image Builder launches during image creation.

Constraints:

min: 1

max: 30

key -> (string)

Constraints:

min: 1

max: 128

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

value -> (string)

Constraints:

max: 256

instanceMetadataOptions -> (structure)

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 * .

Constraints:

pattern: optional|required

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.

Constraints:

min: 1

max: 64

tags -> (map)

The tags of the infrastructure configuration.

Constraints:

min: 1

max: 50

key -> (string)

Constraints:

min: 1

max: 128

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

value -> (string)

Constraints:

max: 256

placement -> (structure)

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.

Constraints:

min: 1

max: 1024

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.

Possible values:

default

dedicated

host

hostId -> (string)

The ID of the Dedicated Host on which build and test instances run. This only applies if tenancy is host .

Constraints:

min: 1

max: 1024

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 .

Constraints:

min: 1

max: 1024

distributionConfiguration -> (structure)

The distribution configuration that Image Builder used to create this image.

arn -> (string)

The Amazon Resource Name (ARN) of the distribution configuration.

Constraints:

pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?|third-party):(?:image-recipe|container-recipe|infrastructure-configuration|distribution-configuration|component|image|image-pipeline|lifecycle-policy|workflow\/(?:build|test|distribution))/[a-z0-9-_]+(?:/(?:(?:x|[0-9]+)\.(?:x|[0-9]+)\.(?:x|[0-9]+))(?:/[0-9]+)?)?$

name -> (string)

The name of the distribution configuration.

Constraints:

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

description -> (string)

The description of the distribution configuration.

Constraints:

min: 1

max: 1024

distributions -> (list)

The distribution objects that apply Region-specific settings for the deployment of the image to targeted Regions.

(structure)

Defines the settings for a specific Region.

region -> (string) [required]

The target Region.

Constraints:

min: 1

max: 1024

amiDistributionConfiguration -> (structure)

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 .

Constraints:

min: 1

max: 127

pattern: ^[-_A-Za-z0-9{][-_A-Za-z0-9\s:{}\.]+[-_A-Za-z0-9}]$

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.

Constraints:

min: 1

max: 1024

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.

Constraints:

min: 1

max: 1536

(string)

Constraints:

pattern: ^[0-9]{12}$

amiTags -> (map)

The tags to apply to AMIs distributed to this Region.

Constraints:

min: 1

max: 50

key -> (string)

Constraints:

min: 1

max: 128

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

value -> (string)

Constraints:

max: 256

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 .

Constraints:

min: 1

max: 1024

launchPermission -> (structure)

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.

Constraints:

min: 1

max: 1536

(string)

Constraints:

pattern: ^[0-9]{12}$

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)

Constraints:

min: 1

max: 1024

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? .

Constraints:

min: 1

max: 25

(string)

Constraints:

pattern: ^arn:aws[^:]*:organizations::[0-9]{12}:organization/o-[a-z0-9]{10,32}$

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 .

Constraints:

min: 1

max: 25

(string)

Constraints:

pattern: ^arn:aws[^:]*:organizations::[0-9]{12}:ou/o-[a-z0-9]{10,32}/ou-[0-9a-z]{4,32}-[0-9a-z]{8,32}

containerDistributionConfiguration -> (structure)

Container distribution settings for encryption, licensing, and sharing in a specific Region.

description -> (string)

The description of the container distribution configuration.

Constraints:

min: 1

max: 1024

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)

Constraints:

min: 1

max: 1024

targetRepository -> (structure) [required]

The destination repository for the container distribution configuration.

service -> (string) [required]

Specifies the service in which this image was registered.

Possible values:

ECR

repositoryName -> (string) [required]

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).

Constraints:

min: 1

max: 1024

licenseConfigurationArns -> (list)

The License Manager Configuration to associate with the AMI in the specified Region.

Constraints:

min: 1

max: 50

(string)

Constraints:

pattern: ^arn:aws[^:]*:license-manager:[^:]+:[0-9]{12}:license-configuration:lic-[a-z0-9-_]{32}$

launchTemplateConfigurations -> (list)

A group of launchTemplateConfiguration settings that apply to image distribution for specified accounts.

Constraints:

min: 1

max: 100

(structure)

Identifies an Amazon EC2 launch template to use for a specific account.

launchTemplateId -> (string) [required]

Identifies the Amazon EC2 launch template to use.

Constraints:

pattern: ^lt-[a-z0-9-_]{17}$

accountId -> (string)

The account ID that this configuration applies to.

Constraints:

pattern: ^[0-9]{12}$

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 -> (structure)

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) [required]

The name of the role that grants VM Import/Export permission to export images to your S3 bucket.

Constraints:

min: 1

max: 1024

diskImageFormat -> (string) [required]

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.

Possible values:

VMDK

RAW

VHD

s3Bucket -> (string) [required]

The S3 bucket in which to store the output disk images for your VM.

Constraints:

min: 1

max: 1024

s3Prefix -> (string)

The Amazon S3 path for the bucket where the output disk images for your VM are stored.

Constraints:

min: 1

max: 1024

fastLaunchConfigurations -> (list)

The Windows faster-launching configurations to use for AMI distribution.

Constraints:

min: 1

max: 1000

(structure)

Defines and configures EC2 Fast Launch for output Windows AMIs.

enabled -> (boolean) [required]

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 -> (structure)

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.

Constraints:

min: 1

max: 10000

maxParallelLaunches -> (integer)

The maximum number of parallel instances that are launched for creating resources.

Constraints:

min: 1

launchTemplate -> (structure)

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.

Constraints:

pattern: ^lt-[a-z0-9-_]{17}$

launchTemplateName -> (string)

The name of the launch template to use for Windows fast launch for a Windows AMI.

Constraints:

min: 1

max: 1024

launchTemplateVersion -> (string)

The version of the launch template to use for Windows fast launch for a Windows AMI.

Constraints:

min: 1

max: 1024

accountId -> (string)

The owner account ID for the fast-launch enabled Windows AMI.

Constraints:

pattern: ^[0-9]{12}$

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.

(structure)

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.

Constraints:

pattern: ^[0-9]{12}$

parameterName -> (string) [required]

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.

Constraints:

min: 1

max: 1011

pattern: ^[a-zA-Z0-9_.\-\/]+$

dataType -> (string)

The type of value the parameter contains. We recommend the aws:ec2:image data type.

Possible values:

text

aws:ec2:image

timeoutMinutes -> (integer) [required]

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.

Constraints:

min: 30

max: 720

dateCreated -> (string)

The date on which this distribution configuration was created.

dateUpdated -> (string)

The date on which this distribution configuration was last updated.

tags -> (map)

The tags of the distribution configuration.

Constraints:

min: 1

max: 50

key -> (string)

Constraints:

min: 1

max: 128

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

value -> (string)

Constraints:

max: 256

imageTestsConfiguration -> (structure)

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.

Note
The timeout property is not currently active. This value is ignored.

Constraints:

min: 60

max: 1440

dateCreated -> (string)

The date on which Image Builder created this image.

outputResources -> (structure)

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.

(structure)

Details of an Amazon EC2 AMI.

region -> (string)

The Amazon Web Services Region of the Amazon EC2 AMI.

Constraints:

min: 1

max: 1024

image -> (string)

The AMI ID of the Amazon EC2 AMI.

Constraints:

min: 1

max: 1024

name -> (string)

The name of the Amazon EC2 AMI.

Constraints:

min: 1

max: 1024

description -> (string)

The description of the Amazon EC2 AMI. Minimum and maximum length are in characters.

Constraints:

min: 1

max: 1024

state -> (structure)

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.

Possible values:

PENDING

CREATING

BUILDING

TESTING

DISTRIBUTING

INTEGRATING

AVAILABLE

CANCELLED

FAILED

DEPRECATED

DELETED

DISABLED

reason -> (string)

The reason for the status of the image.

Constraints:

min: 1

max: 1024

failureContext -> (structure)

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 .

Possible values:

PENDING

CREATING

BUILDING

TESTING

DISTRIBUTING

INTEGRATING

AVAILABLE

CANCELLED

FAILED

DEPRECATED

DELETED

DISABLED

workflowExecutionId -> (string)

The unique identifier of the workflow execution that was running when the image failed.

Constraints:

pattern: ^wf-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

workflowArn -> (string)

The Amazon Resource Name (ARN) of the workflow build version that was running when the image failed.

Constraints:

max: 1024

pattern: ^arn:aws(?:-[a-z]+)*:imagebuilder:[a-z]{2,}(?:-[a-z]+)+-[0-9]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?):workflow/(build|test|distribution)/[a-z0-9-_]+/[0-9]+\.[0-9]+\.[0-9]+/[0-9]+$

stepExecutionId -> (string)

The unique identifier of the workflow step execution that failed.

Constraints:

pattern: ^step-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

failedStep -> (string)

The name of the workflow step that failed, as it appears in the workflow document.

Constraints:

pattern: ^[A-Za-z][A-Za-z0-9-_]{1,99}$

componentFailure -> (structure)

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.

Constraints:

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

phaseName -> (string)

The name of the phase in the component document where the failure occurred, such as build , validate , or test .

Constraints:

min: 1

max: 1024

stepName -> (string)

The name of the step in the component document that failed.

Constraints:

min: 1

max: 1024

action -> (string)

The action that the failed step runs, for example ExecuteBash .

Constraints:

min: 1

max: 1024

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.

Constraints:

min: 1

max: 384000

distributionFailure -> (structure)

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.

Constraints:

min: 1

max: 384000

regionFailures -> (list)

The details about the failure for each Region where the image didn’t finish distribution or configuration.

Constraints:

min: 1

max: 256

(structure)

Contains details about a distribution or image configuration failure for a single Region.

region -> (string)

The Region where the failure occurred.

Constraints:

min: 1

max: 1024

status -> (string)

The failure status for the Region. Indicates whether the process failed, was canceled, or timed out.

Possible values:

FAILED

CANCELLED

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.

Possible values:

ASSOCIATE_LICENSES

UPDATE_LAUNCH_TEMPLATES

PUT_SSM_PARAMETERS

UPDATE_FAST_LAUNCH_CONFIGURATIONS

EXPORT_AMI

errorMessage -> (string)

The error message for the failure in the Region.

Constraints:

min: 1

max: 384000

targetAccountId -> (string)

The account ID of the account that the image was distributed to in the Region.

Constraints:

pattern: ^[0-9]{12}$

accountId -> (string)

The account ID of the owner of the AMI.

Constraints:

min: 1

max: 1024

containers -> (list)

The container images that Image Builder created when it built this image, stored in the output Amazon ECR repository.

(structure)

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.

Constraints:

min: 1

max: 1024

imageUris -> (list)

A list of URIs for containers created in the context Region.

(string)

Constraints:

min: 1

max: 1024

tags -> (map)

The tags that apply to this image.

Constraints:

min: 1

max: 50

key -> (string)

Constraints:

min: 1

max: 128

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

value -> (string)

Constraints:

max: 256

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.

Possible values:

USER_INITIATED

SCHEDULED

IMPORT

IMPORT_ISO

imageSource -> (string)

The origin of the base image that Image Builder used to build this image.

Possible values:

AMAZON_MANAGED

AWS_MARKETPLACE

IMPORTED

CUSTOM

scanState -> (structure)

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 .

Possible values:

PENDING

SCANNING

COLLECTING

COMPLETED

ABANDONED

FAILED

TIMED_OUT

reason -> (string)

The reason for the scan status for the image.

Constraints:

min: 1

max: 1024

imageScanningConfiguration -> (structure)

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 -> (structure)

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.

Constraints:

min: 1

max: 1024

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)

Constraints:

min: 1

max: 1024

deprecationTime -> (timestamp)

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.

Constraints:

pattern: ^lce-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

executionRole -> (string)

The name or Amazon Resource Name (ARN) for the IAM role you create that grants Image Builder access to perform workflow actions.

Constraints:

min: 1

max: 2048

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

workflows -> (list)

The build, test, and distribution workflow configurations that are associated with the image.

(structure)

Contains control settings and configurable inputs for a workflow resource.

workflowArn -> (string) [required]

The Amazon Resource Name (ARN) of the workflow resource.

Constraints:

pattern: ^arn:aws(?:-[a-z]+)*:imagebuilder:[a-z]{2,}(?:-[a-z]+)+-[0-9]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?):workflow/(build|test|distribution)/[a-z0-9-_]+/(?:(?:([0-9]+|x)\.([0-9]+|x)\.([0-9]+|x))|(?:[0-9]+\.[0-9]+\.[0-9]+/[0-9]+))$

parameters -> (list)

Contains parameter values for each of the parameters that the workflow document defined for the workflow resource.

Constraints:

min: 1

(structure)

Contains a key/value pair that sets the named workflow parameter.

name -> (string) [required]

The name of the workflow parameter to set.

Constraints:

min: 1

max: 128

pattern: [^\x00]+

value -> (list) [required]

Sets the value for the named workflow parameter.

(string)

Constraints:

min: 0

pattern: [^\x00]*

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.

Constraints:

min: 1

max: 100

pattern: ^[A-Za-z0-9][A-Za-z0-9-_+#]{0,99}$

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.

Possible values:

CONTINUE

ABORT

loggingConfiguration -> (structure)

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 .

Constraints:

min: 1

max: 512

pattern: ^[a-zA-Z0-9\-_/\.]{1,512}$

latestVersionReferences -> (structure)

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.

Constraints:

pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?|third-party):(?:image-recipe|container-recipe|infrastructure-configuration|distribution-configuration|component|image|image-pipeline|lifecycle-policy|workflow\/(?:build|test|distribution))/[a-z0-9-_]+(?:/(?:(?:x|[0-9]+)\.(?:x|[0-9]+)\.(?:x|[0-9]+))(?:/[0-9]+)?)?$

latestMajorVersionArn -> (string)

The latest version Amazon Resource Name (ARN) with the same major version of the Image Builder resource.

Constraints:

pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?|third-party):(?:image-recipe|container-recipe|infrastructure-configuration|distribution-configuration|component|image|image-pipeline|lifecycle-policy|workflow\/(?:build|test|distribution))/[a-z0-9-_]+(?:/(?:(?:x|[0-9]+)\.(?:x|[0-9]+)\.(?:x|[0-9]+))(?:/[0-9]+)?)?$

latestMinorVersionArn -> (string)

The latest version Amazon Resource Name (ARN) with the same minor version of the Image Builder resource.

Constraints:

pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?|third-party):(?:image-recipe|container-recipe|infrastructure-configuration|distribution-configuration|component|image|image-pipeline|lifecycle-policy|workflow\/(?:build|test|distribution))/[a-z0-9-_]+(?:/(?:(?:x|[0-9]+)\.(?:x|[0-9]+)\.(?:x|[0-9]+))(?:/[0-9]+)?)?$

latestPatchVersionArn -> (string)

The latest version Amazon Resource Name (ARN) with the same patch version of the Image Builder resource.

Constraints:

pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws(?:-[a-z-]+)?|third-party):(?:image-recipe|container-recipe|infrastructure-configuration|distribution-configuration|component|image|image-pipeline|lifecycle-policy|workflow\/(?:build|test|distribution))/[a-z0-9-_]+(?:/(?:(?:x|[0-9]+)\.(?:x|[0-9]+)\.(?:x|[0-9]+))(?:/[0-9]+)?)?$

Table of Contents

Feedback

User Guide

get-image¶

Description¶

Synopsis¶

Options¶

Global Options¶

Examples¶

Note

Output¶

Note

Note

Note

Note

Note

Note

Note