Syntax Properties Return values Examples See also

AWS::ImageBuilder::Image

An image resource represents a versioned AMI or container image that Image Builder produces. Each image is built from a recipe, tested, and then distributed to the Regions and accounts that you specify.

Creates a new image in one of the following ways:

From an image recipe - Specify an ImageRecipeArn and an InfrastructureConfigurationArn. Image Builder launches an instance, applies your components, and creates an AMI.
From a container recipe - Specify a ContainerRecipeArn and an InfrastructureConfigurationArn. Image Builder builds a Docker container image and pushes it to your target repository.
From a pipeline - Specify ImagePipelineExecutionSettings with a DeploymentId that references an existing image pipeline. Image Builder runs the pipeline to create the image. The pipeline already defines the recipe and infrastructure configuration.

Syntax

To declare this entity in your CloudFormation template, use the following syntax:

JSON


{
  "Type" : "AWS::ImageBuilder::Image",
  "Properties" : {
      "ContainerRecipeArn" : String,
      "DeletionSettings" : DeletionSettings,
      "DistributionConfigurationArn" : String,
      "EnhancedImageMetadataEnabled" : Boolean,
      "ExecutionRole" : String,
      "ImagePipelineExecutionSettings" : ImagePipelineExecutionSettings,
      "ImageRecipeArn" : String,
      "ImageScanningConfiguration" : ImageScanningConfiguration,
      "ImageTestsConfiguration" : ImageTestsConfiguration,
      "InfrastructureConfigurationArn" : String,
      "LoggingConfiguration" : ImageLoggingConfiguration,
      "Tags" : {Key: Value, ...},
      "Workflows" : [ WorkflowConfiguration, ... ]
    }
}

YAML


Type: AWS::ImageBuilder::Image
Properties:
  ContainerRecipeArn: String
  DeletionSettings: 
    DeletionSettings
  DistributionConfigurationArn: String
  EnhancedImageMetadataEnabled: Boolean
  ExecutionRole: String
  ImagePipelineExecutionSettings: 
    ImagePipelineExecutionSettings
  ImageRecipeArn: String
  ImageScanningConfiguration: 
    ImageScanningConfiguration
  ImageTestsConfiguration: 
    ImageTestsConfiguration
  InfrastructureConfigurationArn: String
  LoggingConfiguration: 
    ImageLoggingConfiguration
  Tags: 
    Key: Value
  Workflows: 
    - WorkflowConfiguration

Properties

ContainerRecipeArn

The Amazon Resource Name (ARN) of the container recipe that defines how images are configured and tested.

Required: No

Type: String

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

Update requires: Replacement

DeletionSettings

Enables deletion of underlying resources of an image when it is replaced or deleted, including its Amazon Machine Images (AMIs), snapshots, or containers.

Required: No

Type: DeletionSettings

Update requires: No interruption

DistributionConfigurationArn

The Amazon Resource Name (ARN) of the distribution configuration that defines and configures the outputs of your pipeline.

Required: No

Type: String

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

Update requires: Replacement

EnhancedImageMetadataEnabled

Collects additional information about the image being created, including the operating system (OS) version and package list. This information is used to enhance the overall experience of using EC2 Image Builder. Enabled by default.

Required: No

Type: Boolean

Update requires: Replacement

ExecutionRole

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

Required: No

Type: String

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

Minimum: 1

Maximum: 2048

Update requires: No interruption

ImagePipelineExecutionSettings

The settings for creating the image by running an existing image pipeline, instead of building it from a recipe. When you specify these settings, do not specify recipe or infrastructure properties. The pipeline that you reference already defines them.

Required: No

Type: ImagePipelineExecutionSettings

Update requires: Some interruptions

ImageRecipeArn

The Amazon Resource Name (ARN) of the image recipe that defines how images are configured, tested, and assessed.

Required: No

Type: String

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

Update requires: Replacement

ImageScanningConfiguration

Contains settings for vulnerability scans.

Required: No

Type: ImageScanningConfiguration

Update requires: Replacement

ImageTestsConfiguration

The image tests configuration of the image.

Required: No

Type: ImageTestsConfiguration

Update requires: Replacement

InfrastructureConfigurationArn

The Amazon Resource Name (ARN) of the infrastructure configuration that defines the environment in which your image will be built and tested.

Required: No

Type: String

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

Update requires: Replacement

LoggingConfiguration

The logging configuration that's defined for the image. Image Builder uses the defined settings to direct execution log output during image creation.

Required: No

Type: ImageLoggingConfiguration

Update requires: No interruption

Tags

The tags of the image.

Required: No

Type: Object of String

Pattern: .{1,}

Update requires: No interruption

Workflows

Contains an array of workflow configuration objects.

Required: No

Type: Array of WorkflowConfiguration

Update requires: Replacement

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the resource ARN, such as arn:aws:imagebuilder:us-west-2:111122223333:image/my-example-image.

For more information about using the Ref function, see Ref.

Fn::GetAtt

The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.

Arn: Returns the Amazon Resource Name (ARN) of the image. For example, arn:aws:imagebuilder:us-west-2:111122223333:image/mybasicrecipe/2019.12.03/1.
ImageId: Returns the AMI ID of the Amazon EC2 AMI in the Region in which you are using Image Builder. Values are returned only for AMIs, and not for container images.
ImageUri: Returns the URI for a container image created in the context Region. Values are returned only for container images, and not for AMIs.
LatestVersion.Arn: The latest version Amazon Resource Name (ARN) of the Image Builder resource.
LatestVersion.Major: The latest version Amazon Resource Name (ARN) with the same major version of the Image Builder resource.
LatestVersion.Minor: The latest version Amazon Resource Name (ARN) with the same minor version of the Image Builder resource.
LatestVersion.Patch: The latest version Amazon Resource Name (ARN) with the same patch version of the Image Builder resource.
Name: Returns the name of the image.

Create an image

The following example shows the template for the Image resource in both YAML and JSON format.

YAML


Resources:
  ImageAllParameters:
    Type: 'AWS::ImageBuilder::Image'
    Properties:
      ImageRecipeArn: !Ref ImageRecipeArn
      InfrastructureConfigurationArn: !Ref InfrastructureConfigurationArn
      DistributionConfigurationArn: !Ref DistributionConfigurationArn
      ImageTestsConfiguration:
        ImageTestsEnabled: false
        TimeoutMinutes: 60
      Tags:
        CustomerImageTagKey1: 'CustomerImageTagValue1'
        CustomerImageTagKey2: 'CustomerImageTagValue2'

JSON


{
    "Resources": {
        "ImageAllParameters": {
            "Type": "AWS::ImageBuilder::Image",
            "Properties": {
                "ImageRecipeArn": {
                    "Ref": "ImageRecipeArn"
                },
                "InfrastructureConfigurationArn": {
                    "Ref": "InfrastructureConfigurationArn"
                },
                "DistributionConfigurationArn": {
                    "Ref": "DistributionConfigurationArn"
                },
                "ImageTestsConfiguration": {
                    "ImageTestsEnabled": false,
                    "TimeoutMinutes": 60
                },
                "Tags": {
                    "CustomerImageTagKey1": "CustomerImageTagValue1",
                    "CustomerImageTagKey2": "CustomerImageTagValue2"
                }
            }
        }
    }
}

Create a pipeline-driven image

The following example creates an image by running an existing image pipeline. When the pipeline configuration changes, updating the stack triggers a new pipeline execution. This mode does not require a recipe or infrastructure configuration because the referenced pipeline defines them.

YAML


Resources:
  PipelineDrivenImage:
    Type: AWS::ImageBuilder::Image
    Properties:
      ImagePipelineExecutionSettings:
        DeploymentId: !GetAtt MyImagePipeline.DeploymentId
        OnUpdate: true
      Tags:
        Environment: production

JSON


{
    "Resources": {
        "PipelineDrivenImage": {
            "Type": "AWS::ImageBuilder::Image",
            "Properties": {
                "ImagePipelineExecutionSettings": {
                    "DeploymentId": {
                        "Fn::GetAtt": ["MyImagePipeline", "DeploymentId"]
                    },
                    "OnUpdate": true
                },
                "Tags": {
                    "Environment": "production"
                }
            }
        }
    }
}