CancelImageCreation

$result = $client->cancelImageCreation([/* ... */]);
$promise = $client->cancelImageCreationAsync([/* ... */]);

Cancels the creation of an image. This operation can only be used on images in a non-terminal state. Cancellation is asynchronous: the request returns immediately, then Image Builder stops the running build and moves the image to the CANCELLED state. Output resources that the build already created, such as AMIs and snapshots, aren't removed.

Parameter Syntax

$result = $client->cancelImageCreation([
    'clientToken' => '<string>', // REQUIRED
    'imageBuildVersionArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'imageBuildVersionArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

Examples

Example 1: Cancel an image build

The following example cancels a build that is in progress for the specified image build version.

$result = $client->cancelImageCreation([
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE77777',
    'imageBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0/1',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE77777',
    'imageBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0/1',
    'requestId' => 'fead325f-72d9-42b5-b2ed-c5294984c6a9',
]

CancelLifecycleExecution

$result = $client->cancelLifecycleExecution([/* ... */]);
$promise = $client->cancelLifecycleExecutionAsync([/* ... */]);

Cancels a lifecycle execution – a single run of lifecycle actions that a lifecycle policy or a StartResourceStateUpdate request started. You can only cancel an execution that hasn't reached a terminal state. Cancellation is asynchronous and doesn't undo completed lifecycle actions.

Parameter Syntax

$result = $client->cancelLifecycleExecution([
    'clientToken' => '<string>', // REQUIRED
    'lifecycleExecutionId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'lifecycleExecutionId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

Examples

Example 1: Cancel a lifecycle execution

The following example cancels the scheduled resource state update associated with the specified lifecycle execution ID before it runs.

$result = $client->cancelLifecycleExecution([
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE97531',
    'lifecycleExecutionId' => 'lce-401aefc3-a829-46f6-8fc2-91497988a503',
]);

Result syntax:

[
    'lifecycleExecutionId' => 'lce-401aefc3-a829-46f6-8fc2-91497988a503',
]

CreateComponent

$result = $client->createComponent([/* ... */]);
$promise = $client->createComponentAsync([/* ... */]);

Creates a new component that can be used to build, validate, test, and assess your image. The component is based on a YAML document that you specify using exactly one of the following methods:

• Inline, using the data property in the request body.

• A URL that points to a YAML document file stored in Amazon S3, using the uri property in the request body.

Image Builder determines the component type from the document. If the document contains a single phase named test, the component type is TEST. Otherwise, the component type is BUILD.

Parameter Syntax

$result = $client->createComponent([
    'changeDescription' => '<string>',
    'clientToken' => '<string>', // REQUIRED
    'data' => '<string>',
    'description' => '<string>',
    'dryRun' => true || false,
    'kmsKeyId' => '<string>',
    'name' => '<string>', // REQUIRED
    'platform' => 'Windows|Linux|macOS', // REQUIRED
    'semanticVersion' => '<string>', // REQUIRED
    'supportedOsVersions' => ['<string>', ...],
    'tags' => ['<string>', ...],
    'uri' => '<string>',
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'componentBuildVersionArn' => '<string>',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => '<string>',
        'latestMinorVersionArn' => '<string>',
        'latestPatchVersionArn' => '<string>',
        'latestVersionArn' => '<string>',
    ],
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

InvalidVersionNumberException:

Your version number is out of bounds or does not follow the required syntax.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

InvalidParameterCombinationException:

You have specified a combination of parameters that isn't valid. For example, two mutually exclusive parameters, or a parameter without its required companion parameter. Review the error message for details.

ServiceQuotaExceededException:

You have exceeded the number of permitted resources or operations for this service. For service quotas, see EC2 Image Builder endpoints and quotas.

DryRunOperationException:

The dry run operation of the resource was successful, and no resources or mutations were actually performed due to the dry run flag in the request.

Examples

Example 1: Create a component from an inline document

The following example creates a build component from a YAML document provided inline in the request.

$result = $client->createComponent([
    'name' => 'my-example-component',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE11111',
    'data' => 'name: InstallMyAppdescription: Installs my applicationschemaVersion: 1.0phases: - name: build steps: - name: InstallApp action: ExecuteBash inputs: commands: - sudo yum -y install my-app',
    'description' => 'Installs the latest version of my application',
    'platform' => 'Linux',
    'semanticVersion' => '1.0.0',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE11111',
    'componentBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0/1',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/x.x.x',
    ],
    'requestId' => 'e769f240-fb6a-4253-88d1-20a80cbe787d',
]

Example 2: Create a component from a document stored in Amazon S3

The following example creates a component from a YAML definition document that's stored in an Amazon S3 bucket. The definition document for this component includes an AppVersion parameter that recipes can set when they include the component.

$result = $client->createComponent([
    'name' => 'my-example-parameterized-component',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE10101',
    'description' => 'Installs a configurable version of my application',
    'platform' => 'Linux',
    'semanticVersion' => '1.0.0',
    'uri' => 's3://amzn-s3-demo-bucket/components/install-my-app.yaml',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE10101',
    'componentBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-parameterized-component/1.0.0/1',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-parameterized-component/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-parameterized-component/1.0.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-parameterized-component/1.0.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-parameterized-component/x.x.x',
    ],
    'requestId' => '0cec8e32-a5c6-4aeb-ac3a-6471c8a2a8a9',
]

CreateContainerRecipe

$result = $client->createContainerRecipe([/* ... */]);
$promise = $client->createContainerRecipeAsync([/* ... */]);

Creates a new container recipe. Container recipes define how images are configured, tested, and assessed.

Parameter Syntax

$result = $client->createContainerRecipe([
    'clientToken' => '<string>', // REQUIRED
    'components' => [
        [
            'componentArn' => '<string>', // REQUIRED
            'parameters' => [
                [
                    'name' => '<string>', // REQUIRED
                    'value' => ['<string>', ...], // REQUIRED
                ],
                // ...
            ],
        ],
        // ...
    ],
    'containerType' => 'DOCKER', // REQUIRED
    'description' => '<string>',
    'dockerfileTemplateData' => '<string>',
    'dockerfileTemplateUri' => '<string>',
    'dryRun' => true || false,
    'imageOsVersionOverride' => '<string>',
    'instanceConfiguration' => [
        'blockDeviceMappings' => [
            [
                'deviceName' => '<string>',
                'ebs' => [
                    'deleteOnTermination' => true || false,
                    'encrypted' => true || false,
                    'iops' => <integer>,
                    'kmsKeyId' => '<string>',
                    'snapshotId' => '<string>',
                    'throughput' => <integer>,
                    'volumeSize' => <integer>,
                    'volumeType' => 'standard|io1|io2|gp2|gp3|sc1|st1',
                ],
                'noDevice' => '<string>',
                'virtualName' => '<string>',
            ],
            // ...
        ],
        'image' => '<string>',
    ],
    'kmsKeyId' => '<string>',
    'name' => '<string>', // REQUIRED
    'parentImage' => '<string>', // REQUIRED
    'platformOverride' => 'Windows|Linux|macOS',
    'semanticVersion' => '<string>', // REQUIRED
    'tags' => ['<string>', ...],
    'targetRepository' => [ // REQUIRED
        'repositoryName' => '<string>', // REQUIRED
        'service' => 'ECR', // REQUIRED
    ],
    'workingDirectory' => '<string>',
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'containerRecipeArn' => '<string>',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => '<string>',
        'latestMinorVersionArn' => '<string>',
        'latestPatchVersionArn' => '<string>',
        'latestVersionArn' => '<string>',
    ],
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

InvalidVersionNumberException:

Your version number is out of bounds or does not follow the required syntax.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

ResourceAlreadyExistsException:

The resource that you are trying to create already exists.

ServiceQuotaExceededException:

You have exceeded the number of permitted resources or operations for this service. For service quotas, see EC2 Image Builder endpoints and quotas.

DryRunOperationException:

The dry run operation of the resource was successful, and no resources or mutations were actually performed due to the dry run flag in the request.

Examples

Example 1: Create a container recipe with an inline Dockerfile template

The following example creates a Docker container recipe that applies one build component, using the latest Amazon Linux container image as the parent and an existing ECR repository as the target.

$result = $client->createContainerRecipe([
    'name' => 'my-example-container-recipe',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE99999',
    'components' => [
        [
            'componentArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-container-component/1.0.0/1',
        ],
    ],
    'containerType' => 'DOCKER',
    'dockerfileTemplateData' => 'FROM {{{ imagebuilder:parentImage }}}{{{ imagebuilder:environments }}}{{{ imagebuilder:components }}}',
    'parentImage' => 'amazonlinux:latest',
    'semanticVersion' => '1.0.0',
    'targetRepository' => [
        'repositoryName' => 'my-example-container-repo',
        'service' => 'ECR',
    ],
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE99999',
    'containerRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.0.0',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.0.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.0.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/x.x.x',
    ],
    'requestId' => '20b16948-45a4-4b3a-9a17-d54779847365',
]

Example 2: Create a container recipe with a custom build instance configuration

The following example creates a container recipe that customizes the Amazon EC2 instance that builds the container image. The build instance launches from an Amazon ECS-optimized instance image and uses a 40 GiB gp3 volume.

$result = $client->createContainerRecipe([
    'name' => 'my-example-container-recipe',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE40404',
    'components' => [
        [
            'componentArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-container-component/1.0.0/1',
        ],
    ],
    'containerType' => 'DOCKER',
    'description' => 'A container recipe that builds on an ECS-optimized instance image with a larger build volume',
    'dockerfileTemplateData' => 'FROM {{{ imagebuilder:parentImage }}}{{{ imagebuilder:environments }}}{{{ imagebuilder:components }}}',
    'instanceConfiguration' => [
        'blockDeviceMappings' => [
            [
                'deviceName' => '/dev/xvda',
                'ebs' => [
                    'deleteOnTermination' => 1,
                    'volumeSize' => 40,
                    'volumeType' => 'gp3',
                ],
            ],
        ],
        'image' => 'ami-1234567890abcdef0',
    ],
    'parentImage' => 'amazonlinux:latest',
    'semanticVersion' => '1.1.0',
    'targetRepository' => [
        'repositoryName' => 'my-example-container-repo',
        'service' => 'ECR',
    ],
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE40404',
    'containerRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.1.0',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.1.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.1.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/x.x.x',
    ],
    'requestId' => '4b6fc7f3-5b6b-4086-858e-22d4c7f9a37f',
]

CreateDistributionConfiguration

$result = $client->createDistributionConfiguration([/* ... */]);
$promise = $client->createDistributionConfigurationAsync([/* ... */]);

Creates a new distribution configuration. Distribution configurations define and configure the outputs for your images, including the target Regions, accounts, and settings for each Region.

Parameter Syntax

$result = $client->createDistributionConfiguration([
    'clientToken' => '<string>', // REQUIRED
    'description' => '<string>',
    'distributions' => [ // REQUIRED
        [
            'amiDistributionConfiguration' => [
                'amiTags' => ['<string>', ...],
                'description' => '<string>',
                'kmsKeyId' => '<string>',
                'launchPermission' => [
                    'organizationArns' => ['<string>', ...],
                    'organizationalUnitArns' => ['<string>', ...],
                    'userGroups' => ['<string>', ...],
                    'userIds' => ['<string>', ...],
                ],
                'name' => '<string>',
                'targetAccountIds' => ['<string>', ...],
            ],
            'containerDistributionConfiguration' => [
                'containerTags' => ['<string>', ...],
                'description' => '<string>',
                'targetRepository' => [ // REQUIRED
                    'repositoryName' => '<string>', // REQUIRED
                    'service' => 'ECR', // REQUIRED
                ],
            ],
            'fastLaunchConfigurations' => [
                [
                    'accountId' => '<string>',
                    'enabled' => true || false, // REQUIRED
                    'launchTemplate' => [
                        'launchTemplateId' => '<string>',
                        'launchTemplateName' => '<string>',
                        'launchTemplateVersion' => '<string>',
                    ],
                    'maxParallelLaunches' => <integer>,
                    'snapshotConfiguration' => [
                        'targetResourceCount' => <integer>,
                    ],
                ],
                // ...
            ],
            'launchTemplateConfigurations' => [
                [
                    'accountId' => '<string>',
                    'launchTemplateId' => '<string>', // REQUIRED
                    'setDefaultVersion' => true || false,
                ],
                // ...
            ],
            'licenseConfigurationArns' => ['<string>', ...],
            'region' => '<string>', // REQUIRED
            's3ExportConfiguration' => [
                'diskImageFormat' => 'VMDK|RAW|VHD', // REQUIRED
                'roleName' => '<string>', // REQUIRED
                's3Bucket' => '<string>', // REQUIRED
                's3Prefix' => '<string>',
            ],
            'ssmParameterConfigurations' => [
                [
                    'amiAccountId' => '<string>',
                    'dataType' => 'text|aws:ec2:image',
                    'parameterName' => '<string>', // REQUIRED
                ],
                // ...
            ],
        ],
        // ...
    ],
    'dryRun' => true || false,
    'name' => '<string>', // REQUIRED
    'tags' => ['<string>', ...],
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'distributionConfigurationArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

ResourceAlreadyExistsException:

The resource that you are trying to create already exists.

InvalidParameterCombinationException:

You have specified a combination of parameters that isn't valid. For example, two mutually exclusive parameters, or a parameter without its required companion parameter. Review the error message for details.

ServiceQuotaExceededException:

You have exceeded the number of permitted resources or operations for this service. For service quotas, see EC2 Image Builder endpoints and quotas.

DryRunOperationException:

The dry run operation of the resource was successful, and no resources or mutations were actually performed due to the dry run flag in the request.

Examples

Example 1: Create a distribution configuration

The following example creates a distribution configuration that distributes the output AMI to two Regions. The AMI name includes the build date, so that repeated builds create unique AMI names.

$result = $client->createDistributionConfiguration([
    'name' => 'my-example-distribution',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE44444',
    'description' => 'Copies the output AMI to a second Region',
    'distributions' => [
        [
            'amiDistributionConfiguration' => [
                'name' => 'my-example-image-{{ imagebuilder:buildDate }}',
            ],
            'region' => 'us-west-2',
        ],
        [
            'amiDistributionConfiguration' => [
                'name' => 'my-example-image-{{ imagebuilder:buildDate }}',
            ],
            'region' => 'us-east-1',
        ],
    ],
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE44444',
    'distributionConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:distribution-configuration/my-example-distribution',
    'requestId' => 'ca5312ad-a273-4c8c-817e-042941a5762d',
]

Example 2: Create a distribution configuration with launch permissions and a launch template update

The following example creates a distribution configuration that distributes the output AMI to two Regions. In us-east-1, it shares the AMI with another AWS account. In us-west-2, it sets the new AMI as the default version of your launch template.

$result = $client->createDistributionConfiguration([
    'name' => 'my-example-distribution',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE56789',
    'description' => 'Distributes the output AMI to two Regions and shares it with another account',
    'distributions' => [
        [
            'amiDistributionConfiguration' => [
                'name' => 'my-example-image-{{ imagebuilder:buildDate }}',
            ],
            'launchTemplateConfigurations' => [
                [
                    'launchTemplateId' => 'lt-1234567890abcdef0',
                    'setDefaultVersion' => 1,
                ],
            ],
            'region' => 'us-west-2',
        ],
        [
            'amiDistributionConfiguration' => [
                'name' => 'my-example-image-{{ imagebuilder:buildDate }}',
                'launchPermission' => [
                    'userIds' => [
                        '444455556666',
                    ],
                ],
            ],
            'region' => 'us-east-1',
        ],
    ],
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE56789',
    'distributionConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:distribution-configuration/my-example-distribution',
    'requestId' => '13c97ae8-8e39-4e12-af78-25e70def0933',
]

CreateImage

$result = $client->createImage([/* ... */]);
$promise = $client->createImageAsync([/* ... */]);

Creates a new image along with all configured output resources defined in the distribution configuration. You must specify exactly one recipe for your image, using either a containerRecipeArn or an imageRecipeArn.

The response returns as soon as Image Builder creates the new image resource. The image build process runs asynchronously. To check its progress, call GetImage and check the image status.

Parameter Syntax

$result = $client->createImage([
    'clientToken' => '<string>', // REQUIRED
    'containerRecipeArn' => '<string>',
    'distributionConfigurationArn' => '<string>',
    'enhancedImageMetadataEnabled' => true || false,
    'executionRole' => '<string>',
    'imageRecipeArn' => '<string>',
    'imageScanningConfiguration' => [
        'ecrConfiguration' => [
            'containerTags' => ['<string>', ...],
            'repositoryName' => '<string>',
        ],
        'imageScanningEnabled' => true || false,
    ],
    'imageTestsConfiguration' => [
        'imageTestsEnabled' => true || false,
        'timeoutMinutes' => <integer>,
    ],
    'infrastructureConfigurationArn' => '<string>', // REQUIRED
    'loggingConfiguration' => [
        'logGroupName' => '<string>',
    ],
    'tags' => ['<string>', ...],
    'workflows' => [
        [
            'onFailure' => 'CONTINUE|ABORT',
            'parallelGroup' => '<string>',
            'parameters' => [
                [
                    'name' => '<string>', // REQUIRED
                    'value' => ['<string>', ...], // REQUIRED
                ],
                // ...
            ],
            'workflowArn' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'imageBuildVersionArn' => '<string>',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => '<string>',
        'latestMinorVersionArn' => '<string>',
        'latestPatchVersionArn' => '<string>',
        'latestVersionArn' => '<string>',
    ],
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

ServiceQuotaExceededException:

You have exceeded the number of permitted resources or operations for this service. For service quotas, see EC2 Image Builder endpoints and quotas.

Examples

Example 1: Create an image

The following example creates a new image from the specified image recipe and infrastructure configuration.

$result = $client->createImage([
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLEeeeee',
    'imageRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.0',
    'infrastructureConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLEeeeee',
    'imageBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0/1',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/x.x.x',
    ],
    'requestId' => '62e9b43f-a9fd-4272-89fb-ce6235d07ab4',
]

Example 2: Create an image with custom build and parallel test workflows

The following example creates an image that uses your custom build and test workflows. It uses the Image Builder service-linked role as the execution role. Both test workflows are in the same parallel group, so they can run at the same time after the build workflow completes.

$result = $client->createImage([
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE01234',
    'executionRole' => 'arn:aws:iam::111122223333:role/aws-service-role/imagebuilder.amazonaws.com/AWSServiceRoleForImageBuilder',
    'imageRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.0',
    'infrastructureConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure',
    'workflows' => [
        [
            'workflowArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.0.0/1',
        ],
        [
            'parallelGroup' => 'post-build-tests',
            'workflowArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/test/my-example-integration-tests/1.0.0/1',
        ],
        [
            'parallelGroup' => 'post-build-tests',
            'workflowArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/test/my-example-compliance-tests/1.0.0/1',
        ],
    ],
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE01234',
    'imageBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0/1',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/x.x.x',
    ],
    'requestId' => '359f18b1-814f-4857-987f-924214970897',
]

CreateImagePipeline

$result = $client->createImagePipeline([/* ... */]);
$promise = $client->createImagePipelineAsync([/* ... */]);

Creates a new image pipeline. Use image pipelines to automate the creation and distribution of images. You must specify exactly one recipe for the pipeline, using either a containerRecipeArn or an imageRecipeArn.

Parameter Syntax

$result = $client->createImagePipeline([
    'clientToken' => '<string>', // REQUIRED
    'containerRecipeArn' => '<string>',
    'description' => '<string>',
    'distributionConfigurationArn' => '<string>',
    'dryRun' => true || false,
    'enhancedImageMetadataEnabled' => true || false,
    'executionRole' => '<string>',
    'imageRecipeArn' => '<string>',
    'imageScanningConfiguration' => [
        'ecrConfiguration' => [
            'containerTags' => ['<string>', ...],
            'repositoryName' => '<string>',
        ],
        'imageScanningEnabled' => true || false,
    ],
    'imageTags' => ['<string>', ...],
    'imageTestsConfiguration' => [
        'imageTestsEnabled' => true || false,
        'timeoutMinutes' => <integer>,
    ],
    'infrastructureConfigurationArn' => '<string>', // REQUIRED
    'loggingConfiguration' => [
        'imageLogGroupName' => '<string>',
        'pipelineLogGroupName' => '<string>',
    ],
    'name' => '<string>', // REQUIRED
    'schedule' => [
        'autoDisablePolicy' => [
            'failureCount' => <integer>, // REQUIRED
        ],
        'pipelineExecutionStartCondition' => 'EXPRESSION_MATCH_ONLY|EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE',
        'scheduleExpression' => '<string>',
        'timezone' => '<string>',
    ],
    'status' => 'DISABLED|ENABLED',
    'tags' => ['<string>', ...],
    'workflows' => [
        [
            'onFailure' => 'CONTINUE|ABORT',
            'parallelGroup' => '<string>',
            'parameters' => [
                [
                    'name' => '<string>', // REQUIRED
                    'value' => ['<string>', ...], // REQUIRED
                ],
                // ...
            ],
            'workflowArn' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'imagePipelineArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

ResourceAlreadyExistsException:

The resource that you are trying to create already exists.

ServiceQuotaExceededException:

You have exceeded the number of permitted resources or operations for this service. For service quotas, see EC2 Image Builder endpoints and quotas.

DryRunOperationException:

The dry run operation of the resource was successful, and no resources or mutations were actually performed due to the dry run flag in the request.

Examples

Example 1: Create an image pipeline

The following example creates a pipeline that builds a new image version every Sunday at 9:00 AM UTC, if the base image or components have updates.

$result = $client->createImagePipeline([
    'name' => 'my-example-pipeline',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE55555',
    'description' => 'Builds a new version of my image every Sunday',
    'distributionConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:distribution-configuration/my-example-distribution',
    'imageRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.0',
    'infrastructureConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure',
    'schedule' => [
        'pipelineExecutionStartCondition' => 'EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE',
        'scheduleExpression' => 'cron(0 9 ? * SUN *)',
    ],
    'status' => 'ENABLED',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE55555',
    'imagePipelineArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-pipeline/my-example-pipeline',
    'requestId' => 'db0a9329-35ef-4b53-98d0-a34385e44e28',
]

Example 2: Create an image pipeline with scanning, custom workflows, and an auto-disable policy

The following example creates a pipeline that uses your custom build workflow and enables image scanning. The schedule evaluates its cron expression in the America/Los_Angeles time zone. The auto-disable policy disables the pipeline after 3 consecutive failed scheduled builds.

$result = $client->createImagePipeline([
    'name' => 'my-example-pipeline',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE30303',
    'description' => 'Builds a scanned image with my custom build workflow on Sunday mornings when dependency updates are available',
    'distributionConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:distribution-configuration/my-example-distribution',
    'executionRole' => 'arn:aws:iam::111122223333:role/aws-service-role/imagebuilder.amazonaws.com/AWSServiceRoleForImageBuilder',
    'imageRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.1.0',
    'imageScanningConfiguration' => [
        'imageScanningEnabled' => 1,
    ],
    'infrastructureConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure',
    'schedule' => [
        'autoDisablePolicy' => [
            'failureCount' => 3,
        ],
        'pipelineExecutionStartCondition' => 'EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE',
        'scheduleExpression' => 'cron(0 9 ? * SUN *)',
        'timezone' => 'America/Los_Angeles',
    ],
    'status' => 'ENABLED',
    'workflows' => [
        [
            'workflowArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.0.0/1',
        ],
    ],
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE30303',
    'imagePipelineArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-pipeline/my-example-pipeline',
    'requestId' => 'f8da3ec9-4b76-4aa3-817a-c35a90f59dca',
]

CreateImageRecipe

$result = $client->createImageRecipe([/* ... */]);
$promise = $client->createImageRecipeAsync([/* ... */]);

Creates a new image recipe. Image recipes define how images are configured, tested, and assessed.

Parameter Syntax

$result = $client->createImageRecipe([
    'additionalInstanceConfiguration' => [
        'systemsManagerAgent' => [
            'uninstallAfterBuild' => true || false,
        ],
        'userDataOverride' => '<string>',
    ],
    'amiTags' => ['<string>', ...],
    'amiWatermarks' => ['<string>', ...],
    'blockDeviceMappings' => [
        [
            'deviceName' => '<string>',
            'ebs' => [
                'deleteOnTermination' => true || false,
                'encrypted' => true || false,
                'iops' => <integer>,
                'kmsKeyId' => '<string>',
                'snapshotId' => '<string>',
                'throughput' => <integer>,
                'volumeSize' => <integer>,
                'volumeType' => 'standard|io1|io2|gp2|gp3|sc1|st1',
            ],
            'noDevice' => '<string>',
            'virtualName' => '<string>',
        ],
        // ...
    ],
    'clientToken' => '<string>', // REQUIRED
    'components' => [
        [
            'componentArn' => '<string>', // REQUIRED
            'parameters' => [
                [
                    'name' => '<string>', // REQUIRED
                    'value' => ['<string>', ...], // REQUIRED
                ],
                // ...
            ],
        ],
        // ...
    ],
    'description' => '<string>',
    'dryRun' => true || false,
    'name' => '<string>', // REQUIRED
    'parentImage' => '<string>', // REQUIRED
    'semanticVersion' => '<string>', // REQUIRED
    'tags' => ['<string>', ...],
    'workingDirectory' => '<string>',
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'imageRecipeArn' => '<string>',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => '<string>',
        'latestMinorVersionArn' => '<string>',
        'latestPatchVersionArn' => '<string>',
        'latestVersionArn' => '<string>',
    ],
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

InvalidVersionNumberException:

Your version number is out of bounds or does not follow the required syntax.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

ResourceAlreadyExistsException:

The resource that you are trying to create already exists.

ServiceQuotaExceededException:

You have exceeded the number of permitted resources or operations for this service. For service quotas, see EC2 Image Builder endpoints and quotas.

DryRunOperationException:

The dry run operation of the resource was successful, and no resources or mutations were actually performed due to the dry run flag in the request.

Examples

Example 1: Create an image recipe

The following example creates an image recipe that applies a custom component on top of the latest Amazon Linux 2023 base image.

$result = $client->createImageRecipe([
    'name' => 'my-example-recipe',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE22222',
    'components' => [
        [
            'componentArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0/1',
        ],
    ],
    'description' => 'An image recipe that installs my application on Amazon Linux 2023',
    'parentImage' => 'arn:aws:imagebuilder:us-west-2:aws:image/amazon-linux-2023-x86/x.x.x',
    'semanticVersion' => '1.0.0',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE22222',
    'imageRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.0',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/x.x.x',
    ],
    'requestId' => '89f4af2f-4f28-45e6-a9d8-abeba591df6a',
]

Example 2: Create an image recipe with component parameters and block device mappings

The following example creates an image recipe that configures its components and storage. The AppVersion component parameter selects the application version to install. The block device mapping increases the root volume to an encrypted 30 GiB gp3 volume.

$result = $client->createImageRecipe([
    'name' => 'my-example-recipe',
    'blockDeviceMappings' => [
        [
            'deviceName' => '/dev/xvda',
            'ebs' => [
                'deleteOnTermination' => 1,
                'encrypted' => 1,
                'volumeSize' => 30,
                'volumeType' => 'gp3',
            ],
        ],
    ],
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE20202',
    'components' => [
        [
            'componentArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-parameterized-component/1.0.0/1',
            'parameters' => [
                [
                    'name' => 'AppVersion',
                    'value' => [
                        '2.5.0',
                    ],
                ],
            ],
        ],
    ],
    'description' => 'Installs a specific version of my application on Amazon Linux 2023 with a larger encrypted root volume',
    'parentImage' => 'arn:aws:imagebuilder:us-west-2:aws:image/amazon-linux-2023-x86/x.x.x',
    'semanticVersion' => '1.1.0',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE20202',
    'imageRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.1.0',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.1.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.1.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/x.x.x',
    ],
    'requestId' => 'e3bdc054-d12e-4578-a847-68a18da724ca',
]

CreateInfrastructureConfiguration

$result = $client->createInfrastructureConfiguration([/* ... */]);
$promise = $client->createInfrastructureConfigurationAsync([/* ... */]);

Creates a new infrastructure configuration. An infrastructure configuration defines the environment in which your image will be built and tested.

Parameter Syntax

$result = $client->createInfrastructureConfiguration([
    'clientToken' => '<string>', // REQUIRED
    'description' => '<string>',
    'dryRun' => true || false,
    'instanceMetadataOptions' => [
        'httpPutResponseHopLimit' => <integer>,
        'httpTokens' => '<string>',
    ],
    'instanceProfileName' => '<string>', // REQUIRED
    'instanceTypes' => ['<string>', ...],
    'keyPair' => '<string>',
    'logging' => [
        's3Logs' => [
            's3BucketName' => '<string>',
            's3KeyPrefix' => '<string>',
        ],
    ],
    'name' => '<string>', // REQUIRED
    'placement' => [
        'availabilityZone' => '<string>',
        'hostId' => '<string>',
        'hostResourceGroupArn' => '<string>',
        'tenancy' => 'default|dedicated|host',
    ],
    'resourceTags' => ['<string>', ...],
    'securityGroupIds' => ['<string>', ...],
    'snsTopicArn' => '<string>',
    'subnetId' => '<string>',
    'tags' => ['<string>', ...],
    'terminateInstanceOnFailure' => true || false,
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'infrastructureConfigurationArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

ResourceAlreadyExistsException:

The resource that you are trying to create already exists.

ServiceQuotaExceededException:

You have exceeded the number of permitted resources or operations for this service. For service quotas, see EC2 Image Builder endpoints and quotas.

DryRunOperationException:

The dry run operation of the resource was successful, and no resources or mutations were actually performed due to the dry run flag in the request.

Examples

Example 1: Create an infrastructure configuration

The following example creates an infrastructure configuration that gives Image Builder a choice of two instance types for its build and test instances.

$result = $client->createInfrastructureConfiguration([
    'name' => 'my-example-infrastructure',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE33333',
    'description' => 'An infrastructure configuration for Amazon Linux builds',
    'instanceProfileName' => 'EC2InstanceProfileForImageBuilder',
    'instanceTypes' => [
        't3.medium',
        't3.large',
    ],
    'terminateInstanceOnFailure' => 1,
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE33333',
    'infrastructureConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure',
    'requestId' => '67082698-415b-4d9f-8be0-84a58380b93f',
]

Example 2: Create an infrastructure configuration with instance placement and metadata options

The following example creates an infrastructure configuration. It places your build and test instances in a single Availability Zone and requires IMDSv2 for instance metadata requests. It also applies resource tags to the resources that Image Builder creates during the build.

$result = $client->createInfrastructureConfiguration([
    'name' => 'my-example-infrastructure',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE98765',
    'description' => 'An infrastructure configuration that pins build instances to one Availability Zone and requires IMDSv2',
    'instanceMetadataOptions' => [
        'httpPutResponseHopLimit' => 2,
        'httpTokens' => 'required',
    ],
    'instanceProfileName' => 'my-example-instance-role',
    'placement' => [
        'availabilityZone' => 'us-west-2a',
    ],
    'resourceTags' => [
        'CostCenter' => '12345',
        'Environment' => 'test',
    ],
    'terminateInstanceOnFailure' => 1,
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE98765',
    'infrastructureConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure',
    'requestId' => 'b96b54d8-daa6-4fdf-b25a-7b570bc2ab25',
]

CreateLifecyclePolicy

$result = $client->createLifecyclePolicy([/* ... */]);
$promise = $client->createLifecyclePolicyAsync([/* ... */]);

Creates a lifecycle policy resource.

Parameter Syntax

$result = $client->createLifecyclePolicy([
    'clientToken' => '<string>', // REQUIRED
    'description' => '<string>',
    'dryRun' => true || false,
    'executionRole' => '<string>', // REQUIRED
    'name' => '<string>', // REQUIRED
    'policyDetails' => [ // REQUIRED
        [
            'action' => [ // REQUIRED
                'includeResources' => [
                    'amis' => true || false,
                    'containers' => true || false,
                    'snapshots' => true || false,
                ],
                'type' => 'DELETE|DEPRECATE|DISABLE', // REQUIRED
            ],
            'exclusionRules' => [
                'amis' => [
                    'isPublic' => true || false,
                    'lastLaunched' => [
                        'unit' => 'DAYS|WEEKS|MONTHS|YEARS', // REQUIRED
                        'value' => <integer>, // REQUIRED
                    ],
                    'regions' => ['<string>', ...],
                    'sharedAccounts' => ['<string>', ...],
                    'tagMap' => ['<string>', ...],
                ],
                'tagMap' => ['<string>', ...],
            ],
            'filter' => [ // REQUIRED
                'retainAtLeast' => <integer>,
                'type' => 'AGE|COUNT', // REQUIRED
                'unit' => 'DAYS|WEEKS|MONTHS|YEARS',
                'value' => <integer>, // REQUIRED
            ],
        ],
        // ...
    ],
    'resourceSelection' => [ // REQUIRED
        'recipes' => [
            [
                'name' => '<string>', // REQUIRED
                'semanticVersion' => '<string>', // REQUIRED
            ],
            // ...
        ],
        'tagMap' => ['<string>', ...],
    ],
    'resourceType' => 'AMI_IMAGE|CONTAINER_IMAGE', // REQUIRED
    'status' => 'DISABLED|ENABLED',
    'tags' => ['<string>', ...],
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'lifecyclePolicyArn' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

ResourceAlreadyExistsException:

The resource that you are trying to create already exists.

ServiceQuotaExceededException:

You have exceeded the number of permitted resources or operations for this service. For service quotas, see EC2 Image Builder endpoints and quotas.

DryRunOperationException:

The dry run operation of the resource was successful, and no resources or mutations were actually performed due to the dry run flag in the request.

Examples

Example 1: Create a lifecycle policy

The following example creates a lifecycle policy that deletes AMI-based images six months after they were created, selecting the images that match the specified resource tags.

$result = $client->createLifecyclePolicy([
    'name' => 'my-example-lifecycle-policy',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE13579',
    'executionRole' => 'arn:aws:iam::111122223333:role/my-example-lifecycle-role',
    'policyDetails' => [
        [
            'action' => [
                'type' => 'DELETE',
            ],
            'filter' => [
                'type' => 'AGE',
                'value' => 6,
                'unit' => 'MONTHS',
            ],
        ],
    ],
    'resourceSelection' => [
        'tagMap' => [
            'Environment' => 'test',
        ],
    ],
    'resourceType' => 'AMI_IMAGE',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE13579',
    'lifecyclePolicyArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:lifecycle-policy/my-example-lifecycle-policy',
]

Example 2: Create a lifecycle policy with exclusion rules

The following example creates a lifecycle policy that deletes images created from the specified recipe version after six months. The policy excludes images whose AMIs launched an instance within the last 30 days or are tagged to be retained.

$result = $client->createLifecyclePolicy([
    'name' => 'my-example-lifecycle-policy',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE43210',
    'executionRole' => 'arn:aws:iam::111122223333:role/my-example-lifecycle-role',
    'policyDetails' => [
        [
            'action' => [
                'type' => 'DELETE',
            ],
            'exclusionRules' => [
                'amis' => [
                    'lastLaunched' => [
                        'value' => 30,
                        'unit' => 'DAYS',
                    ],
                    'tagMap' => [
                        'Retention' => 'keep',
                    ],
                ],
            ],
            'filter' => [
                'type' => 'AGE',
                'value' => 6,
                'unit' => 'MONTHS',
            ],
        ],
    ],
    'resourceSelection' => [
        'recipes' => [
            [
                'name' => 'my-example-recipe',
                'semanticVersion' => '1.0.0',
            ],
        ],
    ],
    'resourceType' => 'AMI_IMAGE',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE43210',
    'lifecyclePolicyArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:lifecycle-policy/my-example-lifecycle-policy',
]

CreateWorkflow

$result = $client->createWorkflow([/* ... */]);
$promise = $client->createWorkflowAsync([/* ... */]);

Creates a new workflow or a new version of an existing workflow. If a workflow with the same name and semantic version already exists, and your request changes its configuration, Image Builder creates a new build version. If the configuration is identical to the latest build version, the request fails because that workflow configuration already exists.

Parameter Syntax

$result = $client->createWorkflow([
    'changeDescription' => '<string>',
    'clientToken' => '<string>', // REQUIRED
    'data' => '<string>',
    'description' => '<string>',
    'dryRun' => true || false,
    'kmsKeyId' => '<string>',
    'name' => '<string>', // REQUIRED
    'semanticVersion' => '<string>', // REQUIRED
    'tags' => ['<string>', ...],
    'type' => 'BUILD|TEST|DISTRIBUTION', // REQUIRED
    'uri' => '<string>',
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => '<string>',
        'latestMinorVersionArn' => '<string>',
        'latestPatchVersionArn' => '<string>',
        'latestVersionArn' => '<string>',
    ],
    'workflowBuildVersionArn' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

InvalidVersionNumberException:

Your version number is out of bounds or does not follow the required syntax.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

InvalidParameterCombinationException:

You have specified a combination of parameters that isn't valid. For example, two mutually exclusive parameters, or a parameter without its required companion parameter. Review the error message for details.

ServiceQuotaExceededException:

You have exceeded the number of permitted resources or operations for this service. For service quotas, see EC2 Image Builder endpoints and quotas.

DryRunOperationException:

The dry run operation of the resource was successful, and no resources or mutations were actually performed due to the dry run flag in the request.

Examples

Example 1: Create a build workflow from an inline document

The following example creates a build workflow from a YAML workflow document provided inline in the request.

$result = $client->createWorkflow([
    'name' => 'my-example-workflow',
    'type' => 'BUILD',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE54321',
    'data' => 'name: my-example-workflowdescription: Workflow to build an AMIschemaVersion: 1.0steps: - name: LaunchBuildInstance action: LaunchInstance onFailure: Abort inputs: waitFor: ssmAgent - name: ApplyBuildComponents action: ExecuteComponents onFailure: Abort inputs: instanceId.$: $.stepOutputs.LaunchBuildInstance.instanceId - name: CreateOutputAMI action: CreateImage onFailure: Abort inputs: instanceId.$: $.stepOutputs.LaunchBuildInstance.instanceId - name: TerminateBuildInstance action: TerminateInstance onFailure: Continue inputs: instanceId.$: $.stepOutputs.LaunchBuildInstance.instanceId',
    'description' => 'Workflow to build an AMI',
    'semanticVersion' => '1.0.0',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE54321',
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.0.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.0.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/x.x.x',
    ],
    'workflowBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.0.0/1',
]

DeleteComponent

$result = $client->deleteComponent([/* ... */]);
$promise = $client->deleteComponentAsync([/* ... */]);

Deletes a component build version. The request fails with ResourceDependencyException if an image recipe or container recipe references this component version. It also fails if the component build version is shared with other accounts.

Parameter Syntax

$result = $client->deleteComponent([
    'componentBuildVersionArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'componentBuildVersionArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceDependencyException:

You have attempted to mutate or delete a resource with a dependency that prohibits this action. See the error message for more details.

Examples

Example 1: Delete a component build version

The following example deletes the specified component build version.

$result = $client->deleteComponent([
    'componentBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0/1',
]);

Result syntax:

[
    'componentBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0/1',
    'requestId' => 'c75a1764-2ca3-4cb4-9ce9-6d49f87942b0',
]

DeleteContainerRecipe

$result = $client->deleteContainerRecipe([/* ... */]);
$promise = $client->deleteContainerRecipeAsync([/* ... */]);

Deletes a container recipe. The request fails with ResourceDependencyException if the recipe is shared with other accounts, or if an image pipeline references it.

Parameter Syntax

$result = $client->deleteContainerRecipe([
    'containerRecipeArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'containerRecipeArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceDependencyException:

You have attempted to mutate or delete a resource with a dependency that prohibits this action. See the error message for more details.

Examples

Example 1: Delete a container recipe

The following example deletes the specified container recipe.

$result = $client->deleteContainerRecipe([
    'containerRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.0.0',
]);

Result syntax:

[
    'containerRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.0.0',
    'requestId' => '988e934a-b785-4705-aff1-4d9840a165aa',
]

DeleteDistributionConfiguration

$result = $client->deleteDistributionConfiguration([/* ... */]);
$promise = $client->deleteDistributionConfigurationAsync([/* ... */]);

Deletes a distribution configuration. You can't delete a configuration that an image pipeline still references. The request fails with ResourceDependencyException. Update or delete the referencing pipelines first.

Parameter Syntax

$result = $client->deleteDistributionConfiguration([
    'distributionConfigurationArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'distributionConfigurationArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ServiceUnavailableException:

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

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceDependencyException:

You have attempted to mutate or delete a resource with a dependency that prohibits this action. See the error message for more details.

Examples

Example 1: Delete a distribution configuration

The following example deletes the specified distribution configuration.

$result = $client->deleteDistributionConfiguration([
    'distributionConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:distribution-configuration/my-example-distribution-configuration',
]);

Result syntax:

[
    'distributionConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:distribution-configuration/my-example-distribution-configuration',
    'requestId' => '2b752b77-2038-40f4-996a-0a6da1be5e92',
]

DeleteImage

$result = $client->deleteImage([/* ... */]);
$promise = $client->deleteImageAsync([/* ... */]);

Deletes an Image Builder image resource. This does not delete any EC2 AMIs or ECR container images that are created during the image build process. You must clean those up separately, using the appropriate Amazon EC2 or Amazon ECR console actions, or API or CLI commands.

The request fails with ResourceDependencyException if the image is shared with other accounts, or if other resources depend on it. It also fails while the image build is still running. Cancel an in-progress build with CancelImageCreation before you delete the image.

• To deregister an EC2 Linux AMI, see Deregister your Linux AMI in the Amazon EC2 User Guide .

• To deregister an EC2 Windows AMI, see Deregister your Windows AMI in the Amazon EC2 Windows Guide .

• To delete a container image from Amazon ECR, see Deleting an image in the Amazon ECR User Guide.

Parameter Syntax

$result = $client->deleteImage([
    'imageBuildVersionArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'imageBuildVersionArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ServiceUnavailableException:

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

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceDependencyException:

You have attempted to mutate or delete a resource with a dependency that prohibits this action. See the error message for more details.

Examples

Example 1: Delete an image build version

The following example deletes the Image Builder image record for the specified build version - EC2 AMIs or ECR container images that the build created aren't removed.

$result = $client->deleteImage([
    'imageBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0/1',
]);

Result syntax:

[
    'imageBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0/1',
    'requestId' => 'fd45526c-ec37-4345-8843-329e4268e00e',
]

DeleteImagePipeline

$result = $client->deleteImagePipeline([/* ... */]);
$promise = $client->deleteImagePipelineAsync([/* ... */]);

Deletes an image pipeline. Images that the pipeline created aren't deleted - remove those separately with DeleteImage. You can delete a pipeline while a build that it started is still running. The build continues independently.

Parameter Syntax

$result = $client->deleteImagePipeline([
    'imagePipelineArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'imagePipelineArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceDependencyException:

You have attempted to mutate or delete a resource with a dependency that prohibits this action. See the error message for more details.

Examples

Example 1: Delete an image pipeline

The following example deletes an image pipeline.

$result = $client->deleteImagePipeline([
    'imagePipelineArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-pipeline/my-example-pipeline',
]);

Result syntax:

[
    'imagePipelineArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-pipeline/my-example-pipeline',
    'requestId' => '0536e4e9-5331-493a-921e-e8f86d367043',
]

DeleteImageRecipe

$result = $client->deleteImageRecipe([/* ... */]);
$promise = $client->deleteImageRecipeAsync([/* ... */]);

Deletes an image recipe.

Parameter Syntax

$result = $client->deleteImageRecipe([
    'imageRecipeArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'imageRecipeArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceDependencyException:

You have attempted to mutate or delete a resource with a dependency that prohibits this action. See the error message for more details.

Examples

Example 1: Delete an image recipe

The following example deletes the specified image recipe version.

$result = $client->deleteImageRecipe([
    'imageRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.0',
]);

Result syntax:

[
    'imageRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.0',
    'requestId' => 'a27ae6de-0adc-4cbb-9705-a4b8751857b8',
]

DeleteInfrastructureConfiguration

$result = $client->deleteInfrastructureConfiguration([/* ... */]);
$promise = $client->deleteInfrastructureConfigurationAsync([/* ... */]);

Deletes an infrastructure configuration. You can't delete a configuration that an image pipeline still references. The request fails with ResourceDependencyException. Update or delete the referencing pipelines first.

Parameter Syntax

$result = $client->deleteInfrastructureConfiguration([
    'infrastructureConfigurationArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'infrastructureConfigurationArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceDependencyException:

You have attempted to mutate or delete a resource with a dependency that prohibits this action. See the error message for more details.

Examples

Example 1: Delete an infrastructure configuration

The following example deletes the infrastructure configuration with the specified ARN.

$result = $client->deleteInfrastructureConfiguration([
    'infrastructureConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure',
]);

Result syntax:

[
    'infrastructureConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure',
    'requestId' => 'fbae57f4-59fc-48ab-a25e-c67b0d9b454c',
]

DeleteLifecyclePolicy

$result = $client->deleteLifecyclePolicy([/* ... */]);
$promise = $client->deleteLifecyclePolicyAsync([/* ... */]);

Deletes the specified lifecycle policy resource. Deleting the policy removes its schedule, so no further lifecycle runs occur for that policy. If a lifecycle execution is in progress for the policy, Image Builder cancels it. Deletion doesn't revert actions that the policy already applied to your resources.

Parameter Syntax

$result = $client->deleteLifecyclePolicy([
    'lifecyclePolicyArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'lifecyclePolicyArn' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ServiceUnavailableException:

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

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceDependencyException:

You have attempted to mutate or delete a resource with a dependency that prohibits this action. See the error message for more details.

Examples

Example 1: Delete a lifecycle policy

The following example deletes the specified lifecycle policy.

$result = $client->deleteLifecyclePolicy([
    'lifecyclePolicyArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:lifecycle-policy/my-example-lifecycle-policy',
]);

Result syntax:

[
    'lifecyclePolicyArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:lifecycle-policy/my-example-lifecycle-policy',
]

DeleteWorkflow

$result = $client->deleteWorkflow([/* ... */]);
$promise = $client->deleteWorkflowAsync([/* ... */]);

Deletes a specific workflow resource. You can't delete a workflow build version while an image pipeline references it. The request fails with ResourceDependencyException.

Parameter Syntax

$result = $client->deleteWorkflow([
    'workflowBuildVersionArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'workflowBuildVersionArn' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceDependencyException:

You have attempted to mutate or delete a resource with a dependency that prohibits this action. See the error message for more details.

Examples

Example 1: Delete a workflow build version

The following example deletes the workflow build version that the ARN specifies.

$result = $client->deleteWorkflow([
    'workflowBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.0.0/1',
]);

Result syntax:

[
    'workflowBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.0.0/1',
]

DistributeImage

$result = $client->distributeImage([/* ... */]);
$promise = $client->distributeImageAsync([/* ... */]);

Distributes an existing AMI to target Regions and accounts without running the full image build process. This operation only runs the distribution phase on an image that has already been built.

Parameter Syntax

$result = $client->distributeImage([
    'clientToken' => '<string>', // REQUIRED
    'distributionConfigurationArn' => '<string>', // REQUIRED
    'executionRole' => '<string>', // REQUIRED
    'loggingConfiguration' => [
        'logGroupName' => '<string>',
    ],
    'sourceImage' => '<string>', // REQUIRED
    'tags' => ['<string>', ...],
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'imageBuildVersionArn' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

ServiceQuotaExceededException:

You have exceeded the number of permitted resources or operations for this service. For service quotas, see EC2 Image Builder endpoints and quotas.

AccessDeniedException:

You do not have permissions to perform the requested operation.

TooManyRequestsException:

You have attempted too many requests for the specific operation.

ResourceNotFoundException:

At least one of the resources referenced by your request does not exist.

Examples

Example 1: Distribute an existing AMI

The following example distributes an AMI that you own to the targets defined in the specified distribution configuration. It returns the ARN of a new Image Builder image resource that you can use with GetImage to monitor distribution progress.

$result = $client->distributeImage([
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE86420',
    'distributionConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:distribution-configuration/my-example-distribution-configuration',
    'executionRole' => 'arn:aws:iam::111122223333:role/aws-service-role/imagebuilder.amazonaws.com/AWSServiceRoleForImageBuilder',
    'sourceImage' => 'ami-1234567890abcdef0',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE86420',
    'imageBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-source-ami/1.0.0/1',
]

GetComponent

$result = $client->getComponent([/* ... */]);
$promise = $client->getComponentAsync([/* ... */]);

Retrieves a component object.

Parameter Syntax

$result = $client->getComponent([
    'componentBuildVersionArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'component' => [
        'arn' => '<string>',
        'changeDescription' => '<string>',
        'data' => '<string>',
        'dateCreated' => '<string>',
        'description' => '<string>',
        'encrypted' => true || false,
        'kmsKeyId' => '<string>',
        'name' => '<string>',
        'obfuscate' => true || false,
        'owner' => '<string>',
        'parameters' => [
            [
                'defaultValue' => ['<string>', ...],
                'description' => '<string>',
                'name' => '<string>',
                'type' => '<string>',
            ],
            // ...
        ],
        'platform' => 'Windows|Linux|macOS',
        'productCodes' => [
            [
                'productCodeId' => '<string>',
                'productCodeType' => 'marketplace',
            ],
            // ...
        ],
        'publisher' => '<string>',
        'state' => [
            'reason' => '<string>',
            'status' => 'DEPRECATED|DISABLED|ACTIVE',
        ],
        'supportedOsVersions' => ['<string>', ...],
        'tags' => ['<string>', ...],
        'type' => 'BUILD|TEST',
        'version' => '<string>',
    ],
    'latestVersionReferences' => [
        'latestMajorVersionArn' => '<string>',
        'latestMinorVersionArn' => '<string>',
        'latestPatchVersionArn' => '<string>',
        'latestVersionArn' => '<string>',
    ],
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the details of a component build version

The following example retrieves a component build version. The data field in the response contains the YAML document that defines the component.

$result = $client->getComponent([
    'componentBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0/1',
]);

Result syntax:

[
    'component' => [
        'version' => '1.0.0',
        'name' => 'my-example-component',
        'type' => 'BUILD',
        'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0/1',
        'changeDescription' => 'Initial version',
        'data' => 'name: InstallMyAppdescription: Installs my applicationschemaVersion: 1.0phases: - name: build steps: - name: InstallApp action: ExecuteBash inputs: commands: - sudo yum -y install my-app',
        'dateCreated' => '2026-09-09T18:31:30.404Z',
        'description' => 'Installs the latest version of my application',
        'encrypted' => 1,
        'owner' => '111122223333',
        'platform' => 'Linux',
        'state' => [
            'status' => 'ACTIVE',
        ],
    ],
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/x.x.x',
    ],
    'requestId' => 'f5401098-035f-4be2-9eee-784c388ed04b',
]

GetComponentPolicy

$result = $client->getComponentPolicy([/* ... */]);
$promise = $client->getComponentPolicyAsync([/* ... */]);

Retrieves a component policy.

Parameter Syntax

$result = $client->getComponentPolicy([
    'componentArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'policy' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ServiceUnavailableException:

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

ResourceNotFoundException:

At least one of the resources referenced by your request does not exist.

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the resource policy for a component

The following example retrieves the resource policy that's applied to a component that the owner shared with another account.

$result = $client->getComponentPolicy([
    'componentArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-shared-component/1.0.0/1',
]);

Result syntax:

[
    'policy' => '{"Version": "2012-10-17", "Statement": [{"Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::444455556666:root"}, "Action": ["imagebuilder:GetComponent", "imagebuilder:ListComponents"], "Resource": ["arn:aws:imagebuilder:us-west-2:111122223333:component/my-shared-component/1.0.0/1"]}]}',
    'requestId' => 'cb458998-6e6f-442a-9325-78c730b80895',
]

GetContainerRecipe

$result = $client->getContainerRecipe([/* ... */]);
$promise = $client->getContainerRecipeAsync([/* ... */]);

Retrieves a container recipe.

Parameter Syntax

$result = $client->getContainerRecipe([
    'containerRecipeArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'containerRecipe' => [
        'arn' => '<string>',
        'components' => [
            [
                'componentArn' => '<string>',
                'parameters' => [
                    [
                        'name' => '<string>',
                        'value' => ['<string>', ...],
                    ],
                    // ...
                ],
            ],
            // ...
        ],
        'containerType' => 'DOCKER',
        'dateCreated' => '<string>',
        'description' => '<string>',
        'dockerfileTemplateData' => '<string>',
        'encrypted' => true || false,
        'instanceConfiguration' => [
            'blockDeviceMappings' => [
                [
                    'deviceName' => '<string>',
                    'ebs' => [
                        'deleteOnTermination' => true || false,
                        'encrypted' => true || false,
                        'iops' => <integer>,
                        'kmsKeyId' => '<string>',
                        'snapshotId' => '<string>',
                        'throughput' => <integer>,
                        'volumeSize' => <integer>,
                        'volumeType' => 'standard|io1|io2|gp2|gp3|sc1|st1',
                    ],
                    'noDevice' => '<string>',
                    'virtualName' => '<string>',
                ],
                // ...
            ],
            'image' => '<string>',
        ],
        'kmsKeyId' => '<string>',
        'name' => '<string>',
        'owner' => '<string>',
        'parentImage' => '<string>',
        'platform' => 'Windows|Linux|macOS',
        'tags' => ['<string>', ...],
        'targetRepository' => [
            'repositoryName' => '<string>',
            'service' => 'ECR',
        ],
        'version' => '<string>',
        'workingDirectory' => '<string>',
    ],
    'latestVersionReferences' => [
        'latestMajorVersionArn' => '<string>',
        'latestMinorVersionArn' => '<string>',
        'latestPatchVersionArn' => '<string>',
        'latestVersionArn' => '<string>',
    ],
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the details of a container recipe

The following example retrieves the details of the specified container recipe.

$result = $client->getContainerRecipe([
    'containerRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.0.0',
]);

Result syntax:

[
    'containerRecipe' => [
        'version' => '1.0.0',
        'name' => 'my-example-container-recipe',
        'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.0.0',
        'components' => [
            [
                'componentArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-container-component/1.0.0/1',
            ],
        ],
        'containerType' => 'DOCKER',
        'dateCreated' => '2026-09-09T19:32:53.983Z',
        'description' => 'A container recipe that installs my application on Amazon Linux',
        'dockerfileTemplateData' => 'FROM {{{ imagebuilder:parentImage }}}{{{ imagebuilder:environments }}}{{{ imagebuilder:components }}}',
        'encrypted' => 1,
        'owner' => '111122223333',
        'parentImage' => 'amazonlinux:latest',
        'platform' => 'Linux',
        'targetRepository' => [
            'repositoryName' => 'my-example-container-repo',
            'service' => 'ECR',
        ],
    ],
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.0.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/1.0.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe/x.x.x',
    ],
    'requestId' => '15b03ca7-050f-46d4-945e-00232cff6b19',
]

GetContainerRecipePolicy

$result = $client->getContainerRecipePolicy([/* ... */]);
$promise = $client->getContainerRecipePolicyAsync([/* ... */]);

Retrieves the policy for a container recipe.

Parameter Syntax

$result = $client->getContainerRecipePolicy([
    'containerRecipeArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'policy' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ResourceNotFoundException:

At least one of the resources referenced by your request does not exist.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the policy attached to a container recipe

The following example retrieves the resource policy for a container recipe that you shared with another AWS account. The policy property contains the resource-based policy document as a JSON-encoded string.

$result = $client->getContainerRecipePolicy([
    'containerRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe-shared/1.0.0',
]);

Result syntax:

[
    'policy' => '{"Version": "2012-10-17", "Statement": [{"Sid": "AllowSharedAccountContainerRecipeAccess", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::444455556666:root"}, "Action": ["imagebuilder:GetContainerRecipe", "imagebuilder:ListContainerRecipes"], "Resource": "arn:aws:imagebuilder:us-west-2:111122223333:container-recipe/my-example-container-recipe-shared/1.0.0"}]}',
    'requestId' => '1b8334a0-5ae7-4c3c-8092-5d589dab7a2b',
]

GetDistributionConfiguration

$result = $client->getDistributionConfiguration([/* ... */]);
$promise = $client->getDistributionConfigurationAsync([/* ... */]);

Retrieves a distribution configuration.

Parameter Syntax

$result = $client->getDistributionConfiguration([
    'distributionConfigurationArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'distributionConfiguration' => [
        'arn' => '<string>',
        'dateCreated' => '<string>',
        'dateUpdated' => '<string>',
        'description' => '<string>',
        'distributions' => [
            [
                'amiDistributionConfiguration' => [
                    'amiTags' => ['<string>', ...],
                    'description' => '<string>',
                    'kmsKeyId' => '<string>',
                    'launchPermission' => [
                        'organizationArns' => ['<string>', ...],
                        'organizationalUnitArns' => ['<string>', ...],
                        'userGroups' => ['<string>', ...],
                        'userIds' => ['<string>', ...],
                    ],
                    'name' => '<string>',
                    'targetAccountIds' => ['<string>', ...],
                ],
                'containerDistributionConfiguration' => [
                    'containerTags' => ['<string>', ...],
                    'description' => '<string>',
                    'targetRepository' => [
                        'repositoryName' => '<string>',
                        'service' => 'ECR',
                    ],
                ],
                'fastLaunchConfigurations' => [
                    [
                        'accountId' => '<string>',
                        'enabled' => true || false,
                        'launchTemplate' => [
                            'launchTemplateId' => '<string>',
                            'launchTemplateName' => '<string>',
                            'launchTemplateVersion' => '<string>',
                        ],
                        'maxParallelLaunches' => <integer>,
                        'snapshotConfiguration' => [
                            'targetResourceCount' => <integer>,
                        ],
                    ],
                    // ...
                ],
                'launchTemplateConfigurations' => [
                    [
                        'accountId' => '<string>',
                        'launchTemplateId' => '<string>',
                        'setDefaultVersion' => true || false,
                    ],
                    // ...
                ],
                'licenseConfigurationArns' => ['<string>', ...],
                'region' => '<string>',
                's3ExportConfiguration' => [
                    'diskImageFormat' => 'VMDK|RAW|VHD',
                    'roleName' => '<string>',
                    's3Bucket' => '<string>',
                    's3Prefix' => '<string>',
                ],
                'ssmParameterConfigurations' => [
                    [
                        'amiAccountId' => '<string>',
                        'dataType' => 'text|aws:ec2:image',
                        'parameterName' => '<string>',
                    ],
                    // ...
                ],
            ],
            // ...
        ],
        'name' => '<string>',
        'tags' => ['<string>', ...],
        'timeoutMinutes' => <integer>,
    ],
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the details of a distribution configuration

The following example retrieves a distribution configuration that distributes the output AMI to two Regions.

$result = $client->getDistributionConfiguration([
    'distributionConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:distribution-configuration/my-example-distribution',
]);

Result syntax:

[
    'distributionConfiguration' => [
        'name' => 'my-example-distribution',
        'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:distribution-configuration/my-example-distribution',
        'dateCreated' => '2026-09-09T19:37:37.231Z',
        'description' => 'Copies the output AMI to a second Region',
        'distributions' => [
            [
                'amiDistributionConfiguration' => [
                    'name' => 'my-example-image-{{ imagebuilder:buildDate }}',
                ],
                'region' => 'us-west-2',
            ],
            [
                'amiDistributionConfiguration' => [
                    'name' => 'my-example-image-{{ imagebuilder:buildDate }}',
                ],
                'region' => 'us-east-1',
            ],
        ],
        'timeoutMinutes' => 720,
    ],
    'requestId' => '2d0a8dc0-99d5-4d7a-af7a-d1aeafd71c2e',
]

GetImage

$result = $client->getImage([/* ... */]);
$promise = $client->getImageAsync([/* ... */]);

Retrieves an image.

Parameter Syntax

$result = $client->getImage([
    'imageBuildVersionArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'image' => [
        'arn' => '<string>',
        'buildType' => 'USER_INITIATED|SCHEDULED|IMPORT|IMPORT_ISO',
        'containerRecipe' => [
            'arn' => '<string>',
            'components' => [
                [
                    'componentArn' => '<string>',
                    'parameters' => [
                        [
                            'name' => '<string>',
                            'value' => ['<string>', ...],
                        ],
                        // ...
                    ],
                ],
                // ...
            ],
            'containerType' => 'DOCKER',
            'dateCreated' => '<string>',
            'description' => '<string>',
            'dockerfileTemplateData' => '<string>',
            'encrypted' => true || false,
            'instanceConfiguration' => [
                'blockDeviceMappings' => [
                    [
                        'deviceName' => '<string>',
                        'ebs' => [
                            'deleteOnTermination' => true || false,
                            'encrypted' => true || false,
                            'iops' => <integer>,
                            'kmsKeyId' => '<string>',
                            'snapshotId' => '<string>',
                            'throughput' => <integer>,
                            'volumeSize' => <integer>,
                            'volumeType' => 'standard|io1|io2|gp2|gp3|sc1|st1',
                        ],
                        'noDevice' => '<string>',
                        'virtualName' => '<string>',
                    ],
                    // ...
                ],
                'image' => '<string>',
            ],
            'kmsKeyId' => '<string>',
            'name' => '<string>',
            'owner' => '<string>',
            'parentImage' => '<string>',
            'platform' => 'Windows|Linux|macOS',
            'tags' => ['<string>', ...],
            'targetRepository' => [
                'repositoryName' => '<string>',
                'service' => 'ECR',
            ],
            'version' => '<string>',
            'workingDirectory' => '<string>',
        ],
        'dateCreated' => '<string>',
        'deprecationTime' => <DateTime>,
        'distributionConfiguration' => [
            'arn' => '<string>',
            'dateCreated' => '<string>',
            'dateUpdated' => '<string>',
            'description' => '<string>',
            'distributions' => [
                [
                    'amiDistributionConfiguration' => [
                        'amiTags' => ['<string>', ...],
                        'description' => '<string>',
                        'kmsKeyId' => '<string>',
                        'launchPermission' => [
                            'organizationArns' => ['<string>', ...],
                            'organizationalUnitArns' => ['<string>', ...],
                            'userGroups' => ['<string>', ...],
                            'userIds' => ['<string>', ...],
                        ],
                        'name' => '<string>',
                        'targetAccountIds' => ['<string>', ...],
                    ],
                    'containerDistributionConfiguration' => [
                        'containerTags' => ['<string>', ...],
                        'description' => '<string>',
                        'targetRepository' => [
                            'repositoryName' => '<string>',
                            'service' => 'ECR',
                        ],
                    ],
                    'fastLaunchConfigurations' => [
                        [
                            'accountId' => '<string>',
                            'enabled' => true || false,
                            'launchTemplate' => [
                                'launchTemplateId' => '<string>',
                                'launchTemplateName' => '<string>',
                                'launchTemplateVersion' => '<string>',
                            ],
                            'maxParallelLaunches' => <integer>,
                            'snapshotConfiguration' => [
                                'targetResourceCount' => <integer>,
                            ],
                        ],
                        // ...
                    ],
                    'launchTemplateConfigurations' => [
                        [
                            'accountId' => '<string>',
                            'launchTemplateId' => '<string>',
                            'setDefaultVersion' => true || false,
                        ],
                        // ...
                    ],
                    'licenseConfigurationArns' => ['<string>', ...],
                    'region' => '<string>',
                    's3ExportConfiguration' => [
                        'diskImageFormat' => 'VMDK|RAW|VHD',
                        'roleName' => '<string>',
                        's3Bucket' => '<string>',
                        's3Prefix' => '<string>',
                    ],
                    'ssmParameterConfigurations' => [
                        [
                            'amiAccountId' => '<string>',
                            'dataType' => 'text|aws:ec2:image',
                            'parameterName' => '<string>',
                        ],
                        // ...
                    ],
                ],
                // ...
            ],
            'name' => '<string>',
            'tags' => ['<string>', ...],
            'timeoutMinutes' => <integer>,
        ],
        'enhancedImageMetadataEnabled' => true || false,
        'executionRole' => '<string>',
        'imageRecipe' => [
            'additionalInstanceConfiguration' => [
                'systemsManagerAgent' => [
                    'uninstallAfterBuild' => true || false,
                ],
                'userDataOverride' => '<string>',
            ],
            'amiTags' => ['<string>', ...],
            'amiWatermarks' => ['<string>', ...],
            'arn' => '<string>',
            'blockDeviceMappings' => [
                [
                    'deviceName' => '<string>',
                    'ebs' => [
                        'deleteOnTermination' => true || false,
                        'encrypted' => true || false,
                        'iops' => <integer>,
                        'kmsKeyId' => '<string>',
                        'snapshotId' => '<string>',
                        'throughput' => <integer>,
                        'volumeSize' => <integer>,
                        'volumeType' => 'standard|io1|io2|gp2|gp3|sc1|st1',
                    ],
                    'noDevice' => '<string>',
                    'virtualName' => '<string>',
                ],
                // ...
            ],
            'components' => [
                [
                    'componentArn' => '<string>',
                    'parameters' => [
                        [
                            'name' => '<string>',
                            'value' => ['<string>', ...],
                        ],
                        // ...
                    ],
                ],
                // ...
            ],
            'dateCreated' => '<string>',
            'description' => '<string>',
            'name' => '<string>',
            'owner' => '<string>',
            'parentImage' => '<string>',
            'platform' => 'Windows|Linux|macOS',
            'tags' => ['<string>', ...],
            'type' => 'AMI|DOCKER',
            'version' => '<string>',
            'workingDirectory' => '<string>',
        ],
        'imageScanningConfiguration' => [
            'ecrConfiguration' => [
                'containerTags' => ['<string>', ...],
                'repositoryName' => '<string>',
            ],
            'imageScanningEnabled' => true || false,
        ],
        'imageSource' => 'AMAZON_MANAGED|AWS_MARKETPLACE|IMPORTED|CUSTOM',
        'imageTestsConfiguration' => [
            'imageTestsEnabled' => true || false,
            'timeoutMinutes' => <integer>,
        ],
        'infrastructureConfiguration' => [
            'arn' => '<string>',
            'dateCreated' => '<string>',
            'dateUpdated' => '<string>',
            'description' => '<string>',
            'instanceMetadataOptions' => [
                'httpPutResponseHopLimit' => <integer>,
                'httpTokens' => '<string>',
            ],
            'instanceProfileName' => '<string>',
            'instanceTypes' => ['<string>', ...],
            'keyPair' => '<string>',
            'logging' => [
                's3Logs' => [
                    's3BucketName' => '<string>',
                    's3KeyPrefix' => '<string>',
                ],
            ],
            'name' => '<string>',
            'placement' => [
                'availabilityZone' => '<string>',
                'hostId' => '<string>',
                'hostResourceGroupArn' => '<string>',
                'tenancy' => 'default|dedicated|host',
            ],
            'resourceTags' => ['<string>', ...],
            'securityGroupIds' => ['<string>', ...],
            'snsTopicArn' => '<string>',
            'subnetId' => '<string>',
            'tags' => ['<string>', ...],
            'terminateInstanceOnFailure' => true || false,
        ],
        'lifecycleExecutionId' => '<string>',
        'loggingConfiguration' => [
            'logGroupName' => '<string>',
        ],
        'name' => '<string>',
        'osVersion' => '<string>',
        'outputResources' => [
            'amis' => [
                [
                    'accountId' => '<string>',
                    'description' => '<string>',
                    'image' => '<string>',
                    'name' => '<string>',
                    'region' => '<string>',
                    'state' => [
                        'failureContext' => [
                            'componentFailure' => [
                                'action' => '<string>',
                                'componentArn' => '<string>',
                                'errorMessage' => '<string>',
                                'phaseName' => '<string>',
                                'stepName' => '<string>',
                            ],
                            'distributionFailure' => [
                                'errorMessage' => '<string>',
                                'regionFailures' => [
                                    [
                                        'errorMessage' => '<string>',
                                        'imageConfigurationStep' => 'ASSOCIATE_LICENSES|UPDATE_LAUNCH_TEMPLATES|PUT_SSM_PARAMETERS|UPDATE_FAST_LAUNCH_CONFIGURATIONS|EXPORT_AMI',
                                        'region' => '<string>',
                                        'status' => 'FAILED|CANCELLED|TIMED_OUT',
                                        'targetAccountId' => '<string>',
                                    ],
                                    // ...
                                ],
                            ],
                            'failedStep' => '<string>',
                            'imageStatus' => 'PENDING|CREATING|BUILDING|TESTING|DISTRIBUTING|INTEGRATING|AVAILABLE|CANCELLED|FAILED|DEPRECATED|DELETED|DISABLED',
                            'stepExecutionId' => '<string>',
                            'workflowArn' => '<string>',
                            'workflowExecutionId' => '<string>',
                        ],
                        'reason' => '<string>',
                        'status' => 'PENDING|CREATING|BUILDING|TESTING|DISTRIBUTING|INTEGRATING|AVAILABLE|CANCELLED|FAILED|DEPRECATED|DELETED|DISABLED',
                    ],
                ],
                // ...
            ],
            'containers' => [
                [
                    'imageUris' => ['<string>', ...],
                    'region' => '<string>',
                ],
                // ...
            ],
        ],
        'platform' => 'Windows|Linux|macOS',
        'scanState' => [
            'reason' => '<string>',
            'status' => 'PENDING|SCANNING|COLLECTING|COMPLETED|ABANDONED|FAILED|TIMED_OUT',
        ],
        'sourcePipelineArn' => '<string>',
        'sourcePipelineName' => '<string>',
        'state' => [
            'failureContext' => [
                'componentFailure' => [
                    'action' => '<string>',
                    'componentArn' => '<string>',
                    'errorMessage' => '<string>',
                    'phaseName' => '<string>',
                    'stepName' => '<string>',
                ],
                'distributionFailure' => [
                    'errorMessage' => '<string>',
                    'regionFailures' => [
                        [
                            'errorMessage' => '<string>',
                            'imageConfigurationStep' => 'ASSOCIATE_LICENSES|UPDATE_LAUNCH_TEMPLATES|PUT_SSM_PARAMETERS|UPDATE_FAST_LAUNCH_CONFIGURATIONS|EXPORT_AMI',
                            'region' => '<string>',
                            'status' => 'FAILED|CANCELLED|TIMED_OUT',
                            'targetAccountId' => '<string>',
                        ],
                        // ...
                    ],
                ],
                'failedStep' => '<string>',
                'imageStatus' => 'PENDING|CREATING|BUILDING|TESTING|DISTRIBUTING|INTEGRATING|AVAILABLE|CANCELLED|FAILED|DEPRECATED|DELETED|DISABLED',
                'stepExecutionId' => '<string>',
                'workflowArn' => '<string>',
                'workflowExecutionId' => '<string>',
            ],
            'reason' => '<string>',
            'status' => 'PENDING|CREATING|BUILDING|TESTING|DISTRIBUTING|INTEGRATING|AVAILABLE|CANCELLED|FAILED|DEPRECATED|DELETED|DISABLED',
        ],
        'tags' => ['<string>', ...],
        'type' => 'AMI|DOCKER',
        'version' => '<string>',
        'workflows' => [
            [
                'onFailure' => 'CONTINUE|ABORT',
                'parallelGroup' => '<string>',
                'parameters' => [
                    [
                        'name' => '<string>',
                        'value' => ['<string>', ...],
                    ],
                    // ...
                ],
                'workflowArn' => '<string>',
            ],
            // ...
        ],
    ],
    'latestVersionReferences' => [
        'latestMajorVersionArn' => '<string>',
        'latestMinorVersionArn' => '<string>',
        'latestPatchVersionArn' => '<string>',
        'latestVersionArn' => '<string>',
    ],
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Check the status of an image build

The following example retrieves an image build version to check its status while the build is running. The response is shortened to show a subset of the fields that Image Builder returns.

$result = $client->getImage([
    'imageBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0/1',
]);

Result syntax:

[
    'image' => [
        'version' => '1.0.0/1',
        'name' => 'my-example-recipe',
        'type' => 'AMI',
        'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0/1',
        'dateCreated' => '2026-09-03T05:44:21.121Z',
        'enhancedImageMetadataEnabled' => 1,
        'platform' => 'Linux',
        'sourcePipelineArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-pipeline/my-example-pipeline',
        'state' => [
            'status' => 'BUILDING',
        ],
    ],
    'requestId' => '4be892f0-e1d1-47f9-8bc1-d08ec5dec640',
]

GetImagePipeline

$result = $client->getImagePipeline([/* ... */]);
$promise = $client->getImagePipelineAsync([/* ... */]);

Retrieves an image pipeline.

Parameter Syntax

$result = $client->getImagePipeline([
    'imagePipelineArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'imagePipeline' => [
        'arn' => '<string>',
        'consecutiveFailures' => <integer>,
        'containerRecipeArn' => '<string>',
        'dateCreated' => '<string>',
        'dateLastRun' => '<string>',
        'dateNextRun' => '<string>',
        'dateUpdated' => '<string>',
        'description' => '<string>',
        'distributionConfigurationArn' => '<string>',
        'enhancedImageMetadataEnabled' => true || false,
        'executionRole' => '<string>',
        'imageRecipeArn' => '<string>',
        'imageScanningConfiguration' => [
            'ecrConfiguration' => [
                'containerTags' => ['<string>', ...],
                'repositoryName' => '<string>',
            ],
            'imageScanningEnabled' => true || false,
        ],
        'imageTags' => ['<string>', ...],
        'imageTestsConfiguration' => [
            'imageTestsEnabled' => true || false,
            'timeoutMinutes' => <integer>,
        ],
        'infrastructureConfigurationArn' => '<string>',
        'lastRunStatus' => 'PENDING|CREATING|BUILDING|TESTING|DISTRIBUTING|INTEGRATING|AVAILABLE|CANCELLED|FAILED|DEPRECATED|DELETED|DISABLED',
        'loggingConfiguration' => [
            'imageLogGroupName' => '<string>',
            'pipelineLogGroupName' => '<string>',
        ],
        'name' => '<string>',
        'platform' => 'Windows|Linux|macOS',
        'schedule' => [
            'autoDisablePolicy' => [
                'failureCount' => <integer>,
            ],
            'pipelineExecutionStartCondition' => 'EXPRESSION_MATCH_ONLY|EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE',
            'scheduleExpression' => '<string>',
            'timezone' => '<string>',
        ],
        'status' => 'DISABLED|ENABLED',
        'tags' => ['<string>', ...],
        'workflows' => [
            [
                'onFailure' => 'CONTINUE|ABORT',
                'parallelGroup' => '<string>',
                'parameters' => [
                    [
                        'name' => '<string>',
                        'value' => ['<string>', ...],
                    ],
                    // ...
                ],
                'workflowArn' => '<string>',
            ],
            // ...
        ],
    ],
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the details of an image pipeline

The following example retrieves an image pipeline that builds a new image every Sunday, including the image tests configuration and schedule start condition defaults that Image Builder applied at creation.

$result = $client->getImagePipeline([
    'imagePipelineArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-pipeline/my-example-pipeline',
]);

Result syntax:

[
    'imagePipeline' => [
        'name' => 'my-example-pipeline',
        'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-pipeline/my-example-pipeline',
        'dateCreated' => '2026-09-09T19:38:26.574Z',
        'dateUpdated' => '2026-09-09T19:38:26.574Z',
        'description' => 'Builds an Amazon Linux 2023 image every Sunday',
        'enhancedImageMetadataEnabled' => 1,
        'imageRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.0',
        'imageTestsConfiguration' => [
            'imageTestsEnabled' => 1,
            'timeoutMinutes' => 720,
        ],
        'infrastructureConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure',
        'platform' => 'Linux',
        'schedule' => [
            'pipelineExecutionStartCondition' => 'EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE',
            'scheduleExpression' => 'cron(0 0 ? * SUN *)',
        ],
        'status' => 'ENABLED',
    ],
    'requestId' => 'b7e58d62-36dc-43a5-87ff-546e04cdabf1',
]

GetImagePolicy

$result = $client->getImagePolicy([/* ... */]);
$promise = $client->getImagePolicyAsync([/* ... */]);

Retrieves an image policy.

Parameter Syntax

$result = $client->getImagePolicy([
    'imageArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'policy' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ServiceUnavailableException:

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

ResourceNotFoundException:

At least one of the resources referenced by your request does not exist.

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Retrieve the resource policy for an image

The following example retrieves the resource policy for an image build version that was shared with account 444455556666.

$result = $client->getImagePolicy([
    'imageArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0/1',
]);

Result syntax:

[
    'policy' => '{"Version": "2012-10-17", "Statement": [{"Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::444455556666:root"}, "Action": ["imagebuilder:GetImage", "imagebuilder:ListImages"], "Resource": ["arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0/1"]}]}',
    'requestId' => 'bc0c8348-c0d9-452a-af20-2640430df585',
]

GetImageRecipe

$result = $client->getImageRecipe([/* ... */]);
$promise = $client->getImageRecipeAsync([/* ... */]);

Retrieves an image recipe.

Parameter Syntax

$result = $client->getImageRecipe([
    'imageRecipeArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'imageRecipe' => [
        'additionalInstanceConfiguration' => [
            'systemsManagerAgent' => [
                'uninstallAfterBuild' => true || false,
            ],
            'userDataOverride' => '<string>',
        ],
        'amiTags' => ['<string>', ...],
        'amiWatermarks' => ['<string>', ...],
        'arn' => '<string>',
        'blockDeviceMappings' => [
            [
                'deviceName' => '<string>',
                'ebs' => [
                    'deleteOnTermination' => true || false,
                    'encrypted' => true || false,
                    'iops' => <integer>,
                    'kmsKeyId' => '<string>',
                    'snapshotId' => '<string>',
                    'throughput' => <integer>,
                    'volumeSize' => <integer>,
                    'volumeType' => 'standard|io1|io2|gp2|gp3|sc1|st1',
                ],
                'noDevice' => '<string>',
                'virtualName' => '<string>',
            ],
            // ...
        ],
        'components' => [
            [
                'componentArn' => '<string>',
                'parameters' => [
                    [
                        'name' => '<string>',
                        'value' => ['<string>', ...],
                    ],
                    // ...
                ],
            ],
            // ...
        ],
        'dateCreated' => '<string>',
        'description' => '<string>',
        'name' => '<string>',
        'owner' => '<string>',
        'parentImage' => '<string>',
        'platform' => 'Windows|Linux|macOS',
        'tags' => ['<string>', ...],
        'type' => 'AMI|DOCKER',
        'version' => '<string>',
        'workingDirectory' => '<string>',
    ],
    'latestVersionReferences' => [
        'latestMajorVersionArn' => '<string>',
        'latestMinorVersionArn' => '<string>',
        'latestPatchVersionArn' => '<string>',
        'latestVersionArn' => '<string>',
    ],
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the details of an image recipe

The following example retrieves the full definition of an image recipe, including the components it applies and the base image it builds on.

$result = $client->getImageRecipe([
    'imageRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-app-recipe/1.0.0',
]);

Result syntax:

[
    'imageRecipe' => [
        'version' => '1.0.0',
        'name' => 'my-example-app-recipe',
        'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-app-recipe/1.0.0',
        'components' => [
            [
                'componentArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-app/1.0.0/1',
            ],
        ],
        'dateCreated' => '2026-09-09T19:30:21.183Z',
        'description' => 'An image recipe that installs my application on Amazon Linux 2023',
        'owner' => '111122223333',
        'parentImage' => 'arn:aws:imagebuilder:us-west-2:aws:image/amazon-linux-2023-x86/x.x.x',
        'platform' => 'Linux',
        'workingDirectory' => '/tmp',
    ],
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-app-recipe/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-app-recipe/1.0.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-app-recipe/1.0.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-app-recipe/x.x.x',
    ],
    'requestId' => 'adb3ff9a-df84-4b4e-8ecf-11d38281ead7',
]

GetImageRecipePolicy

$result = $client->getImageRecipePolicy([/* ... */]);
$promise = $client->getImageRecipePolicyAsync([/* ... */]);

Retrieves an image recipe policy.

Parameter Syntax

$result = $client->getImageRecipePolicy([
    'imageRecipeArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'policy' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ResourceNotFoundException:

At least one of the resources referenced by your request does not exist.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the resource policy for an image recipe

The following example retrieves the resource policy that's applied to the specified image recipe.

$result = $client->getImageRecipePolicy([
    'imageRecipeArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.0',
]);

Result syntax:

[
    'policy' => '{"Version": "2012-10-17", "Statement": [{"Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::444455556666:root"}, "Action": ["imagebuilder:GetImageRecipe", "imagebuilder:ListImageRecipes"], "Resource": "arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.0"}]}',
    'requestId' => '0cf42efc-4b2c-4ba3-b6e3-542a796fffaf',
]

GetInfrastructureConfiguration

$result = $client->getInfrastructureConfiguration([/* ... */]);
$promise = $client->getInfrastructureConfigurationAsync([/* ... */]);

Retrieves an infrastructure configuration.

Parameter Syntax

$result = $client->getInfrastructureConfiguration([
    'infrastructureConfigurationArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'infrastructureConfiguration' => [
        'arn' => '<string>',
        'dateCreated' => '<string>',
        'dateUpdated' => '<string>',
        'description' => '<string>',
        'instanceMetadataOptions' => [
            'httpPutResponseHopLimit' => <integer>,
            'httpTokens' => '<string>',
        ],
        'instanceProfileName' => '<string>',
        'instanceTypes' => ['<string>', ...],
        'keyPair' => '<string>',
        'logging' => [
            's3Logs' => [
                's3BucketName' => '<string>',
                's3KeyPrefix' => '<string>',
            ],
        ],
        'name' => '<string>',
        'placement' => [
            'availabilityZone' => '<string>',
            'hostId' => '<string>',
            'hostResourceGroupArn' => '<string>',
            'tenancy' => 'default|dedicated|host',
        ],
        'resourceTags' => ['<string>', ...],
        'securityGroupIds' => ['<string>', ...],
        'snsTopicArn' => '<string>',
        'subnetId' => '<string>',
        'tags' => ['<string>', ...],
        'terminateInstanceOnFailure' => true || false,
    ],
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the details of an infrastructure configuration

The following example retrieves an infrastructure configuration that specifies the instance types, instance profile, and instance metadata options that Image Builder uses for build and test instances.

$result = $client->getInfrastructureConfiguration([
    'infrastructureConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure-configuration',
]);

Result syntax:

[
    'infrastructureConfiguration' => [
        'name' => 'my-example-infrastructure-configuration',
        'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure-configuration',
        'dateCreated' => '2026-09-09T19:36:48.933Z',
        'description' => 'Infrastructure configuration for my application image builds',
        'instanceMetadataOptions' => [
            'httpPutResponseHopLimit' => 2,
            'httpTokens' => 'required',
        ],
        'instanceProfileName' => 'EC2InstanceProfileForImageBuilder',
        'instanceTypes' => [
            'm5.large',
            'm5.xlarge',
        ],
        'resourceTags' => [
            'CostCenter' => '12345',
        ],
        'tags' => [
            'Environment' => 'test',
        ],
        'terminateInstanceOnFailure' => 1,
    ],
    'requestId' => '7ba25cd0-0735-4f44-bc67-2f231e96503f',
]

GetLifecycleExecution

$result = $client->getLifecycleExecution([/* ... */]);
$promise = $client->getLifecycleExecutionAsync([/* ... */]);

Retrieves runtime information for a lifecycle execution – a single run of lifecycle actions that a lifecycle policy or a StartResourceStateUpdate request started.

Parameter Syntax

$result = $client->getLifecycleExecution([
    'lifecycleExecutionId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'lifecycleExecution' => [
        'endTime' => <DateTime>,
        'lifecycleExecutionId' => '<string>',
        'lifecyclePolicyArn' => '<string>',
        'resourcesImpactedSummary' => [
            'hasImpactedResources' => true || false,
        ],
        'startTime' => <DateTime>,
        'state' => [
            'reason' => '<string>',
            'status' => 'IN_PROGRESS|CANCELLED|CANCELLING|FAILED|SUCCESS|PENDING',
        ],
    ],
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the details of a lifecycle execution

The following example retrieves the runtime status of the specified lifecycle execution. If the execution was started by StartResourceStateUpdate rather than a lifecycle policy run, the response doesn't include the lifecyclePolicyArn field.

$result = $client->getLifecycleExecution([
    'lifecycleExecutionId' => 'lce-401aefc3-a829-46f6-8fc2-91497988a503',
]);

Result syntax:

[
    'lifecycleExecution' => [
        'lifecycleExecutionId' => 'lce-401aefc3-a829-46f6-8fc2-91497988a503',
        'resourcesImpactedSummary' => [
            'hasImpactedResources' => ,
        ],
        'startTime' => ,
        'state' => [
            'status' => 'IN_PROGRESS',
        ],
    ],
]

GetLifecyclePolicy

$result = $client->getLifecyclePolicy([/* ... */]);
$promise = $client->getLifecyclePolicyAsync([/* ... */]);

Retrieves details for the specified image lifecycle policy.

Parameter Syntax

$result = $client->getLifecyclePolicy([
    'lifecyclePolicyArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'lifecyclePolicy' => [
        'arn' => '<string>',
        'dateCreated' => <DateTime>,
        'dateLastRun' => <DateTime>,
        'dateUpdated' => <DateTime>,
        'description' => '<string>',
        'executionRole' => '<string>',
        'name' => '<string>',
        'policyDetails' => [
            [
                'action' => [
                    'includeResources' => [
                        'amis' => true || false,
                        'containers' => true || false,
                        'snapshots' => true || false,
                    ],
                    'type' => 'DELETE|DEPRECATE|DISABLE',
                ],
                'exclusionRules' => [
                    'amis' => [
                        'isPublic' => true || false,
                        'lastLaunched' => [
                            'unit' => 'DAYS|WEEKS|MONTHS|YEARS',
                            'value' => <integer>,
                        ],
                        'regions' => ['<string>', ...],
                        'sharedAccounts' => ['<string>', ...],
                        'tagMap' => ['<string>', ...],
                    ],
                    'tagMap' => ['<string>', ...],
                ],
                'filter' => [
                    'retainAtLeast' => <integer>,
                    'type' => 'AGE|COUNT',
                    'unit' => 'DAYS|WEEKS|MONTHS|YEARS',
                    'value' => <integer>,
                ],
            ],
            // ...
        ],
        'resourceSelection' => [
            'recipes' => [
                [
                    'name' => '<string>',
                    'semanticVersion' => '<string>',
                ],
                // ...
            ],
            'tagMap' => ['<string>', ...],
        ],
        'resourceType' => 'AMI_IMAGE|CONTAINER_IMAGE',
        'status' => 'DISABLED|ENABLED',
        'tags' => ['<string>', ...],
    ],
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the details of a lifecycle policy

The following example retrieves the full definition of the specified lifecycle policy.

$result = $client->getLifecyclePolicy([
    'lifecyclePolicyArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:lifecycle-policy/my-example-lifecycle-policy',
]);

Result syntax:

[
    'lifecyclePolicy' => [
        'name' => 'my-example-lifecycle-policy',
        'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:lifecycle-policy/my-example-lifecycle-policy',
        'dateCreated' => ,
        'description' => 'Deletes AMIs and snapshots for builds older than six months, keeping at least the five most recent',
        'executionRole' => 'arn:aws:iam::111122223333:role/my-example-lifecycle-role',
        'policyDetails' => [
            [
                'action' => [
                    'type' => 'DELETE',
                    'includeResources' => [
                        'amis' => 1,
                        'snapshots' => 1,
                    ],
                ],
                'filter' => [
                    'type' => 'AGE',
                    'value' => 6,
                    'retainAtLeast' => 5,
                    'unit' => 'MONTHS',
                ],
            ],
        ],
        'resourceSelection' => [
            'tagMap' => [
                'Environment' => 'my-example-environment',
            ],
        ],
        'resourceType' => 'AMI_IMAGE',
        'status' => 'ENABLED',
    ],
]

GetMarketplaceResource

$result = $client->getMarketplaceResource([/* ... */]);
$promise = $client->getMarketplaceResourceAsync([/* ... */]);

Verifies the subscription and performs resource dependency checks on the requested Amazon Web Services Marketplace resource. The caller must be entitled to the resource. For Amazon Web Services Marketplace components, the response contains fields to download the components and their artifacts.

Parameter Syntax

$result = $client->getMarketplaceResource([
    'resourceArn' => '<string>', // REQUIRED
    'resourceLocation' => '<string>',
    'resourceType' => 'COMPONENT_DATA|COMPONENT_ARTIFACT', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'data' => '<string>',
    'resourceArn' => '<string>',
    'url' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

GetWorkflow

$result = $client->getWorkflow([/* ... */]);
$promise = $client->getWorkflowAsync([/* ... */]);

Retrieves a workflow resource object.

Parameter Syntax

$result = $client->getWorkflow([
    'workflowBuildVersionArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'latestVersionReferences' => [
        'latestMajorVersionArn' => '<string>',
        'latestMinorVersionArn' => '<string>',
        'latestPatchVersionArn' => '<string>',
        'latestVersionArn' => '<string>',
    ],
    'workflow' => [
        'arn' => '<string>',
        'changeDescription' => '<string>',
        'data' => '<string>',
        'dateCreated' => '<string>',
        'description' => '<string>',
        'kmsKeyId' => '<string>',
        'name' => '<string>',
        'owner' => '<string>',
        'parameters' => [
            [
                'defaultValue' => ['<string>', ...],
                'description' => '<string>',
                'name' => '<string>',
                'type' => '<string>',
            ],
            // ...
        ],
        'state' => [
            'reason' => '<string>',
            'status' => 'DEPRECATED',
        ],
        'tags' => ['<string>', ...],
        'type' => 'BUILD|TEST|DISTRIBUTION',
        'version' => '<string>',
    ],
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the details of a workflow build version

The following example retrieves a workflow build version. The response includes the YAML workflow document in the data field and the parameters that Image Builder extracted from it when the workflow was created.

$result = $client->getWorkflow([
    'workflowBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.0.0/1',
]);

Result syntax:

[
    'latestVersionReferences' => [
        'latestMajorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.x.x',
        'latestMinorVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.0.x',
        'latestPatchVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.0.0',
        'latestVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/x.x.x',
    ],
    'workflow' => [
        'version' => '1.0.0',
        'name' => 'my-example-workflow',
        'type' => 'BUILD',
        'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/my-example-workflow/1.0.0/1',
        'changeDescription' => 'Initial version',
        'data' => 'name: my-example-workflowdescription: Workflow to build an AMI, then wait for an external action before it completesschemaVersion: 1.0parameters: - name: waitForActionAtEnd type: boolean default: truesteps: - name: LaunchBuildInstance action: LaunchInstance onFailure: Abort inputs: waitFor: "ssmAgent" - name: ApplyBuildComponents action: ExecuteComponents onFailure: Abort inputs: instanceId.$: "$.stepOutputs.LaunchBuildInstance.instanceId" - name: CreateOutputAMI action: CreateImage onFailure: Abort inputs: instanceId.$: "$.stepOutputs.LaunchBuildInstance.instanceId" - name: TerminateBuildInstance action: TerminateInstance onFailure: Continue inputs: instanceId.$: "$.stepOutputs.LaunchBuildInstance.instanceId" - name: WaitForActionAtEnd action: WaitForAction if: booleanEquals: true value: "$.parameters.waitForActionAtEnd"',
        'dateCreated' => '2026-09-09T19:55:55.731Z',
        'description' => 'Builds an AMI, and then waits for an external action before the workflow completes',
        'owner' => '111122223333',
        'parameters' => [
            [
                'name' => 'waitForActionAtEnd',
                'type' => 'boolean',
                'defaultValue' => [
                    'true',
                ],
            ],
        ],
    ],
]

GetWorkflowExecution

$result = $client->getWorkflowExecution([/* ... */]);
$promise = $client->getWorkflowExecutionAsync([/* ... */]);

Retrieves runtime information for a specific runtime instance of the workflow.

Parameter Syntax

$result = $client->getWorkflowExecution([
    'workflowExecutionId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'endTime' => '<string>',
    'imageBuildVersionArn' => '<string>',
    'message' => '<string>',
    'parallelGroup' => '<string>',
    'requestId' => '<string>',
    'startTime' => '<string>',
    'status' => 'PENDING|SKIPPED|RUNNING|COMPLETED|FAILED|ROLLBACK_IN_PROGRESS|ROLLBACK_COMPLETED|CANCELLED',
    'totalStepCount' => <integer>,
    'totalStepsFailed' => <integer>,
    'totalStepsSkipped' => <integer>,
    'totalStepsSucceeded' => <integer>,
    'type' => 'BUILD|TEST|DISTRIBUTION',
    'workflowBuildVersionArn' => '<string>',
    'workflowExecutionId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the runtime details for a workflow execution

The following example retrieves runtime status and step counts for the build workflow that ran for an image build version, using the workflow execution ID returned by ListWorkflowExecutions.

$result = $client->getWorkflowExecution([
    'workflowExecutionId' => 'wf-165b1cb6-3a62-4618-a021-94ddcbe32908',
]);

Result syntax:

[
    'type' => 'BUILD',
    'endTime' => '2026-09-09T19:19:06.158Z',
    'imageBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0/1',
    'requestId' => 'cd69c813-51c3-4261-8e59-382a1af96f73',
    'startTime' => '2026-09-09T19:12:23.175Z',
    'status' => 'COMPLETED',
    'totalStepCount' => 7,
    'totalStepsFailed' => 0,
    'totalStepsSkipped' => 2,
    'totalStepsSucceeded' => 5,
    'workflowBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:aws:workflow/build/build-image/1.0.3/1',
    'workflowExecutionId' => 'wf-165b1cb6-3a62-4618-a021-94ddcbe32908',
]

GetWorkflowStepExecution

$result = $client->getWorkflowStepExecution([/* ... */]);
$promise = $client->getWorkflowStepExecutionAsync([/* ... */]);

Retrieves runtime information for a specific runtime instance of the workflow step.

Parameter Syntax

$result = $client->getWorkflowStepExecution([
    'stepExecutionId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'action' => '<string>',
    'attemptNumber' => <integer>,
    'description' => '<string>',
    'endTime' => '<string>',
    'imageBuildVersionArn' => '<string>',
    'inputs' => '<string>',
    'maxAttempts' => <integer>,
    'message' => '<string>',
    'name' => '<string>',
    'onFailure' => '<string>',
    'outputs' => '<string>',
    'requestId' => '<string>',
    'rollbackStatus' => 'RUNNING|COMPLETED|SKIPPED|FAILED',
    'startTime' => '<string>',
    'status' => 'PENDING|SKIPPED|RUNNING|COMPLETED|FAILED|CANCELLED',
    'stepExecutionId' => '<string>',
    'timeoutSeconds' => <integer>,
    'workflowBuildVersionArn' => '<string>',
    'workflowExecutionId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: Get the runtime details of a workflow step

The following example retrieves runtime details for the step that launched the build instance during an image build, with the step's input parameters and output values returned as JSON-encoded strings.

$result = $client->getWorkflowStepExecution([
    'stepExecutionId' => 'step-2e6fef0d-657c-4b7e-8706-ff24da9afa01',
]);

Result syntax:

[
    'name' => 'LaunchBuildInstance',
    'action' => 'LaunchInstance',
    'endTime' => '2026-09-09T19:14:50.822Z',
    'imageBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-recipe/1.0.0/1',
    'inputs' => '{"waitFor": "ssmAgent"}',
    'onFailure' => 'Abort',
    'outputs' => '{"instanceId": "i-1234567890abcdef0"}',
    'requestId' => '9ba63d27-9568-4ea3-bfed-6b1ad4c09200',
    'startTime' => '2026-09-09T19:12:23.418Z',
    'status' => 'COMPLETED',
    'stepExecutionId' => 'step-2e6fef0d-657c-4b7e-8706-ff24da9afa01',
    'timeoutSeconds' => 4500,
    'workflowBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:aws:workflow/build/build-image/1.0.3/1',
    'workflowExecutionId' => 'wf-165b1cb6-3a62-4618-a021-94ddcbe32908',
]

ImportComponent

$result = $client->importComponent([/* ... */]);
$promise = $client->importComponentAsync([/* ... */]);

Imports a component and transforms its data into a component document. For the SHELL format, Image Builder wraps your script in a component document with a single step that runs the script.

Parameter Syntax

$result = $client->importComponent([
    'changeDescription' => '<string>',
    'clientToken' => '<string>', // REQUIRED
    'data' => '<string>',
    'description' => '<string>',
    'format' => 'SHELL', // REQUIRED
    'kmsKeyId' => '<string>',
    'name' => '<string>', // REQUIRED
    'platform' => 'Windows|Linux|macOS', // REQUIRED
    'semanticVersion' => '<string>', // REQUIRED
    'tags' => ['<string>', ...],
    'type' => 'BUILD|TEST', // REQUIRED
    'uri' => '<string>',
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'componentBuildVersionArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

IdempotentParameterMismatchException:

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

InvalidVersionNumberException:

Your version number is out of bounds or does not follow the required syntax.

ResourceInUseException:

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

InvalidParameterCombinationException:

You have specified a combination of parameters that isn't valid. For example, two mutually exclusive parameters, or a parameter without its required companion parameter. Review the error message for details.

Examples

Example 1: Import a component from a shell script

The following example imports a plain shell script as a Linux build component.

$result = $client->importComponent([
    'name' => 'my-example-imported-component',
    'type' => 'BUILD',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE88888',
    'data' => 'sudo yum update -ysudo yum -y install my-app',
    'description' => 'Installs my application from an imported shell script',
    'format' => 'SHELL',
    'platform' => 'Linux',
    'semanticVersion' => '1.0.0',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE88888',
    'componentBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-imported-component/1.0.0/1',
    'requestId' => 'e62cb87f-e291-4fb2-9305-54a7878c3b99',
]

ImportDiskImage

$result = $client->importDiskImage([/* ... */]);
$promise = $client->importDiskImageAsync([/* ... */]);

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

• Windows 11 Enterprise

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

Parameter Syntax

$result = $client->importDiskImage([
    'clientToken' => '<string>', // REQUIRED
    'description' => '<string>',
    'executionRole' => '<string>',
    'infrastructureConfigurationArn' => '<string>', // REQUIRED
    'loggingConfiguration' => [
        'logGroupName' => '<string>',
    ],
    'name' => '<string>', // REQUIRED
    'osVersion' => '<string>', // REQUIRED
    'platform' => '<string>', // REQUIRED
    'registerImageOptions' => [
        'secureBootEnabled' => true || false,
        'uefiData' => '<string>',
    ],
    'semanticVersion' => '<string>', // REQUIRED
    'tags' => ['<string>', ...],
    'uri' => '<string>', // REQUIRED
    'windowsConfiguration' => [
        'imageIndex' => <integer>, // REQUIRED
    ],
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'imageBuildVersionArn' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

AccessDeniedException:

You do not have permissions to perform the requested operation.

TooManyRequestsException:

You have attempted too many requests for the specific operation.

Examples

Example 1: Import a Windows 11 ISO disk image

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

$result = $client->importDiskImage([
    'name' => 'my-example-imported-image',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE12345',
    'infrastructureConfigurationArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:infrastructure-configuration/my-example-infrastructure',
    'osVersion' => 'Microsoft Windows 11',
    'platform' => 'Windows',
    'semanticVersion' => '1.0.0',
    'uri' => 's3://amzn-s3-demo-bucket/Win11_23H2_English_x64.iso',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE12345',
    'imageBuildVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-imported-image/1.0.0/1',
]

ImportVmImage

$result = $client->importVmImage([/* ... */]);
$promise = $client->importVmImageAsync([/* ... */]);

Creates an Image Builder image resource from an Amazon EC2 VM import task. The response returns as soon as Image Builder creates the image resource in the PENDING state. Image Builder then monitors the import task asynchronously. When the task completes, Image Builder records the AMI that it produced as the new image's output resource and marks the image AVAILABLE. You can then use the imported image as the base image for your recipes.

To create the VM import task, use the Amazon EC2 API ImportImage operation, or the import-image CLI command.

Parameter Syntax

$result = $client->importVmImage([
    'clientToken' => '<string>', // REQUIRED
    'description' => '<string>',
    'loggingConfiguration' => [
        'logGroupName' => '<string>',
    ],
    'name' => '<string>', // REQUIRED
    'osVersion' => '<string>',
    'platform' => 'Windows|Linux|macOS', // REQUIRED
    'semanticVersion' => '<string>', // REQUIRED
    'tags' => ['<string>', ...],
    'vmImportTaskId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'clientToken' => '<string>',
    'imageArn' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

Examples

Example 1: Import a virtual machine as an Image Builder image

The following example registers the output of an EC2 VM Import/Export task (import-ami) as a new Image Builder image, so you can use the imported virtual machine as a base image.

$result = $client->importVmImage([
    'name' => 'my-example-imported-image',
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE00000',
    'osVersion' => 'Amazon Linux 2',
    'platform' => 'Linux',
    'semanticVersion' => '1.0.0',
    'vmImportTaskId' => 'import-ami-1234567890abcdef0',
]);

Result syntax:

[
    'clientToken' => 'a1b2c3d4-5678-90ab-cdef-EXAMPLE00000',
    'imageArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-imported-image/1.0.0/1',
    'requestId' => 'f8a1d0ce-42b7-4d6a-9b12-3c84a02e5f19',
]

ListComponentBuildVersions

$result = $client->listComponentBuildVersions([/* ... */]);
$promise = $client->listComponentBuildVersionsAsync([/* ... */]);

Returns a list of component build versions for the specified component version ARN. You can only list build versions for components that your account owns. Deprecated build versions aren't included in the results.

Parameter Syntax

$result = $client->listComponentBuildVersions([
    'componentVersionArn' => '<string>',
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Result Syntax

[
    'componentSummaryList' => [
        [
            'arn' => '<string>',
            'changeDescription' => '<string>',
            'dateCreated' => '<string>',
            'description' => '<string>',
            'name' => '<string>',
            'obfuscate' => true || false,
            'owner' => '<string>',
            'platform' => 'Windows|Linux|macOS',
            'publisher' => '<string>',
            'state' => [
                'reason' => '<string>',
                'status' => 'DEPRECATED|DISABLED|ACTIVE',
            ],
            'supportedOsVersions' => ['<string>', ...],
            'tags' => ['<string>', ...],
            'type' => 'BUILD|TEST',
            'version' => '<string>',
        ],
        // ...
    ],
    'nextToken' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

InvalidPaginationTokenException:

You have provided an invalid pagination token in your request.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: List the build versions of a component

The following example lists the build versions that exist for version 1.0.0 of the specified component. The list returns the most recent build version first.

$result = $client->listComponentBuildVersions([
    'componentVersionArn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0',
]);

Result syntax:

[
    'componentSummaryList' => [
        [
            'version' => '1.0.0',
            'name' => 'my-example-component',
            'type' => 'BUILD',
            'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0/2',
            'changeDescription' => 'Updated the install command to use dnf',
            'dateCreated' => '2026-09-09T18:35:23.098Z',
            'description' => 'Installs the latest version of my application',
            'owner' => '111122223333',
            'platform' => 'Linux',
            'state' => [
                'status' => 'ACTIVE',
            ],
            'supportedOsVersions' => [
                'Amazon Linux 2023',
            ],
            'tags' => [
                'Environment' => 'Production',
            ],
        ],
        [
            'version' => '1.0.0',
            'name' => 'my-example-component',
            'type' => 'BUILD',
            'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0/1',
            'changeDescription' => 'Initial version',
            'dateCreated' => '2026-09-09T18:35:20.731Z',
            'description' => 'Installs the latest version of my application',
            'owner' => '111122223333',
            'platform' => 'Linux',
            'state' => [
                'status' => 'ACTIVE',
            ],
            'supportedOsVersions' => [
                'Amazon Linux 2023',
            ],
            'tags' => [
                'Environment' => 'Production',
            ],
        ],
    ],
    'requestId' => '1d8693f0-26e1-42d7-ba35-d95ace1ce7e0',
]

ListComponents

$result = $client->listComponents([/* ... */]);
$promise = $client->listComponentsAsync([/* ... */]);

Returns the list of components that you have access to. By default, the response doesn't include components in the DEPRECATED state. To list deprecated components, use the status filter with the value DEPRECATED.

Parameter Syntax

$result = $client->listComponents([
    'byName' => true || false,
    'filters' => [
        [
            'name' => '<string>',
            'values' => ['<string>', ...],
        ],
        // ...
    ],
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'owner' => 'Self|Shared|Amazon|ThirdParty|AWSMarketplace',
]);

Parameter Details

Result Syntax

[
    'componentVersionList' => [
        [
            'arn' => '<string>',
            'dateCreated' => '<string>',
            'description' => '<string>',
            'name' => '<string>',
            'owner' => '<string>',
            'platform' => 'Windows|Linux|macOS',
            'productCodes' => [
                [
                    'productCodeId' => '<string>',
                    'productCodeType' => 'marketplace',
                ],
                // ...
            ],
            'status' => 'DEPRECATED|DISABLED|ACTIVE',
            'supportedOsVersions' => ['<string>', ...],
            'type' => 'BUILD|TEST',
            'version' => '<string>',
        ],
        // ...
    ],
    'nextToken' => '<string>',
    'requestId' => '<string>',
]

Result Details

Errors

ServiceException:

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

ClientException:

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

ServiceUnavailableException:

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

InvalidRequestException:

The request is malformed or otherwise invalid. Verify the request and try again.

InvalidPaginationTokenException:

You have provided an invalid pagination token in your request.

ForbiddenException:

You are not authorized to perform the requested operation.

CallRateLimitExceededException:

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

Examples

Example 1: List components that you own

The following example lists the component versions that your account owns, filtered to components for the Linux platform.

$result = $client->listComponents([
    'filters' => [
        [
            'name' => 'platform',
            'values' => [
                'Linux',
            ],
        ],
    ],
    'owner' => 'Self',
]);

Result syntax:

[
    'componentVersionList' => [
        [
            'version' => '1.0.0',
            'name' => 'my-example-component',
            'type' => 'BUILD',
            'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0',
            'dateCreated' => '2026-09-09T18:31:49.661Z',
            'description' => 'Installs my example application',
            'owner' => '111122223333',
            'platform' => 'Linux',
            'status' => 'ACTIVE',
            'supportedOsVersions' => [
                'Amazon Linux 2023',
            ],
        ],
        [
            'version' => '1.0.0',
            'name' => 'my-example-imported-component',
            'type' => 'BUILD',
            'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-imported-component/1.0.0',
            'dateCreated' => '2026-09-09T18:31:21.941Z',
            'description' => 'Installs my application from an imported shell script',
            'owner' => '111122223333',
            'platform' => 'Linux',
            'status' => 'ACTIVE',
        ],
        [
            'version' => '1.0.0',
            'name' => 'my-example-test-component',
            'type' => 'TEST',
            'arn' => 'arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-test-component/1.0.0',
            'dateCreated' => '2026-09-09T18:31:52.888Z',
            'description' => 'Verifies that my example application is installed',
            'owner' => '111122223333',
            'platform' => 'Linux',
            'status' => 'ACTIVE',
        ],
    ],
    'requestId' => 'fc51d989-ca0a-4ac7-9ca6-fb7786e70955',
]

ListContainerRecipes

$result = $client->listContainerRecipes([/* ... */]);
$promise = $client->listContainerRecipesAsync([/* ... */]);

Returns a list of container recipes.

Parameter Syntax

$result = $client->listContainerRecipes([
    'filters' => [
        [
            'name' => '<string>',
            'values' => ['<string>', ...],
        ],
        // ...
    ],
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'owner' => 'Self|Shared|Amazon|ThirdParty|AWSMarketplace',
]);

Parameter Details

Result Syntax

[
    'containerRecipeSummaryList' => [
        [
            'arn' => '<string>',
            'containerType' => 'DOCKER',
            'dateCreated' => '<string>',
            'instanceImage' => '<string>',
            'name' => '<string>',
            'owner' => '<string>',
            'parentImage' => '<string>',
            'platform' => 'Windows|Linux|macOS',
            'tags' => ['<string>', ...],
        ],
        // ...
    ],
    'nextToken' => '<string>',
    'requestId' => '<string>',
]

Result Details