# Configure custom images with Image Builder Configuration resources are the building blocks that make up image pipelines, as well as the images those pipelines produce. This chapter covers creating, maintaining, and sharing Image Builder resources, including components, recipes, and images, along with infrastructure configuration and distribution settings. **Note** To help you manage your Image Builder resources, you can assign your own metadata to each resource in the form of tags. You use tags to categorize your AWS resources in different ways; for example, by purpose, owner, or environment. This is useful when you have many resources of the same type. You can more readily identify a specific resource based on the tags you've assigned to it. For more information about tagging your resources using Image Builder commands in the AWS CLI, see the [Tag resources](tag-resources.md) section of this guide. **Topics** + [ # Manage recipes in Image Builder ](manage-recipes.md) + [ # Manage Image Builder infrastructure configuration ](manage-infra-config.md) + [ # Manage Image Builder distribution settings ](manage-distribution-settings.md) # Manage recipes in Image Builder An EC2 Image Builder recipe defines the base image to use as your starting point to create a new image, along with the set of components that you add to customize your image and verify that everything works as expected. Image Builder provides automatic version choices for each component. By default, you can apply up to 20 components to a recipe. This includes both build and test components. After you create a recipe, you can't modify or replace it. To update components after you create a recipe, you must create a new recipe or recipe version. You can always apply tags to your existing recipes. For more information about tagging your resources using Image Builder commands in the AWS CLI, see the [Tag resources](tag-resources.md) section of this guide. **Tip** You can use Amazon managed components in your recipes, or you can develop your own custom components. For more information, see [Develop custom components for your Image Builder image](create-custom-components.md). For image recipes that create output AMIs, you can also use AWS Marketplace image products and components. For more information about integration with AWS Marketplace products, see [AWS Marketplace integration in Image Builder](integ-marketplace.md). This section covers how to list, view, and create recipes. **Topics** + [ # List and view image recipe details ](image-recipe-details.md) + [ # List and view container recipe details ](container-recipe-details.md) + [ # Create a new version of an image recipe ](create-image-recipes.md) + [ # Create a new version of a container recipe ](create-container-recipes.md) + [ ## Clean up resources ](#recipes-cleanup) # List and view image recipe details This section describes the various ways that you can find information and view details for your EC2 Image Builder image recipes. **Topics** + [ ## List image recipes from the console ](#list-image-recipes-console) + [ ## List image recipes from the AWS CLI ](#cli-list-image-recipes) + [ ## View image recipe details from the console ](#view-image-recipe-details-console) + [ ## Get image recipe details from the AWS CLI ](#cli-get-image-recipe) + [ ## Get image recipe policy details from the AWS CLI ](#cli-get-image-recipe-policy) ## List image recipes from the console To see a list of the image recipes created under your account in the Image Builder console, follow these steps: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. Choose **Image recipes** from the navigation pane. This shows a list of the image recipes that are created under your account. 1. To view details or create a new recipe version, choose the **Recipe name** link. This opens the detail view for the recipe. **Note** You can also select the check box next to the **Recipe name**, then choose **View details**. ## List image recipes from the AWS CLI The following example shows how to list all of your image recipes, using the AWS CLI. ``` aws imagebuilder list-image-recipes ``` ## View image recipe details from the console To view details for a specific image recipe using the Image Builder console, select the image recipe to review, using the steps described in [List image recipes from the console](#list-image-recipes-console). On the recipe detail page, you can: + Delete the recipe. For more information about deleting resources in Image Builder, see [Delete outdated or unused Image Builder resources](delete-resources.md). + Create a new version. + Create a pipeline from the recipe. After choosing **Create pipeline from this recipe**, you are taken to the pipeline wizard. For more information about creating an Image Builder pipeline using the pipeline wizard, see [Tutorial: Create an image pipeline with output AMI from the Image Builder console wizard](start-build-image-pipeline.md) **Note** When you create a pipeline from an existing recipe, the option to create a new recipe is not available. ## Get image recipe details from the AWS CLI The following example shows how to use an **imagebuilder** CLI command to get the details of an image recipe by specifying its Amazon Resource Name (ARN). ``` aws imagebuilder get-image-recipe --image-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-recipe/2020.12.03 ``` ## Get image recipe policy details from the AWS CLI The following example shows how to use an **imagebuilder** CLI command to get the details of an image recipe policy by specifying its ARN. ``` aws imagebuilder get-image-recipe-policy --image-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-recipe/2020.12.03 ``` # List and view container recipe details This section describes the ways that you can find information and view details for your EC2 Image Builder container recipes. **Topics** + [ ## List container recipes in the console ](#list-container-recipes-console) + [ ## List container recipes with the AWS CLI ](#cli-list-container-recipes) + [ ## View container recipe details in the console ](#view-container-recipe-details-console) + [ ## Get container recipe details with the AWS CLI ](#cli-get-container-recipe) + [ ## Get container recipe policy details with the AWS CLI ](#cli-get-container-recipe-policy) ## List container recipes in the console To see a list of the container recipes that have been created under your account in the Image Builder console, follow these steps: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. Choose **Container recipes** from the navigation pane. This shows a list of the container recipes that are created under your account. 1. To view details or create a new recipe version, choose the **Recipe name** link. This opens the detail view for the recipe. **Note** You can also select the check box next to the **Recipe name**, and then choose **View details**. ## List container recipes with the AWS CLI The following example shows how to list all of your container recipes, using the AWS CLI. ``` aws imagebuilder list-container-recipes ``` ## View container recipe details in the console To view details for a specific container recipe with the Image Builder console, select the container recipe to review, and use the steps described in [List container recipes in the console](#list-container-recipes-console). On the recipe detail page, you can do the following: + Delete the recipe. For more information on how to delete resources in Image Builder, see [Delete outdated or unused Image Builder resources](delete-resources.md). + Create a new version. + Create a pipeline from the recipe. After ou choose **Create pipeline from this recipe**, you are taken to the pipeline wizard. For more information on how to create an Image Builder pipeline using the pipeline wizard, see [Tutorial: Create an image pipeline with output AMI from the Image Builder console wizard](start-build-image-pipeline.md) **Note** When you create a pipeline from an existing recipe, the option to create a new recipe isn't available. ## Get container recipe details with the AWS CLI The following example shows how to use an **imagebuilder** CLI command to get the details of a container recipe by specifying its ARN. ``` aws imagebuilder get-container-recipe --container-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:container-recipe/my-example-recipe/2020.12.03 ``` ## Get container recipe policy details with the AWS CLI The following example shows how to use an **imagebuilder** CLI command to get the details of a container recipe policy by specifying its ARN. ``` aws imagebuilder get-container-recipe-policy --container-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:container-recipe/my-example-recipe/2020.12.03 ``` # Create a new version of an image recipe This section describes how to create a new version of an image recipe. **Topics** + [ ## Create a new image recipe version from the console ](#create-image-recipe-version-console) + [ ## Create an image recipe with the AWS CLI ](#create-image-recipe-cli) + [ ## Import a VM as your base image in the console ](#import-vm-recipes) ## Create a new image recipe version from the console When you create a new recipe version, it's virtually the same as creating a new recipe. The difference is that certain details are pre-selected to match the base recipe, in most cases. The following list describes the differences between creating a new recipe and creating a new version of an existing recipe. **Base recipe details in the new version** + **Name** – *Not editable*. + **Version** – Required. Enter the version number that you want to create in the format *..*. Image Builder supports automatic version incrementing for recipes, allowing you to use wildcard patterns in your recipe versions. When you create a recipe with a wildcard version such as `1.0.x`, Image Builder automatically increments the version (for example, `1.0.1`, `1.0.2`, `1.0.3`, and so on). This eliminates the need to manually track and increment recipe versions. + The **Select image** option – Pre-selected, but you can edit it. If you change your choice for the source of your base image, you might lose other details that depend on the original option that you chose. To see details that are associated with your base image selection, choose the tab that matches your selection. ------ #### [ Managed image ] + **Image Operating System (OS)** – *Not editable*. + **Image name** – Pre-selected, based on the combination of base image choices that you made for the existing recipe. However, if you change the **Select image** option, you lose the pre-selected **Image name**. + **Auto-versioning options** – Does *not* match your base recipe. This image option defaults to the **Use selected OS version** option. **Important** If you're using semantic versioning to kick off pipeline builds, make sure that you change this value to **Use latest available OS version**. To learn more about semantic versioning for Image Builder resources, see [Semantic versioning in Image Builder](ibhow-semantic-versioning.md). ------ #### [ AWS Marketplace image ] + **Subscriptions** – This tab should be open, and the subscribed image from AWS Marketplace should be pre-selected to match your base recipe. If you change the image that your recipe uses as its base image, you might lose other details that depend on the original image that you chose. For more information about AWS Marketplace products, see [Buying products](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-subscribing-to-products.html) in the *AWS Marketplace Buyer Guide*. ------ #### [ Custom AMI ] **AMI source** (Required) - Enter the AMI ID or an AWS Systems Manager (SSM) Parameter Store parameter that contains an AMI ID to use as the base image. The SSM Agent must be pre-installed in the selected AMI. + **AMI ID** – This setting is not pre-filled with your original entry. Enter the AMI ID for your base image. Example: `ami-1234567890abcdef1`. + **SSM parameter** – Enter the name or ARN of the SSM Parameter Store parameter that contains the AMI ID for your base image. Example: `/ib/test/param` or `arn:aws:ssm:us-east-1:111122223333:parameter/ib/test/param`. ------ + **Instance configuration** – Settings are pre-selected, but you can edit them. + **Systems Manager agent** – You can select or clear this check box to control installation of the Systems Manager agent on the new image. The check box is cleared by default to include the Systems Manager agent in your new image. To remove the Systems Manager agent from the final image, select the check box so that the agent isn't included in your AMI. + **User data** – You can use this area to provide commands, or a command script to run, when you launch your build instance. However, this value replaces any commands that Image Builder might have added to ensure that Systems Manager is installed. These commands include the clean-up script that Image Builder normally runs for Linux images prior to creating the new image. When Image Builder launches an instance, user data scripts run during the cloud-init phase, before component execution begins. This step is logged to the following file on the instance: `var/log/cloud-init.log`. **Note** If you enter user data, make sure that the Systems Manager agent is pre-installed on your base image, or that you include the install in your user data. For Linux images, ensure that clean-up steps run by including a command to create an empty file named `perform_cleanup` in your user data script. Image Builder detects this file, and runs the clean-up script prior to creating the new image. For more information and a sample script, see [Security best practices for Image Builder](security-best-practices.md). + **Working directory** – Pre-selected, but you can edit it. + **Components** – Components that are already included in the recipe are displayed in the **Selected components** section at the end of each of the component lists (build and test). You can remove or reorder the selected components to suit your needs. CIS hardening components don't follow the standard component ordering rules in Image Builder recipes. The CIS hardening components always run last to ensure that the benchmark tests run against your output image. **Note** Build and test component lists display available components based on the component owner type. To add a component, choose **Add build components**, and select the ownership filter that applies. For example, to add a build component that's associated with an AWS Marketplace product, select `AWS Marketplace`. This opens a selection panel on the right side of the console interface that lists AWS Marketplace components. For the CIS component, select `Third party managed`. You can configure the following settings for your selected component: + **Versioning options** – Pre-selected, but you can change them. We recommend that you choose the **Use latest available component version** option to ensure that your image builds always pick up the latest version of the component. If you need to use a specific component version in your recipe, you can choose **Specify component version**, and enter the version in the **Component version** box that appears. + **Input parameters** – Displays input parameters that the component accepts. The **Value** is pre-filled with the value from the prior version of the recipe. If you are using this component for the first time in this recipe, and a default value was defined for the input parameter, the default value appears in the **Value** box with greyed-out text. If no other value is entered, Image Builder uses the default value. If an input parameter is required, but doesn't have a default value defined in the component, you must provide a value. Image Builder won't create the recipe version if there are any required parameters that are missing and don't have a default value defined. **Important** Component parameters are plain text values, and are logged in AWS CloudTrail. We recommend that you use AWS Secrets Manager or the AWS Systems Manager Parameter Store to store your secrets. For more information about Secrets Manager, see [What is Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*. For more information about AWS Systems Manager Parameter Store, see [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) in the *AWS Systems Manager User Guide*. To expand settings for **Versioning options** or **Input parameters**, you can choose the arrow next to the name of the setting. To expand all of the settings for all selected components, you can toggle the **Expand all** switch off and on. + **Storage (volumes)** – are pre-filled. The root volume **Device name**, **Snapshot**, and **IOPS** selections, are not editable. However, you can change all of the remaining settings, such as the **Size**. You can also add new volumes, and encrypt new or existing volumes. To encrypt volumes for the images that Image Builder creates under your account in the source Region (where the build runs), you must use the storage volume encryption in the image recipe. Encryption that runs during the distribution phase of the build is only for images that are distributed to other accounts or Regions. **Note** If you use encryption for your volumes, you must select the key for each volume separately, even if the key is the same one that's used for the root volume. **To create a new image recipe version:** 1. At the top of the recipe details page, choose **Create new version**. This takes you to the **Create image recipe** page. 1. To create the new version, make your changes, and then choose **Create recipe**. Your final image can contain up to four product codes from AWS Marketplace image products and components. If your selected base image and components contain more than four product codes, Image Builder returns an error when you try to create the recipe. For more information on how to create an image recipe when you create an image pipeline, see [Step 2: Choose recipe](start-build-image-pipeline.md#start-build-image-step2) in the **Get started** section of this guide. ## Create an image recipe with the AWS CLI To create an image recipe with the Image Builder `create-image-recipe` command in the AWS CLI, follow these steps: **Prerequisites** Before you run the Image Builder commands in this section to create an image recipe from the AWS CLI, you can optionally create components that the recipe uses. The image recipe example in the following step refers to example components that are created in the [Create a custom component from the AWS CLI](create-component.md#create-component-ib-cli) section of this guide. If you want to include components in your recipe, note the ARNs that you want to include. You can also create recipes without any components for testing existing AMIs or distribution-only workflows. 1. **Create a CLI input JSON file** You can provide all of the input for the **create-image-recipe** command with inline command parameters. However, the resulting command can be quite long. To streamline the command, you can instead provide a JSON file that contains all of the recipe settings. **Note** The naming convention for the data values in the JSON file follows the pattern that is specified for the Image Builder API operation request parameters. To review the API operation request parameters, see the [CreateImageRecipe](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateImageRecipe.html) command in the *EC2 Image Builder API Reference*. To provide the data values as command line parameters, refer to the parameter names specified in the *AWS CLI Command Reference*. Here is a summary of the parameters that these examples specify: + **name** (string, required) – The name of the image recipe. + **description** (string) – The description of the image recipe. + **parentImage** (string, required) – The image that the image recipe uses as a base for your customized image. You can specify the parent image using one of the following options: + AMI ID + Image Builder image resource ARN + AWS Systems Manager (SSM) Parameter Store parameter, prefixed by `ssm:`, followed by the parameter name or ARN. + AWS Marketplace product ID **Note** The Linux and macOS examples use an Image Builder AMI, and the Windows example uses an ARN. + **semanticVersion** (string, required) – Enter the version number that you want to create in the format *..*. Image Builder supports automatic version incrementing for recipes, allowing you to use wildcard patterns in your recipe versions. When you create a recipe with a wildcard version such as `1.0.x`, Image Builder automatically increments the version (for example, `1.0.1`, `1.0.2`, `1.0.3`, and so on). This eliminates the need to manually track and increment recipe versions. To learn more about semantic versioning for Image Builder resources, see [Semantic versioning in Image Builder](ibhow-semantic-versioning.md). + **components** (array, optional) – Contains an array of `ComponentConfiguration` objects. Components are optional - you can create recipes without any components for testing or distribution workflows: **Note** Image Builder installs components in the order that you specified them in the recipe. However, CIS hardening components always run last to ensure that the benchmark tests run against your output image. + **componentARN** (string, required) – The component ARN. **Tip** To use one of the examples to create your own image recipe, you must replace the example ARNs with the ARNs for the components that you are using for your recipe. + **parameters** (array of objects) – Contains an array of `ComponentParameter` objects. If an input parameter is required, but doesn't have a default value defined in the component, you must provide a value. Image Builder won't create the recipe version if there are any required parameters that are missing and don't have a default value defined. **Important** Component parameters are plain text values, and are logged in AWS CloudTrail. We recommend that you use AWS Secrets Manager or the AWS Systems Manager Parameter Store to store your secrets. For more information about Secrets Manager, see [What is Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*. For more information about AWS Systems Manager Parameter Store, see [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) in the *AWS Systems Manager User Guide*. + **name** (string, required) – The name of the component parameter to set. + **value** (array of strings, required) – Contains an array of strings to set the value for the named component parameter. If there is a default value defined for the component, and no other value is provided, AWSTOE uses the default value. + **additionalInstanceConfiguration** (object) – Specify additional settings and launch scripts for your build instances. + **systemsManagerAgent** (object) – Contains settings for the Systems Manager agent on your build instance. + **uninstallAfterBuild** (Boolean) – Controls whether the Systems Manager agent is removed from your final build image prior to creating the new AMI. If this option is set to `true`, then the agent is removed from the final image. If the option is set to `false`, then the agent is left in so that it is included in the new AMI. The default value is `false`. **Note** If the `uninstallAfterBuild` attribute isn't included in the JSON file, and the following conditions are true, then Image Builder removes the Systems Manager agent from the final image so that it isn't available in the AMI: The `userDataOverride` is empty or has been omitted from the JSON file. Image Builder automatically installed the Systems Manager agent on the build instance for an operating system that didn't have the agent pre-installed on the base image. + **userDataOverride** (string) – Provide commands or a command script to run when you launch your build instance. **Note** The user data is always base 64 encoded. For example, the following commands are encoded as `IyEvYmluL2Jhc2gKbWtkaXIgLXAgL3Zhci9iYi8KdG91Y2ggL3Zhcg==`: ``` #!/bin/bash mkdir -p /var/bb/ touch /var ``` The Linux example uses this encoded value. ------ #### [ Linux ] The base image (`parentImage` property) in the following example is an AMI. When you use an AMI, you must have access to the AMI, and the AMI must be in the source Region (the same Region where Image Builder runs the command). Save the file as `create-image-recipe.json`, and use it in the **create-image-recipe** command. ``` { "name": "BB Ubuntu Image recipe", "description": "Hello World image recipe for Linux.", "parentImage": "ami-1234567890abcdef1", "semanticVersion": "1.0.0", "components": [ { "componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/bb$" } ], "additionalInstanceConfiguration": { "systemsManagerAgent": { "uninstallAfterBuild": true }, "userDataOverride": "IyEvYmluL2Jhc2gKbWtkaXIgLXAgL3Zhci9iYi8KdG91Y2ggL3Zhcg==" } } ``` ------ #### [ Windows ] The following example refers to the latest version of the Windows Server 2016 English Full Base image. The ARN in this example references the latest image based on the semantic version filters that you've specified: `arn:aws:imagebuilder:us-west-2:aws:image/windows-server-2016-english-full-base-x86/x.x.x`. ``` { "name": "MyBasicRecipe", "description": "This example image recipe creates a Windows 2016 image.", "parentImage": "arn:aws:imagebuilder:us-west-2:aws:image/windows-server-2016-english-full-base-x86/x.x.x", "semanticVersion": "1.0.0", "components": [ { "componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/2019.12.02/1" }, { "componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/my-imported-component/1.0.0/1" } ] } ``` **Note** To learn more about semantic versioning for Image Builder resources, see [Semantic versioning in Image Builder](ibhow-semantic-versioning.md). ------ #### [ macOS ] The base image (`parentImage` property) in the following example is an AMI. When you use an AMI, you must have access to the AMI, and the AMI must be in the source Region (the same Region where Image Builder runs the command). Save the file as `create-image-recipe.json`, and use it in the **create-image-recipe** command. ``` { "name": "macOS Catalina Image recipe", "description": "Hello World image recipe for macOS.", "parentImage": "ami-1234567890abcdef1", "semanticVersion": "1.0.0", "components": [ { "componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/catalina$" } ], "additionalInstanceConfiguration": { "systemsManagerAgent": { "uninstallAfterBuild": true }, "userDataOverride": "IyEvYmluL2Jhc2gKbWtkaXIgLXAgL3Zhci9iYi8KdG91Y2ggL3Zhcg==" } } ``` ------ **Example: Recipe without components** You can create recipes without any components for testing existing AMIs or distribution-only workflows. The following example shows a recipe that uses an existing AMI without applying any additional components: ``` { "name": "Test Distribution Recipe", "description": "Recipe for testing and distributing existing AMI without modifications.", "parentImage": "ami-1234567890abcdef1", "semanticVersion": "1.0.0", "additionalInstanceConfiguration": { "systemsManagerAgent": { "uninstallAfterBuild": true } } } ``` 1. **Create the recipe** Use the following command to create the recipe. Provide the name of the JSON file that you created in the prior step in the `--cli-input-json` parameter: ``` aws imagebuilder create-image-recipe --cli-input-json file://create-image-recipe.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). Your final image can contain up to four product codes from AWS Marketplace image products and components. If your selected base image and components contain more than four product codes, Image Builder returns an error when run the `create-image-recipe` command. ## Import a VM as your base image in the console In this section, we focus on how to import a virtual machine (VM) as the base image for your image recipe. We don't cover other steps involved with creating a recipe or recipe version here. For additional steps to create a new image recipe with the pipeline creation wizard in the Image Builder console, see [Pipeline wizard: Create AMI](start-build-image-pipeline.md). For additional steps to create a new image recipe or recipe version, see [Create a new version of an image recipe](#create-image-recipes). To import a VM as the base image for your image recipe in the Image Builder console, follow these steps, along with any other required steps, to create your recipe or recipe version. 1. In the **Select image** section for the base image, select the **Import base image** option. 1. Choose the **Image Operating System (OS)** and **OS version** as you normally would. ### VM import configuration When you export your VM from its virtualization environment, that process creates a set of one or more disk container files that act as snapshots of your VM environment, settings, and data. You can use these files to import your VM as the base image for your image recipe. For more information about importing VMs in Image Builder, see [Import and export VM images](vm-import-export.md) To specify the location of your import source, follow these steps: **Import source** Specify the source for the first VM image disk container or snapshot to import in the **Disk container 1** section. 1. **Source** – This can be either an S3 bucket or an EBS snapshot. 1. **Select S3 location of disk** – Enter the location in Amazon S3 where your disk images are stored. To browse for the location, choose **Browse S3**. 1. To add a disk container, choose **Add disk container**. **IAM role** To associate an IAM role with your VM import configuration, select the role from the **IAM role** dropdown list, or choose **Create new role** to create a new one. If you create a new role, the IAM Roles console page opens in a separate tab. #### Advanced settings – *optional* The following settings are optional. With these settings, you can configure encryption, licensing, tags, and more for the base image that the import creates. **General** 1. Specify a unique **Name** for the base image. If you do not enter a value, the base image inherits the recipe name. 1. Specify a **Version** for the base image. Use the following format: `..`. If you do not enter a value, the base image inherits the recipe version. 1. You can also enter a **Description** for the base image. **Base image architecture** To specify the architecture of your VM import source, select a value from the **Architecture** list. **Encryption** If your VM disk images are encrypted, you must provide a key to use for the import process. To specify an AWS KMS key for the import, select a value from the **Encryption (KMS key)** list. The list contains KMS keys that your account has access to in the current Region. **License management** When you import a VM, the import process automatically detects the VM OS and applies the appropriate license to the base image. Depending on your OS platform, the license types are as follows: + **License included** – An appropriate AWS license for your platform is applied to your base image. + **Bring your own license (BYOL)** – Retains the license from your VM, if applicable. To attach license configurations created with AWS License Manager to your base image, select from the **License configuration name** list. For more information about License Manager, see [Working with AWS License Manager]() **Note** License configurations contain licensing rules based on the terms of your enterprise agreements. Linux only supports BYOL licenses. **Tags (base image)** Tags use key-value pairs to assign searchable text to your Image Builder resource. To specify tags for the imported base image, enter key-value pairs with the **Key** and **Value** boxes. To add a tag, choose **Add tag**. To remove a tag, choose **Remove tag**. # Create a new version of a container recipe This section shows you how to create a new version of a container recipe. **Topics** + [ ## Create a new container recipe version with the console ](#create-container-recipe-version) + [ ## Create a container recipe with the AWS CLI ](#create-container-recipe-cli) ## Create a new container recipe version with the console Creating a new version of a container recipe is virtually the same as creating a new recipe. The difference is that certain details are pre-selected to match the base recipe, in most cases. The following list describes the differences between creating a new recipe and creating a new version of an existing recipe. **Recipe details** + **Name** – *not editable*. + **Version** – Required. This detail isn't pre-filled with the current version or any kind of a sequence. Enter the version number that you want to create in the format *major.minor.patch*. If the version already exists, you encounter an error. **Base image** + **Select image** option – Pre-selected, but editable. If you change your choice for the source of your base image, you might lose other details that depend on the original option that you chose. For Docker container images, you can choose from public images hosted on DockerHub, existing container images in Amazon ECR, or Amazon-managed container images. To see details that are associated with your base image selection, choose the tab that matches your selection. ------ #### [ Managed images ] + **Image Operating System (OS)** – *Not editable*. + **Image name** – Pre-selected, based on the combination of base image choices that you made for the existing recipe. However, if you change the **Select image** option, you lose the pre-selected **Image name**. + **Auto-versioning options** – Does *not* match your base recipe. Auto-versioning options defaults to the **Use selected OS version** option. **Important** If you're using semantic versioning to kick off pipeline builds, make sure that you change this value to **Use latest available OS version**. To learn more about semantic versioning for Image Builder resources, see [Semantic versioning in Image Builder](ibhow-semantic-versioning.md). ------ #### [ ECR image ] + **Image Operating System (OS)** – Pre-selected, but editable. + **OS version** – Pre-selected, but editable. + **ECR image ID** – Pre-filled, but editable. ------ #### [ Docker Hub image ] + **Image Operating System (OS)** – *Not editable*. + **OS version** – Pre-selected, but editable. + **Docker image ID** – Pre-filled, but editable. ------ **Instance configuration** + **AMI source** (Required) – Identify a custom AMI to use as the base image for your container build and test instance. This can be an AMI ID or an AWS Systems Manager (SSM) Parameter Store parameter that contains an AMI ID. + **AMI ID** – This setting is not pre-filled with your original entry. Enter the AMI ID for your base image. Example: `ami-1234567890abcdef1`. + **SSM parameter** – Enter the name or ARN of the SSM Parameter Store parameter that contains the AMI ID for your base image. Example: `/ib/test/param` or `arn:aws:ssm:us-east-1:111122223333:parameter/ib/test/param`. + **Storage (volumes)** **EBS volume 1 (AMI root)** – Pre-filled. You can't edit the root volume **Device name**, **Snapshot**, or **IOPS** selections. However, you can change all of the remaining settings, such as the **Size**. You can also add new volumes. **Note** If you specified a base AMI that was shared with you from another account, the snapshots for any secondary volumes that are specified must also be shared with your account. **Working directory** + **Working directory path** – Pre-filled, but editable. **Components** + **Components** – Components that are already included in the recipe are displayed in the **Selected components** section at the end of each of the component lists (build and test). You can remove or reorder the selected components to suit your needs. CIS hardening components don't follow the standard component ordering rules in Image Builder recipes. The CIS hardening components always run last to ensure that the benchmark tests run against your output image. **Note** Build and test component lists display available components based on the component owner type. To add a component, choose **Add build components**, and select the ownership filter that applies. For example, to add a build component that's associated with an AWS Marketplace product, select `AWS Marketplace`. This opens a selection panel on the right side of the console interface that lists AWS Marketplace components. For the CIS component, select `Third party managed`. You can configure the following settings for your selected component: + **Versioning options** – Pre-selected, but you can change them. We recommend that you choose the **Use latest available component version** option to ensure that your image builds always pick up the latest version of the component. If you need to use a specific component version in your recipe, you can choose **Specify component version**, and enter the version in the **Component version** box that appears. + **Input parameters** – Displays input parameters that the component accepts. The **Value** is pre-filled with the value from the prior version of the recipe. If you are using this component for the first time in this recipe, and a default value was defined for the input parameter, the default value appears in the **Value** box with greyed-out text. If no other value is entered, Image Builder uses the default value. If an input parameter is required, but doesn't have a default value defined in the component, you must provide a value. Image Builder won't create the recipe version if there are any required parameters that are missing and don't have a default value defined. **Important** Component parameters are plain text values, and are logged in AWS CloudTrail. We recommend that you use AWS Secrets Manager or the AWS Systems Manager Parameter Store to store your secrets. For more information about Secrets Manager, see [What is Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*. For more information about AWS Systems Manager Parameter Store, see [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) in the *AWS Systems Manager User Guide*. To expand settings for **Versioning options** or **Input parameters**, you can choose the arrow next to the name of the setting. To expand all of the settings for all selected components, you can toggle the **Expand all** switch off and on. **Dockerfile template** + **Dockerfile template** – Pre-filled, but editable. You can specify any of the following contextual variables that Image Builder replaces with build information at runtime.   **parentImage (required)** At build time, this variable resolves to the base image for your recipe. Example: ``` FROM {{{ imagebuilder:parentImage }}} ``` **environments (required if components are specified)** This variable will resolves to a script that runs components. Example: ``` {{{ imagebuilder:environments }}} ``` **components (optional)** Image Builder resolves build and test component scripts for the components that the container recipe includes. This variable can be placed anywhere in the Dockerfile, after the environments variable. Example: ``` {{{ imagebuilder:components }}} ``` **Target repository** + **Target repository name** – The Amazon ECR repository where your output image is stored if there is no other repository specified in your pipeline's distribution configuration for the Region where the pipeline runs (Region 1). **To create a new container recipe version:** 1. At the top of the container recipe details page, choose **Create new version**. You are taken to the **Create recipe** page for container recipes. 1. To create the new version, make your changes, and then choose **Create recipe**. For more information on how to create a container recipe when you create an image pipeline, see [Step 2: Choose recipe](start-build-container-pipeline.md#start-build-container-step2) in the **Get started** section of this guide. ## Create a container recipe with the AWS CLI To create an Image Builder container recipe with the `imagebuilder create-container-recipe` command in the AWS CLI, follow these steps: **Prerequisites** Before you run the Image Builder commands in this section to create a container recipe with the AWS CLI, you must create the components that the recipe will use. The container recipe example in the following step refers to example components that are created in the [Create a custom component from the AWS CLI](create-component.md#create-component-ib-cli) section of this guide. After you create your components, or if you are using existing components, note the ARNs that you want to include in the recipe. 1. **Create a CLI input JSON file** You can provide all of the input for the **create-container-recipe** command with inline command parameters. However, the resulting command can be quite long. To streamline the command, you can instead provide a JSON file that contains all of the container recipe settings **Note** The naming convention for the data values in the JSON file follows the pattern that is specified for the Image Builder API operation request parameters. To review the API operation request parameters, see the [CreateContainerRecipe](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateContainerRecipe.html) command in the *EC2 Image Builder API Reference*. To provide the data values as command line parameters, refer to the parameter names specified in the *AWS CLI Command Reference*. Here is a summary of the parameters in this example: + **components** (array of objects, required) – Contains an array of `ComponentConfiguration` objects. At least one build component must be specified: **Note** Image Builder installs components in the order that you specified them in the recipe. However, CIS hardening components always run last to ensure that the benchmark tests run against your output image. + **componentARN** (string, required) – The component ARN. **Tip** To use the example to create your own container recipe, replace the example ARNs with the ARNs for the components that you are using for your recipe,. These include the AWS Region, name, and the version number for each. + **parameters** (array of objects) – Contains an array of `ComponentParameter` objects. If an input parameter is required, but doesn't have a default value defined in the component, you must provide a value. Image Builder won't create the recipe version if there are any required parameters that are missing and don't have a default value defined. **Important** Component parameters are plain text values, and are logged in AWS CloudTrail. We recommend that you use AWS Secrets Manager or the AWS Systems Manager Parameter Store to store your secrets. For more information about Secrets Manager, see [What is Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*. For more information about AWS Systems Manager Parameter Store, see [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) in the *AWS Systems Manager User Guide*. + **name** (string, required) – The name of the component parameter to set. + **value** (array of strings, required) – Contains an array of strings to set the value for the named component parameter. If there is a default value defined for the component, and no other value is provided, AWSTOE uses the default value. + **containerType** (string, required) – The type of container to create. Valid values include `DOCKER`. + **dockerfileTemplateData** (string) – The Dockerfile template that is used to build your image, expressed as an inline data blob. + **name** (string, required) – The name of the container recipe. + **description** (string) – The description of the container recipe. + **parentImage** (string, required) – The Docker container image to use in the container recipe as a baseline for your customized image. + Public images hosted on DockerHub + Existing container images in Amazon ECR + Amazon-managed container images + **platformOverride** (string) – Specifies the operating system platform when you use a custom base image. + **semanticVersion** (string, required) – The semantic version of the container recipe specified in the following format, with numeric values in each position to indicate a specific version: *..*. An example would be `1.0.0`. To learn more about semantic versioning for Image Builder resources, see [Semantic versioning in Image Builder](ibhow-semantic-versioning.md). + **tags** (string map) – Tags that are attached to the container recipe. + **instanceConfiguration** (object) – A group of options that can be used to configure an instance for building and testing container images. + **image** (string) – The base image for a container build and test instance. This can contain an AMI ID or it can specify an AWS Systems Manager (SSM) Parameter Store parameter, prefixed by `ssm:`, followed by the parameter name or ARN. If you use an SSM parameter, the parameter value must contain an AMI ID. If you don't specify a base image, Image Builder uses the appropriate Amazon ECS optimized AMI as a base image. + **blockDeviceMappings** (array of objects) – Defines the block devices to attach for building an instance from the Image Builder AMI specified in the **image** parameter. + **deviceName** (string) – The device that these mappings apply to. + **ebs** (object) – Used to manage Amazon EBS specific configuration for this mapping. + **deleteOnTermination** (Boolean) – Used to configure delete on termination of the associated device. + **encrypted** (Boolean) – Used to configure device encryption. + **volumeSize** (integer) – Used to override the device's volume size. + **volumeType** (string) – Used to override the device's volume type. + **targetRepository** (object, required) – The destination repository for the container image if there is no other repository specified in your pipeline's distribution configuration for the Region where the pipeline runs (Region 1). + **repositoryName** (string, required) – The name of the container repository where the output container image is stored. This name is prefixed by the repository location. + **service** (string, required) – Specifies the service in which this image was registered. + **workingDirectory** (string) – The working directory for use during build and test workflows. ``` { "components": [ { "componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/helloworldal2/x.x.x" } ], "containerType": "DOCKER", "description": "My Linux Docker container image", "dockerfileTemplateData": "FROM {{{ imagebuilder:parentImage }}}\n{{{ imagebuilder:environments }}}\n{{{ imagebuilder:components }}}", "name": "amazonlinux-container-recipe", "parentImage": "amazonlinux:latest", "platformOverride": "Linux", "semanticVersion": "1.0.2", "tags": { "sometag" : "Tag detail" }, "instanceConfiguration": { "image": "ami-1234567890abcdef1", "blockDeviceMappings": [ { "deviceName": "/dev/xvda", "ebs": { "deleteOnTermination": true, "encrypted": false, "volumeSize": 8, "volumeType": "gp2" } } ] }, "targetRepository": { "repositoryName": "myrepo", "service": "ECR" }, "workingDirectory": "/tmp" } ``` 1. **Create the recipe** Use the following command to create the recipe. Provide the name of the JSON file that you created in the prior step in the `--cli-input-json` parameter: ``` aws imagebuilder create-container-recipe --cli-input-json file://create-container-recipe.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). ## Clean up resources To avoid unexpected charges, make sure to clean up resources and pipelines that you created from the examples in this guide. For more information about deleting resources in Image Builder, see [Delete outdated or unused Image Builder resources](delete-resources.md). # Manage Image Builder infrastructure configuration You can use infrastructure configurations to specify the Amazon EC2 infrastructure that Image Builder uses to build and test your EC2 Image Builder image. Infrastructure settings include: + Instance types for your build and test infrastructure. We recommend that you specify more than one instance type because this allows Image Builder to launch an instance from a pool with sufficient capacity. This can reduce your transient build failures. For Mac images, you might want to choose instance types that natively support the macOS operating system. For more information, see [Amazon EC2 Mac instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-mac-instances.html) in the *Amazon EC2 User Guide*. + Instance placement settings where you can specify the host, host placement group, or Availability Zone where the instances that launch from your image should go. + An instance profile that provides your build and test instances with the permissions that are required to perform customization activities. For example, if you have a component that retrieves resources from Amazon S3, the instance profile requires permissions to access those files. The instance profile also requires a minimal set of permissions for EC2 Image Builder to successfully communicate with the instance. For more information, see [Get set up to build custom images with Image Builder](set-up-ib-env.md). + The VPC, subnet, and security groups for your pipeline's build and test instances. + The Amazon S3 location where Image Builder stores application logs from your build and testing. If you configure logging, the instance profile specified in your infrastructure configuration must have `s3:PutObject` permissions for the target bucket (`arn:aws:s3:::BucketName/*`). + An Amazon EC2 key pair that allows you to log on to your instance to troubleshoot if your build fails and you set `terminateInstanceOnFailure` to `false`. + An SNS topic where Image Builder sends event notifications. For more information about how Image Builder integrates with Amazon SNS, see [Amazon SNS integration in Image Builder](integ-sns.md). **Note** If your SNS topic is encrypted, the key that encrypts this topic must reside in the account where the Image Builder service runs. Image Builder can't send notifications to SNS topics that are encrypted with keys from other accounts. You can create and manage infrastructure configurations using the Image Builder console, through the Image Builder API, or with **imagebuilder** commands in the AWS CLI. **Topics** + [ # List and view infrastructure configuration details ](infra-config-details.md) + [ # Create an infrastructure configuration ](create-infra-config.md) + [ # Update an infrastructure configuration ](update-infra-config.md) + [ # Image Builder and AWS PrivateLink interface VPC endpoints ](vpc-interface-endpoints.md) **Tip** When you have multiple resources of the same type, tagging helps you to identify a specific resource based on the tags you've assigned to it. For more information about tagging your resources using Image Builder commands in the AWS CLI, see the [Tag resources](tag-resources.md) section of this guide. # List and view infrastructure configuration details This section describes the various ways that you can find information and view details for your EC2 Image Builder infrastructure configurations. **Topics** + [ ## List infrastructure configurations from the AWS CLI ](#cli-list-infrastructure-configurations) + [ ## Get infrastructure configuration details from the AWS CLI ](#cli-get-infrastructure-configuration-details) ## List infrastructure configurations from the AWS CLI The following example shows how to list of all of your infrastructure configurations, using the **[list-infrastructure-configurations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/list-infrastructure-configurations.html)** command in the AWS CLI. ``` aws imagebuilder list-infrastructure-configurations ``` ## Get infrastructure configuration details from the AWS CLI The following example shows how use the **[get-infrastructure-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/get-infrastructure-configuration.html)** command in the AWS CLI to get the details of an infrastructure configuration by specifying its Amazon Resource Name (ARN). ``` aws imagebuilder get-infrastructure-configuration --infrastructure-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration ``` # Create an infrastructure configuration This section describes how you can use the Image Builder console or **imagebuilder** commands in the AWS CLI to create an infrastructure configuration, ------ #### [ Console ] To create an infrastructure configuration resource from the Image Builder console, follow these steps: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. From the navigation pane, choose **Infrastructure configuration**. 1. Choose **Create infrastructure configuration**. 1. In the **General** section, enter the following required information: + Enter the **Name** of your infrastructure configuration resource. + Select an **IAM role** that you want to associate with the instance profile for component permissions on your build and test instances. Image Builder uses these permissions to download and run your components, upload logs to CloudWatch, and perform any additional actions that the components in your recipe specify. 1. In the **AWS infrastructure** panel, you can configure remaining infrastructure settings that are available. Enter the following required information: + **Instance type** – You can specify one or more instance types to use for this build. The service will pick one of these instance types based on availability. **Note** Mac instances run on `.metal` instance types on a Dedicated Host. Your instance type must match one of the types that are defined for the host that it runs on. For more information about Mac instances and a list of instance types that natively support the macOS operating system, see [Amazon EC2 Mac instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-mac-instances.html) in the *Amazon EC2 User Guide*. + **SNS topic (optional)** – Select an SNS topic to receive notifications and alerts from EC2 Image Builder. If you do not supply values for the following settings, they use service-specific defaults, where applicable. + **VPC, subnet, and security groups** – Image Builder uses your default VPC and subnet. For more information about configuring VPC interface endpoints, see [Image Builder and AWS PrivateLink interface VPC endpoints](vpc-interface-endpoints.md). + In the **Troubleshooting settings** section, you can configure the following values: + By default, the **Terminate instance on failure** check box is selected. However, when a build fails, you can log on to the EC2 instance to troubleshoot. If you want your instance to continue to run after a build failure, clear the check box. + **Key pair** – If your EC2 instance continues to run after a build failure, you can create a key pair or use an existing key pair to log on to the instance and troubleshoot. + **Logs** – You can specify an S3 bucket where Image Builder can write application logs to help troubleshoot your build and tests. If you don't specify an S3 bucket, Image Builder writes the application logs to the instance. + In the **Instance metadata settings** section, you can configure the following values to apply to the EC2 instances that Image Builder uses to build and test your image: + Select the **Metadata version** to determine if EC2 requires a signed token header for instance metadata retrieval requests. + **V1 and V2 (token optional)** – Default value if you don't select anything. + **V2 (token required)** **Note** We recommend that you configure all EC2 instances that Image Builder launches from a pipeline build to use IMDSv2 so that instance metadata retrieval requests require a signed token header. + **Metadata token response hop limit** – The number of network hops that the metadata token can travel. Minimum hops: 1, maximum hops: 64, with a default of one hop. + In the **Instance placement settings** section, you can configure the following values to apply to the EC2 instances that Image Builder uses to build and test your image: + You can select the **Availability Zone** where Image Builder launches instances during image creation. + Optionally select **Tenancy** for the servers that run the instances that you launch. By default, EC2 instances run on shared tenancy hardware. This means that multiple AWS accounts might share the same physical hardware. An instance with `dedicated` tenancy runs on single-tenant hardware. An instance with `host` tenancy runs on a Dedicated Host. Mac instances require a Dedicated Host that's created as a prerequisite before you build a custom image. Select `host` for your macOS image. You can then select a target host or host resource group to launch instances, but it's not required if your Dedicated Host has auto-placement enabled. For more information, see [Auto-placement](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/dedicated-hosts-understanding.html#dedicated-hosts-auto-placement) in the *Amazon EC2 User Guide*. + **Tenancy host ID** – The ID of the Dedicated Host on which the instances run. + **Tenancy host resource group** – The Amazon Resource Name (ARN) of the host resource group in which to launch the instances. 1. In the **Infrastructure tags** section (optional), you can assign metadata tags to the Amazon EC2 instance that Image Builder launches during the build process. Tags are entered as key value pairs. 1. In the **Tags** section (optional), you can assign metadata tags to the infrastructure configuration resource that Image Builder creates as output. Tags are entered as key value pairs. ------ #### [ AWS CLI ] The following procedure shows how to configure the infrastructure for your image with the Image Builder **[create-infrastructure-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-infrastructure-configuration.html)** command in the AWS CLI. The command in step 2 takes in the file that you create in step 1. For these examples, the file from step 1 is called `create-infrastructure-configuration.json`. 1. **Create a CLI input JSON file** The following examples show variations of the JSON file that you might create for infrastructure configuration. Use a file editing tool to create a JSON file of your own. **Example 1: Configuration to retain an instance from a failed build** This example specifies two instance types, `m5.large` and `m5.xlarge`. We recommend that you specify more than one instance type because this allows Image Builder to launch an instance from a pool with sufficient capacity. This can reduce your transient build failures. The `instanceProfileName` specifies the instance profile that provides the instance with the permissions that the profile requires to perform customization activities. For example, if you have a component that retrieves resources from Amazon S3, the instance profile requires permissions to access those files. The instance profile also requires a minimal set of permissions for EC2 Image Builder to successfully communicate with the instance. For more information, see [Get set up to build custom images with Image Builder](set-up-ib-env.md). ``` { "name": "ExampleInfraConfigDontTerminate", "description": "An example that will retain instances of failed builds", "instanceTypes": [ "m5.large", "m5.xlarge" ], "instanceProfileName": "myIAMInstanceProfileName", "securityGroupIds": [ "sg-12345678" ], "subnetId": "sub-12345678", "logging": { "s3Logs": { "s3BucketName": "my-logging-bucket", "s3KeyPrefix": "my-path" } }, "keyPair": "myKeyPairName", "terminateInstanceOnFailure": false, "snsTopicArn": "arn:aws:sns:us-west-2:123456789012:MyTopic" } ``` **Example 2: macOS configuration with auto-placement** This example specifies instance types and placement for a Mac instance where the Dedicated Host has auto-placement enabled. ``` { "name": "macOSInfraConfigAutoPlacement", "description": "An example infrastructure configuration for macOS.", "instanceProfileName": "EC2InstanceProfileForImageBuilder", "instanceTypes": ["mac1.metal, mac2.metal"], "terminateInstanceOnFailure": false, "placement": { "tenancy": "host" } } ``` **Example 3: macOS configuration with Host ID specified** This example specifies instance type and placement for a Mac instance that targets a specific Dedicated Host. ``` { "name": "macOSInfraConfigHostPlacement", "description": "An example infrastructure configuration for macOS.", "instanceProfileName": "EC2InstanceProfileForImageBuilder", "instanceTypes": ["mac2-m1ultra.metal"], "terminateInstanceOnFailure": false, "placement": { "tenancy": "host", "hostId" : "h-1234567890abcdef0" } } ``` 1. **Use the file you created as input when you run the following command.** ``` aws imagebuilder create-infrastructure-configuration --cli-input-json file://create-infrastructure-configuration.json ``` ------ # Update an infrastructure configuration This section covers how you can use the Image Builder console or **imagebuilder** commands in the AWS CLI to update an infrastructure configuration resource. To track your resources, you can apply tags as follows. Tags are entered as key value pairs. + *Resource tags* assign metadata tags to the Amazon EC2 instance that Image Builder launches during the build process. + *Tags* assign metadata tags to the infrastructure configuration resource that Image Builder creates as output. ------ #### [ Console ] You can edit the following infrastructure configuration details from the Image Builder console: + The **Description** for your infrastructure configuration. + The **IAM role** to associate with the instance profile. + **AWS infrastructure**, including the **Instance type** and an **SNS topic** for notifications. + **VPC, subnet, and security groups**. + **Troubleshooting settings**, including **Terminate instance on failure**, the **Key pair** for connecting, and an optional S3 bucket location for instance logs. To update an infrastructure configuration resource from the Image Builder console, follow these steps: **Choose an existing Image Builder infrastructure configuration** 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. To see a list of the infrastructure configuration resources under your account, choose **Infrastructure configuration** from the navigation pane. 1. To view details or edit an infrastructure configuration, choose the **Configuration name** link. This opens the detail view for the infrastructure configuration. **Note** You can also select the check box next to the **Configuration name**, then choose **View detail**. 1. From the upper right corner of the **Infrastructure details** panel, choose **Edit** . 1. When you're ready to save updates you've made to your infrastructure configuration, choose **Save changes**. ------ #### [ AWS CLI ] The following example shows how to update the infrastructure configuration for your image with the Image Builder **[update-infrastructure-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-infrastructure-configuration.html)** command in the AWS CLI. 1. **Create a CLI input JSON file** This infrastructure configuration example uses the same settings as the create example, except that we've updated the `terminateInstanceOnFailure` setting to `false`. After we run the **update-infrastructure-configuration** command, pipelines that use this infrastructure configuration terminate the build and test instances when the build fails. Use a file editing tool to create a JSON file with keys shown in the following example, plus values that are valid for your environment. This example uses a file named `update-infrastructure-configuration.json`: ``` { "infrastructureConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration", "description": "An example that will terminate instances of failed builds", "instanceTypes": [ "m5.large", "m5.2xlarge" ], "instanceProfileName": "myIAMInstanceProfileName", "securityGroupIds": [ "sg-12345678" ], "subnetId": "sub-12345678", "logging": { "s3Logs": { "s3BucketName": "my-logging-bucket", "s3KeyPrefix": "my-path" } }, "terminateInstanceOnFailure": true, "snsTopicArn": "arn:aws:sns:us-west-2:123456789012:MyTopic" } ``` 1. **Use the file you created as input when you run the following command.** ``` aws imagebuilder update-infrastructure-configuration --cli-input-json file://update-infrastructure-configuration.json ``` ------ # Image Builder and AWS PrivateLink interface VPC endpoints You can establish a private connection between your VPC and EC2 Image Builder by creating an *interface VPC endpoint*. Interface endpoints are powered by [AWS PrivateLink](https://aws.amazon.com/privatelink/), a technology that enables you to privately access Image Builder APIs without an internet gateway, NAT device, VPN connection, or Direct Connect connection. Instances in your VPC don't need public IP addresses to communicate with Image Builder APIs. Traffic between your VPC and Image Builder does not leave the Amazon network. Each interface endpoint is represented by one or more [Elastic Network Interfaces](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) in your subnets. When you create a new image, you can specify the VPC subnet-id in your infrastructure configuration. **Note** Each service that you access from within a VPC has its own interface endpoint, with its own endpoint policy. Image Builder downloads the AWSTOE component manager application and accesses managed resources from S3 buckets to create custom images. To grant access to those buckets, you must update the S3 endpoint policy to allow it. For more information, see [Custom policies for S3 bucket access](#vpc-endpoint-policy-s3). For more information about VPC endpoints, see [Interface VPC endpoints (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html) in the *Amazon VPC User Guide*. ## Considerations for Image Builder VPC endpoints Before you set up an interface VPC endpoint for Image Builder, ensure that you review [Interface endpoint properties and limitations](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#vpce-interface-limitations) in the *Amazon VPC User Guide*. Image Builder supports making calls to all of its API actions from your VPC. ## Create an interface VPC endpoint for Image Builder To create a VPC endpoint for the Image Builder service, you can use either the Amazon VPC console or the AWS Command Line Interface (AWS CLI). For more information, see [Creating an interface endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint) in the *Amazon VPC User Guide*. Create a VPC endpoint for Image Builder using the following service name: + com.amazonaws.*region*.imagebuilder If you enable private DNS for the endpoint, you can make API requests to Image Builder using its default DNS name for the Region, for example: `imagebuilder.us-east-1.amazonaws.com`. To look up the endpoint that applies to your target Region, see [EC2 Image Builder endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/imagebuilder.html#imagebuilder_region) in the *Amazon Web Services General Reference*. For more information, see [Accessing a service through an interface endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#access-service-though-endpoint) in the *Amazon VPC User Guide*. ## Create a VPC endpoint policy for Image Builder You can attach an endpoint policy to your VPC endpoint that controls access to Image Builder. The policy specifies the following information: + The principal that can perform actions. + The actions that can be performed. + The resources on which actions can be performed. If you are using Amazon-managed components in your recipe, the VPC endpoint for Image Builder must allow access to the following serviced-owned component library: `arn:aws:imagebuilder:region:aws:component/*` **Important** When a non-default policy is applied to an interface VPC endpoint for EC2 Image Builder, certain failed API requests, such as those failing from `RequestLimitExceeded`, might not be logged to AWS CloudTrail or Amazon CloudWatch. For more information, see [Controlling access to services with VPC endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html) in the *Amazon VPC User Guide*. ### Custom policies for S3 bucket access Image Builder uses a publicly available S3 bucket to store and access managed resources, such as components. It also downloads the AWSTOE component management application from a separate S3 bucket. If you use a VPC endpoint for Amazon S3 in your environment, you’ll need to ensure that your S3 VPC endpoint policy allows Image Builder to access the following S3 buckets. The bucket names are unique per AWS Region (*region*) and the application environment (*environment*). Image Builder and AWSTOE support the following application environments: `prod`, `preprod`, and `beta`. + The AWSTOE component manager bucket: ``` s3://ec2imagebuilder-toe-region-environment ``` **Example:** s3://ec2imagebuilder-toe-us-west-2-prod/\$1 + The Image Builder managed resources bucket: ``` s3://ec2imagebuilder-managed-resources-region-environment/components ``` **Example:** s3://ec2imagebuilder-managed-resources-us-west-2-prod/components/\$1 ### VPC endpoint policy examples This section includes examples of custom VPC endpoint policies. **General VPC endpoint policy for Image Builder actions** The following example endpoint policy for Image Builder denies permission to delete Image Builder images and components. The example policy also grants permission to perform all other EC2 Image Builder actions. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "imagebuilder:*", "Effect": "Allow", "Resource": "*" }, { "Action": "imagebuilder:DeleteImage", "Effect": "Deny", "Resource": "*" }, { "Action": "imagebuilder:DeleteComponent", "Effect": "Deny", "Resource": "*" } ] } ``` ------ **Restrict access by organization, allow managed component access** The following example endpoint policy shows how to restrict access to identities and resources that belong to your organization and provide access to the Amazon-managed Image Builder components. Replace *region*, *principal-org-id*, and *resource-org-id* with your organization's values. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowRequestsByOrgsIdentitiesToOrgsResources", "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": "*", "Resource": "*", "Condition": { "StringEquals": { "aws:PrincipalOrgID": "principal-org-id", "aws:ResourceOrgID": "resource-org-id" } } }, { "Sid": "AllowAccessToEC2ImageBuilderComponents", "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": [ "imagebuilder:GetComponent" ], "Resource": [ "arn:aws:imagebuilder:us-east-1:aws:component/*" ] } ] } ``` ------ **VPC endpoint policy for Amazon S3 bucket access** The following S3 endpoint policy example shows how to provide access to the S3 buckets that Image Builder uses to build custom images. Replace *region* and *environment* with your organization's values. Add any other required permissions to the policy based on your application requirements. **Note** For Linux images, if you don't specify user data in your image recipe, Image Builder adds a script to download and install the Systems Manager agent on the build and test instances for your image. To download the agent, Image Builder accesses the S3 bucket for your build Region. To ensure that Image Builder can bootstrap the build and test instances, add the following additional resource to your S3 endpoint policy: "`arn:aws:s3:::amazon-ssm-region/*`" ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowImageBuilderAccessToAppAndComponentBuckets", "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::ec2imagebuilder-toe-region-environment/*", "arn:aws:s3:::ec2imagebuilder-managed-resources-region-environment/components/*" ] } ] } ``` ------ # Manage Image Builder distribution settings Before you configure distribution settings for your output images, we recommend that you verify availability for any underlying infrastructure or other requirements for instances that are launched from your output image in the distribution target Regions. For example, not all Regions support EC2 Mac Dedicated Hosts, which are required to launch instances from a macOS image. For more information about instance types and pricing for Dedicated Hosts, see [Amazon EC2 Dedicated Hosts Pricing](https://aws.amazon.com/ec2/dedicated-hosts/pricing/). After you create distribution settings with Image Builder, you can manage them using the Image Builder console, the Image Builder API, or **imagebuilder** commands in the AWS CLI. With distribution settings, you can perform the following actions: **AMI distribution** + Specify the name and description of your output AMI. + Authorize other AWS accounts, organizations, and OUs to launch the AMI from the owner's account. The owner account is billed for charges that are associated with the AMI. **Note** To make an AMI public, set the launch permission authorized accounts to `all`. For information and examples, see **[ModifyImageAttribute](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyImageAttribute.html)** in the *Amazon EC2 API Reference*. + Create a copy of the output AMI for each of the specified target accounts, organizations, and OUs in the destination Region. The target accounts, organizations, and OUs own their AMI copies, and are billed for any associated charges. For more information about distributing your AMI to AWS Organizations and OUs, see [Share an AMI with organizations or OUs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/share-amis-with-organizations-and-OUs.html). + Copy the AMI to the owner's account in other AWS Regions. + Export VM image disks to Amazon Simple Storage Service (Amazon S3). For more information, see [Example: Create distribution settings for output VM disks from the AWS CLI](cr-upd-ami-distribution-settings.md#cli-create-vm-dist-config). **Container image distribution** + Specify the ECR repository where Image Builder stores the output image in the distribution Region. You can use your distribution settings in the following ways to deliver images to target Regions, accounts, AWS Organizations and organizational units (OUs) one time, or with every pipeline build: + To automatically deliver updated images to specified Regions, accounts, Organizations, and OUs, use distribution settings with an Image Builder pipeline that runs on a schedule. + To create a new image and deliver it to the specified Regions, accounts, Organizations, and OUs, use distribution settings with an Image Builder pipeline that you run one time from the Image Builder console, using **Run pipeline** from the **Actions** menu. + To create a new image and deliver it to the specified Regions, accounts, Organizations, and OUs, use distribution settings with the following API action or Image Builder command in the AWS CLI: + The **[CreateImage](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateImage.html)** action in the Image Builder API. + The **[create-image](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-image.html)** command in the AWS CLI. + To export virtual machine (VM) image disks to S3 buckets in target Regions as part of your regular image build process. **Tip** When you have multiple resources of the same type, tagging helps you to identify a specific resource based on the tags you've assigned to it. For more information about tagging your resources using Image Builder commands in the AWS CLI, see the [Tag resources](tag-resources.md) section of this guide. **Topics** + [ # List and view distribution configuration detail ](distribution-settings-detail.md) + [ # Create and update AMI distribution configurations ](cr-upd-ami-distribution-settings.md) + [ # Create and update distribution settings for container images ](cr-upd-container-distribution-settings.md) + [ # Set up cross-account AMI distribution with Image Builder ](cross-account-dist.md) + [ # Configure AMI distribution with an EC2 launch template ](dist-using-launch-template.md) + [ # Use enhanced AMI distribution capabilities ](distribution-enhanced_functionality.md) # List and view distribution configuration detail This section describes the various ways that you can find information and view details for your EC2 Image Builder distribution configuration. **Topics** + [ ## List distribution configurations from the console ](#list-distribution-config-console) + [ ## View distribution configuration details from the console ](#view-distribution-config-details-console) + [ ## List distributions from the AWS CLI ](#cli-list-distributions) + [ ## Get distribution configuration detail from the AWS CLI ](#cli-get-distribution-configuration) ## List distribution configurations from the console To see a list of the distribution configurations created under your account in the Image Builder console, follow these steps: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. Choose **Distribution settings** from the navigation pane. This shows a list of the distribution configurations that are created under your account. 1. To view details or create new distribution configuration, choose the **Configuration name** link. This opens the detail view for the distribution settings. **Note** You can also select the check box next to the **Configuration name**, then choose **View details**. ## View distribution configuration details from the console To view details for a specific distribution configuration using the Image Builder console, select the configuration to review, using the steps described in [List distribution configurations from the console](#list-distribution-config-console). On the distribution detail page, you can: + **Delete** the distribution configuration. For more information about deleting resources in Image Builder, see [Delete outdated or unused Image Builder resources](delete-resources.md). + **Edit** distribution details. ## List distributions from the AWS CLI The following example shows how to use the **[list-distribution-configurations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/list-distribution-configurations.html)** command in the AWS CLI to list all of your distributions. ``` aws imagebuilder list-distribution-configurations ``` ## Get distribution configuration detail from the AWS CLI The following example shows how to use the **[get-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/get-distribution-configuration.html)** command in the AWS CLI to get the details of a distribution configuration by specifying its Amazon Resource Name (ARN). ``` aws imagebuilder get-distribution-configuration --distribution-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-example-distribution-configuration ``` # Create and update AMI distribution configurations This section covers creating and updating distribution configurations for an Image Builder AMI. **Topics** + [ ## AMI distribution prerequisites ](#ami-distribution-config-prereqs) + [ ## Create an AMI distribution configuration ](#create-ami-distribution-config) + [ ## Update an AMI distribution configuration ](#update-ami-distribution-config) + [ ## Example: Enable EC2 Fast Launch with a launch template for output AMIs ](#create-ami-dist-win-fast-launch) + [ ## Example: Create distribution settings for output VM disks from the AWS CLI ](#cli-create-vm-dist-config) ## AMI distribution prerequisites Some distribution settings have prerequisites, as follows: **Topics** + [SSM output parameter prerequisites](#ami-distribution-prereqs-ssm-param) + [EC2 Fast Launch prerequisites](#ami-distribution-prereqs-fast-launch) ### Prerequisites for SSM output parameters Before you create a new AMI distribution configuration that sets an AWS Systems Manager Parameter Store parameter (SSM parameter), ensure that you've met the following prerequisites. **Execution role** When you create a pipeline or use the create-image command in the AWS CLI, you can only specify one Image Builder execution role. If you have defined an Image Builder workflow execution role, you would add any additional feature permissions to that role. Otherwise, you would create a new custom role that includes the required permissions. + To store the output AMI ID in an SSM parameter during distribution, you must specify the `ssm:PutParameter` action in your Image Builder execution role, with the parameter listed as a resource. + When you set the parameter data type to `AWS EC2 Image` to signal Systems Manager to validate the parameter value as an AMI ID, you must also add the `ec2:DescribeImages` action. ### Prerequisites for EC2 Fast Launch Before you create a new distribution configuration for EC2 Fast Launch for Windows AMIs, ensure that you've met the following prerequisites. + If you provide a custom launch template when you configure EC2 Fast Launch, the service uses the VPC and other configuration settings that you've defined in the launch template. For more information, see [Use a launch template when you set up EC2 Fast Launch](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/win-fast-launch-configure.html#win-fast-launch-with-template). + If you don't use a custom launch template to configure your settings, you must attach the [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-iam-awsmanpol-EC2FastLaunchFullAccess.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-iam-awsmanpol-EC2FastLaunchFullAccess.html) policy to the IAM role that Image Builder uses to create your image. When you create a pipeline or use the create-image command in the AWS CLI, you can only specify one Image Builder execution role. If you have defined an Image Builder workflow execution role, you would add any additional feature permissions to that role. Otherwise, you would create a new custom role that includes the required permissions. Then, when Image Builder copies your image, EC2 Fast Launch automatically creates an CloudFormation stack with the following resources in your AWS account. + A virtual private cloud (VPC) + Private subnets across multiple Availability Zones + A launch template configured with Instance Metadata Service Version 2 (IMDSv2) + A security group with no inbound or outbound rules **Note** Image Builder doesn't support cross-account distribution for AMIs with EC2 Fast Launch pre-enabled. EC2 Fast Launch must be enabled from the destination account. ## Create an AMI distribution configuration Distribution configurations include the output AMI name, specific Region settings for encryption, launch permissions, and AWS accounts, organizations, and organizational units (OUs) that can launch the output AMI, and license configurations. A distribution configuration allows you to specify the name and description of your output AMI, authorize other AWS accounts to launch the AMI, copy the AMI to other accounts, and replicate the AMI to other AWS Regions. It also allows you to export the AMI to Amazon Simple Storage Service (Amazon S3), or configure EC2 Fast Launch for output Windows AMIs. To make an AMI public, set the launch permission authorized accounts to `all`. See the examples for making an AMI public at EC2 **[ModifyImageAttribute](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyImageAttribute.html)**. ------ #### [ Console ] Follow these steps to create a new AMI distribution configuration in the AWS Management Console: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. Choose **Distribution settings** from the navigation pane. This shows a list of the distribution configurations that are created under your account. 1. Choose **Create distribution settings** near the top of the **Distribution settings** panel. 1. In the **Image type** section, choose the **Amazon Machine Image (AMI)** output type. 1. In the **General** section, enter a **Name** for your distribution configuration, and optional description. 1. In the **Region settings** section, enter the following details for each Region where you are distributing your AMI: 1. The AMI is distributed to the current Region (**Region 1**), by default. **Region 1** is the source for the distribution. Some settings for **Region 1** are not open for editing. For any Regions that you add, you can choose a Region from the **Region** dropdown list. The **Kms key** identifies the AWS KMS key that's used to encrypt the EBS volumes for your image in the target Region. It's important to note that this doesn't apply for the original AMI that the build creates under your account in the source Region (**Region 1**). Encryption that runs during the distribution phase of the build is only for images that are distributed to other accounts or Regions. To encrypt the EBS volumes for the AMI that's created in the source Region for your account, you must set the KMS key in the image recipe block device mapping (**Storage (volumes)** in the console). Image Builder copies the AMI to the **Target accounts** that you specify for the Region. **Prerequisite** To copy an image across accounts, you must create the `EC2ImageBuilderDistributionCrossAccountRole` role in all of the distribution target accounts, and attach the [Ec2ImageBuilderCrossAccountDistributionAccess policy](security-iam-awsmanpol.md#sec-iam-manpol-Ec2ImageBuilderCrossAccountDistributionAccess) managed policy to the role. The **Output AMI name** is optional. If you provide a name, the final output AMI name includes an appended timestamp of when the AMI is built. If you do not specify a name, Image Builder appends the build timestamp to the recipe name. This ensures unique AMI names for each build. 1. With AMI sharing, you can grant access for specified AWS Principals to launch instances from your AMI. If you expand the **AMI sharing** section, you can enter the following details: + **Launch permissions** – Select **Private** if you want to keep your AMI private, and allow access for specific AWS Principals to launch an instance from your private AMI. Select **Public** if you want to make your AMI public. Any AWS Principal can launch an instance from your public AMI. + **Principals** – You can grant access for the following types of AWS Principals to launch instances: + **AWS account** – Grant access to a specific AWS account + **Organizational unit (OU)** – Grant access to an OU, and all of its child entities. Child entities include OUs and AWS accounts. + **Organization** – Grant access to your AWS Organizations, and all of its child entities. Child entities include OUs and AWS accounts. First, select the Principal type. Then enter the ID for the AWS Principal to which you want to grant access in the box to the right of the drop-down list. You can enter multiple IDs of different types. 1. You can expand the **License configuration** section to attach license configurations created with AWS License Manager to your Image Builder images. License configurations contain licensing rules based on the terms of your enterprise agreements. Image Builder automatically includes license configurations that were associated with your base AMI. 1. You can expand the **Launch template configuration** section to specify an EC2 launch template to use for launching instances from the AMI you create. If you are using an EC2 launch template, you can instruct Image Builder to create a new version of your launch template that includes the latest AMI ID after the build completes. To update the launch template, configure the settings as follows: + **Launch template name** – Select the name of the launch template that you want Image Builder to update. + **Set the default version** – Select this check box to update the launch template default version to the new version. To add another launch template configuration, choose **Add launch template configuration**. You can have up to five launch template configurations per Region. 1. You can expand the **SSM parameter configurations** section to configure an SSM parameter that will store the output AMI ID for the image that's distributed to the destination Region. You can optionally specify a distribution account in the Region. **Parameter name** – Enter the name for your parameter. For example `/output/image/param`. **Data type** – Keep the default value (`AWS EC2 Image`). This tells Systems Manager to validate the parameter value to ensure that it's a valid AMI ID. 1. To add distribution settings for another Region, choose **Add Region**. 1. Choose **Create settings** when you are done. ------ #### [ AWS CLI ] The following example shows how to use the **create-distribution-configuration** command to create a new distribution configuration for your AMI, using the AWS CLI. 1. **Create a CLI input JSON file** Use a file-editing tool to create a JSON file with keys shown in one of the following examples, and values that are valid for your environment. These examples define which AWS accounts, AWS Organizations or organizational units (OUs) have permission to launch the AMI you distribute to the specified Regions. Name the file `create-ami-distribution-configuration.json`, for use in the next step: **Example 1: Distribute to AWS accounts** This example distributes an AMI to two Regions, and specifies AWS accounts that have launch permissions in each Region. ``` { "name": "MyExampleAccountDistribution", "description": "Copies AMI to eu-west-1, and specifies accounts that can launch instances in each Region.", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "name": "Name {{imagebuilder:buildDate}}", "description": "An example image name with parameter references", "amiTags": { "KeyName": "Some Value" }, "launchPermission": { "userIds": [ "987654321012" ] } } }, { "region": "eu-west-1", "amiDistributionConfiguration": { "name": "My {{imagebuilder:buildVersion}} image {{imagebuilder:buildDate}}", "amiTags": { "KeyName": "Some value" }, "launchPermission": { "userIds": [ "100000000001" ] } } } ] } ``` **Example 2: Distribute to Organizations and OUs** This example distributes an AMI to the source Region, and specifies organization and OU launch permissions. ``` { "name": "MyExampleAWSOrganizationDistribution", "description": "Shares AMI with the Organization and OU", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "name": "Name {{ imagebuilder:buildDate }}", "launchPermission": { "organizationArns": [ "arn:aws:organizations::123456789012:organization/o-myorganization123" ], "organizationalUnitArns": [ "arn:aws:organizations::123456789012:ou/o-123example/ou-1234-myorganizationalunit" ] } } } ] } ``` **Example 3: Store the output AMI ID in an SSM parameter** This example stores the output AMI ID in an AWS Systems Manager Parameter Store parameter in the distribution Region. ``` { "name": "SSMParameterOutputAMI", "description": "Updates an SSM parameter with the output AMI ID for the distribution.", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "name": "Name {{ imagebuilder:buildDate }}" }, "ssmParameterConfigurations": [ { "amiAccountId": "111122223333", "parameterName": "/output/image/param", "dataType": "aws:ec2:image" } ] } ] } ``` 1. **Run the following command, using the file you created as input.** ``` aws imagebuilder create-distribution-configuration --cli-input-json file://create-ami-distribution-configuration.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). For more detailed information, see **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** in the *AWS CLI Command Reference*. ------ ## Update an AMI distribution configuration You can change your AMI distribution configuration. However, the changes you make do not apply to any resources that Image Builder has already distributed. For example, if you have distributed an AMI to a Region that you later remove from your distribution, the AMI that was already distributed remains in that Region until you remove it manually. ------ #### [ AWS Management Console ] Follow these steps to an AMI distribution configuration in the AWS Management Console: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. Choose **Distribution settings** from the navigation pane. This shows a list of the distribution configurations that are created under your account. 1. To view details or update a distribution configuration, choose the **Configuration name** link. This opens the detail view for the distribution settings. **Note** You can also select the check box next to the **Configuration name**, then choose **View details**. 1. To edit distribution configuration, choose **Edit** from the upper right corner of the **Distribution details** section. Some fields are locked, such as the **Name** of the distribution configuration, and the default **Region** that is displayed as **Region 1**. For more information about the distribution configuration settings, see [Create an AMI distribution configuration](#create-ami-distribution-config). 1. Choose **Save changes** when you are done. ------ #### [ AWS CLI ] The following example shows how to use the **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** command to update distribution settings for your AMI, using the AWS CLI. 1. **Create a CLI input JSON file** Use a file-editing tool to create a JSON file with the keys shown in the following example, and values that are valid for your environment. This example uses a file named `update-ami-distribution-configuration.json`. ``` { "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/update-ami-distribution-configuration.json", "description": "Copies AMI to eu-west-2, and specifies accounts that can launch instances in each Region.", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "name": "Name {{imagebuilder:buildDate}}", "description": "An example image name with parameter references", "launchPermissions": { "userIds": [ "987654321012" ] } } }, { "region": "eu-west-2", "amiDistributionConfiguration": { "name": "My {{imagebuilder:buildVersion}} image {{imagebuilder:buildDate}}", "tags": { "KeyName": "Some value" }, "launchPermissions": { "userIds": [ "100000000001" ] } } } ] } ``` 1. **Run the following command, using the file you created as input.** ``` aws imagebuilder update-distribution-configuration --cli-input-json file://update-ami-distribution-configuration.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). For more detailed information, see **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** in the *AWS CLI Command Reference*. To update tags for your distribution configuration resource, see the [Tag resources](tag-resources.md) section. ------ ## Example: Enable EC2 Fast Launch with a launch template for output AMIs The following example shows how to use the **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** command with a launch template to create distribution settings that have EC2 Fast Launch configured for your AMI, from the AWS CLI. To configure EC2 Fast Launch settings without a launch template, ensure that you've met all of the [EC2 Fast Launch prerequisites](#ami-distribution-prereqs-fast-launch) before you create your distribution configuration. 1. **Create a CLI input JSON file** Use a file editing tool to create a JSON file with keys as shown in the following example, plus values that are valid for your environment. This example launches instances for all of its target resources simultaneously, because the maximum number of parallel launches is greater than the target resource count. This file is named `ami-dist-config-win-fast-launch.json` in the command example shown in the next step. ``` { "name": "WinFastLaunchDistribution", "description": "An example of Windows AMI EC2 Fast Launch settings in the distribution configuration.", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "name": "Name {{imagebuilder:buildDate}}", "description": "Includes Windows AMI EC2 Fast Launch settings.", "amiTags": { "KeyName": "Some Value" } }, "fastLaunchConfigurations": [{ "enabled": true, "snapshotConfiguration": { "targetResourceCount": 5 }, "maxParallelLaunches": 6, "launchTemplate": { "launchTemplateId": "lt-0ab1234c56d789012", "launchTemplateVersion": "1" } }], "launchTemplateConfigurations": [{ "launchTemplateId": "lt-0ab1234c56d789012", "setDefaultVersion": true }] }] } ``` **Note** You can specify the `launchTemplateName` instead of the `launchTemplateId` in the `launchTemplate` section, but you can't specify both the name and Id. 1. **Run the following command, using the file you created as input.** ``` aws imagebuilder create-distribution-configuration --cli-input-json file://ami-dist-config-win-fast-launch.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). For more detailed information, see **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** in the *AWS CLI Command Reference*. ## Example: Create distribution settings for output VM disks from the AWS CLI The following example shows how to use the **create-distribution-configuration** command to create distribution settings that will export VM image disks to Amazon S3 with every image build. 1. **Create a CLI input JSON file** You can streamline the **create-distribution-configuration** command that you use in the AWS CLI. To do this, create a JSON file that contains all of the export configuration that you want to pass into the command. **Note** The naming convention for the data values in the JSON file follows the pattern that is specified for the Image Builder API operation request parameters. To review the API operation request parameters, see the **[CreateDistributionConfiguration](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateDistributionConfiguration.html)** command in the *EC2 Image Builder API Reference*. To provide the data values as command line parameters, refer to the parameter names specified in the *AWS CLI Command Reference*. to the **create-distribution-configuration** command as options. Here is a summary of the parameters that we specify in the `s3ExportConfiguration` JSON object for this example: + **roleName** (string, required) – The name of the role that grants VM Import/Export permission to export images to your S3 bucket. + **diskImageFormat** (string, required) – Export the updated disk image to one of the following supported formats: + **Virtual Hard Disk (VHD)** – Compatible with Citrix Xen and Microsoft Hyper-V virtualization products. + **Stream-optimized ESX Virtual Machine Disk (VMDK)** – Compatible with VMware ESX and VMware vSphere versions 4, 5, and 6. + **Raw** – Raw format. + **s3Bucket** (string, required) – The S3 bucket in which to store the output disk images for your VM. Save the file as `export-vm-disks.json`. Use the file name in the **create-distribution-configuration** command. ``` { "name": "example-distribution-configuration-with-vm-export", "description": "example", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "description": "example-with-vm-export" }, "s3ExportConfiguration": { "roleName": "vmimport", "diskImageFormat": "RAW", "s3Bucket": "vm-bucket-export" } }], "clientToken": "abc123def4567ab" } ``` 1. **Run the following command, using the file you created as input.** ``` aws imagebuilder create-distribution-configuration --cli-input-json file://export-vm-disks.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). For more detailed information, see **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** in the *AWS CLI Command Reference*. # Create and update distribution settings for container images This section covers creating and updating distribution settings for Image Builder container images. **Topics** + [ ## Create distribution settings for Image Builder container images from the AWS CLI ](#cli-create-container-distribution-configuration) + [ ## Update distribution settings for your container image from the AWS CLI ](#cli-update-container-distribution-configuration) ## Create distribution settings for Image Builder container images from the AWS CLI A distribution configuration enables you to specify the name and description of your output container image and replicate the container image to other AWS Regions. You can also apply separate tags to the distribution configuration resource and to the container images within each Region. 1. **Create a CLI input JSON file** Use your favorite file-editing tool to create a JSON file with the keys shown in the following example, plus values that are valid for your environment. This example uses a file named `create-container-distribution-configuration.json`: ``` { "name": "distribution-configuration-name", "description": "Distributes container image to Amazon ECR repository in two regions.", "distributions": [ { "region": "us-west-2", "containerDistributionConfiguration": { "description": "My test image.", "targetRepository": { "service": "ECR", "repositoryName": "testrepo" }, "containerTags": ["west2", "image1"] } }, { "region": "us-east-1", "containerDistributionConfiguration": { "description": "My test image.", "targetRepository": { "service": "ECR", "repositoryName": "testrepo" }, "containerTags": ["east1", "imagedist"] } } ], "tags": { "DistributionConfigurationTestTagKey1": "DistributionConfigurationTestTagValue1", "DistributionConfigurationTestTagKey2": "DistributionConfigurationTestTagValue2" } } ``` 1. **Run the following command, using the file you created as input.** ``` aws imagebuilder create-distribution-configuration --cli-input-json file://create-container-distribution-configuration.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). For more detailed information, see **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** in the *AWS CLI Command Reference*. ## Update distribution settings for your container image from the AWS CLI The following example shows how to use the **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** command to update distribution settings for your container image, using the AWS CLI. You can also update tags for the container images within each Region. 1. **Create a CLI input JSON file** Use your favorite file-editing tool to create a JSON file with keys shown in the following example, plus values that are valid for your environment. This example uses a file named `update-container-distribution-configuration.json`: ``` { "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/update-container-distribution-configuration.json", "description": "Distributes container image to Amazon ECR repository in two regions.", "distributions": [ { "region": "us-west-2", "containerDistributionConfiguration": { "description": "My test image.", "targetRepository": { "service": "ECR", "repositoryName": "testrepo" }, "containerTags": ["west2", "image1"] } }, { "region": "us-east-2", "containerDistributionConfiguration": { "description": "My test image.", "targetRepository": { "service": "ECR", "repositoryName": "testrepo" }, "containerTags": ["east2", "imagedist"] } } ] } ``` 1. **Run the following command, using the file you created as input:** ``` aws imagebuilder update-distribution-configuration --cli-input-json file://update-container-distribution-configuration.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). For more detailed information, see **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** in the *AWS CLI Command Reference*. To update tags for your distribution configuration resource, see the [Tag resources](tag-resources.md) section. # Set up cross-account AMI distribution with Image Builder This section describes how you can configure distribution settings to deliver an Image Builder AMI to other accounts that you specify. The destination account can then launch or modify the AMI, as needed. **Note** AWS CLI command examples in this section assume that you have previously created image recipe and infrastructure configuration JSON files. To create the JSON file for an image recipe, see [Create an image recipe with the AWS CLI](create-image-recipes.md#create-image-recipe-cli). To create the JSON file for an infrastructure configuration, see [Create an infrastructure configuration](create-infra-config.md). ## Prerequisites for cross-account AMI distribution To ensure that target accounts can successfully launch instances from your Image Builder image, you must configure the appropriate permissions for all destination accounts in all Regions. If you encrypt your AMI using AWS Key Management Service (AWS KMS), you must configure an AWS KMS key for your account that is used to encrypt the new image. When Image Builder performs cross-account distribution for encrypted AMIs, the image in the source account is decrypted and pushed to the target Region, where it is re-encrypted using the designated key for that Region. Because Image Builder acts on behalf of the target account, and uses an IAM role that you create in the destination Region, that account must have access to keys in both the source and destination Regions. ### Encryption keys The following prerequisites are required if your image is encrypted using AWS KMS. IAM prerequisites are covered in the next section. **Source account requirements** + Create a KMS key in your account in all Regions where you build and distribute your AMI. You can also use an existing key. + Update the key policy for all of those keys to allow destination accounts to use your key. **Destination account requirements** + Add an inline policy to `EC2ImageBuilderDistributionCrossAccountRole` that allows the role to perform the required actions to distribute an encrypted AMI. For IAM configuration steps, see the [IAM policies](#cross-account-prereqs-iam) prerequisites section. For more information about cross-account access using AWS KMS, see [Allowing users in other accounts to use a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying-external-accounts.html) in the *AWS Key Management Service Developer Guide*. Specify your encryption key in the image recipe, as follows: + If you are using the Image Builder console, choose your encryption key from the **Encryption (KMS alias)** dropdown list in the **Storage (volumes)** section of your recipe. + If you are using the **CreateImageRecipe** API action, or the **create-image-recipe** command in the AWS CLI, configure your key in the `ebs` section under `blockDeviceMappings` in your JSON input. The following JSON snippet shows encryption settings for an image recipe. In addition to providing your encryption key, you must also set the `encrypted` flag to `true`. ``` { ... "blockDeviceMappings": [ { "deviceName": "Example root volume", "ebs": { "deleteOnTermination": true, "encrypted": true, "iops": 100, "kmsKeyId": "image-owner-key-id", ... }, ... }], ... } ``` ### IAM policies To configure cross-account distribution permissions in AWS Identity and Access Management (IAM), follow these steps: 1. To use Image Builder AMIs that are distributed across accounts, the destination account owner must create a new IAM role in their account called `EC2ImageBuilderDistributionCrossAccountRole`. 1. They must attach the [Ec2ImageBuilderCrossAccountDistributionAccess policy](security-iam-awsmanpol.md#sec-iam-manpol-Ec2ImageBuilderCrossAccountDistributionAccess) to the role to enable cross-account distribution. For more information about managed policies, see [Managed Policies and Inline Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) in the *AWS Identity and Access Management User Guide*. 1. Verify that the source account ID is added to the trust policy attached to the IAM role of the destination account. The following example shows a trust policy in the destination account that specifies the account ID from the source account. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:root" }, "Action": "sts:AssumeRole" }] } ``` ------ For more information about trust policies, see [Resource-Based Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_resource-based) in the *AWS Identity and Access Management User Guide*. 1. If the AMI you distribute is encrypted, the destination account owner must add the following inline policy to the `EC2ImageBuilderDistributionCrossAccountRole` in their account so that they can use your KMS keys. The `Principal` section contains their account number. This enables Image Builder to act on their behalf when it uses AWS KMS to encrypt and decrypt the AMI with the appropriate keys for each Region. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowRoleToPerformKMSOperationsOnBehalfOfTheDestinationAccount", "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey", "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": "*" } ] } ``` ------ For more information about inline policies, see [Inline Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#inline-policies) in the *AWS Identity and Access Management User Guide*. 1. If you are using `launchTemplateConfigurations` to specify an Amazon EC2 launch template, you must also add the following policy to your `EC2ImageBuilderDistributionCrossAccountRole` in each destination account. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ec2:CreateLaunchTemplateVersion", "ec2:ModifyLaunchTemplate" ], "Resource": "*", "Condition": { "StringEquals": { "aws:ResourceTag/CreatedBy": "EC2 Image Builder" } } }, { "Effect": "Allow", "Action": [ "ec2:DescribeLaunchTemplates" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:CreateTags" ], "Resource": "arn:aws:ec2:*:*:launch-template/*", "Condition": { "StringEquals": { "aws:RequestTag/CreatedBy": "EC2 Image Builder" } } } ] } ``` ------ 1. If you use an AWS Systems Manager Parameter Store parameter to store the AMI ID of the output AMI for the distribution account and Region, you must add the following policy to your `EC2ImageBuilderDistributionCrossAccountRole` in each destination account. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:PutParameter" ], "Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*" }, { "Effect": "Allow", "Action": [ "ec2:DescribeImages" ], "Resource": "*" } ] } ``` ------ ## Limits for cross-account distribution There are some limitations when distributing Image Builder images across accounts: + The destination account is limited to 50 concurrent AMI copies for each destination Region. + If you want to copy a paravirtual (PV) virtualization AMI to another Region, the destination Region must support PV virtualization AMIs. For more information, see [Linux AMI virtualization types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/virtualization_types.html). + You cannot create an unencrypted copy of an encrypted snapshot. If you don't specify an AWS Key Management Service (AWS KMS) customer managed key for the `KmsKeyId` parameter, Image Builder uses the default key for Amazon Elastic Block Store (Amazon EBS). For more information, see [Amazon EBS Encryption](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html) in the *Amazon Elastic Compute Cloud User Guide*. For more information, see [CreateDistributionConfiguration](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateDistributionConfiguration.html) in the *EC2 Image Builder API Reference*. ## Configure cross-account distribution for an Image Builder AMI from the console This section describes how to create and configure distribution settings for cross-account distribution of your Image Builder AMIs using the AWS Management Console. Configuring cross-account distribution requires specific IAM permissions. You must complete the [Prerequisites for cross-account AMI distribution](#cross-account-dist-prereqs) for this section before you continue. To create distribution settings in the Image Builder console, follow these steps: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. Choose **Distribution settings** from the navigation pane. This shows a list of the distribution settings that are created under your account. 1. At the top of the **Distribution settings** page, choose **Create distribution settings**. This takes you to the **Create distribution settings** page. 1. In the **Image type** section, choose **Amazon Machine Image (AMI)** as the **Output type**. This is the default setting. 1. In the **General** section, enter the **Name** of the distribution settings resource that you want to create (*required*). 1. In the **Region settings** section, enter a 12-digit account ID that you want to distribute your AMI to in **Target accounts** for the selected Region, and press **Enter**. This checks for the correct formatting, and then displays the account ID that you entered below the box. Repeat the process to add more accounts. To remove an account that you entered, choose the **X** displayed to the right of the account ID. Enter the **Output AMI name** for each Region. 1. Continue specifying any additional settings that you require, and choose **Create settings** to create your new distribution settings resource. ## Configure cross-account distribution for an Image Builder AMI from the AWS CLI This section describes how to configure a distribution settings file and use the **create-image** command in the AWS CLI to build and distribute an Image Builder AMI across accounts. Configuring cross-account distribution requires specific IAM permissions. You must complete the [Prerequisites for cross-account AMI distribution](#cross-account-dist-prereqs) for this section before you run the **create-image** command. 1. **Configure a distribution settings file** Before you use the **create-image** command in the AWS CLI to create an Image Builder AMI that is distributed to another account, you must create a `DistributionConfiguration` JSON structure that specifies the target account IDs in the `AmiDistributionConfiguration` settings. You must specify at least one `AmiDistributionConfiguration` in the source Region. The following sample file, named `create-distribution-configuration.json`, shows configuration for cross-account image distribution in the source Region. ``` { "name": "cross-account-distribution-example", "description": "Cross Account Distribution Configuration Example", "distributions": [ { "amiDistributionConfiguration": { "targetAccountIds": ["123456789012", "987654321098"], "name": "Name {{ imagebuilder:buildDate }}", "description": "ImageCopy Ami Copy Configuration" }, "region": "us-west-2" } ] } ``` 1. **Create the distribution settings** To create an Image Builder distribution settings resource using the [create-distribution-configuration](https://docs.aws.amazon.com/cli/latest/reference/imagebuilder/create-distribution-configuration.html) command in the AWS CLI, provide the following parameters in the command: + Enter the name of the distribution in the `--name` parameter. + Attach the distribution configuration JSON file you created in the `--cli-input-json` parameter. ``` aws imagebuilder create-distribution-configuration --name my distribution name --cli-input-json file://create-distribution-configuration.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). *You can also provide JSON directly in the command, using the `--distributions` parameter.* # Configure AMI distribution with an EC2 launch template To help ensure a consistent launch experience for your Image Builder AMI in target accounts and Regions, you can specify an Amazon EC2 launch template in your distribution settings, using `launchTemplateConfigurations`. When `launchTemplateConfigurations` are present during the distribution process, Image Builder creates a new version of the launch template that includes all of the original settings from the template, and the new AMI ID from the build. For more information about launching an EC2 instance using a launch template, see one of the following links, depending on your target operating system. + [Launch a Linux instance from a launch template](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-templates.html) + [Launch a Windows instance from a launch template](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-templates.html) **Note** When you include a launch template to enable Windows Fast Launch in your image, the launch template must include the following tag so that Image Builder can enable Windows Fast Launch on your behalf. `CreatedBy: EC2 Image Builder` ## Add an EC2 launch template to AMI distribution settings from the console To provide a launch template with your output AMI, follow these steps in the console: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. Choose **Distribution settings** from the navigation pane. This shows a list of the distribution settings that are created under your account. 1. At the top of the **Distribution settings** page, choose **Create distribution settings**. This opens the **Create distribution settings** page. 1. In the **Image type** section, choose the **Amazon Machine Image (AMI)** **Output type**. This is the default setting. 1. In the **General** section, enter the **Name** of the distribution settings resource that you want to create (*required*). 1. In the **Region settings** section, select the name of an EC2 launch template from the list. If there are no launch templates in your account, choose **Create new launch template**, which opens the **Launch Templates** in the **EC2 Dashboard**. Select the **Set the default version** check box to update the launch template default version to the new version that Image Builder creates with your output AMI. To add another launch template to the selected Region, choose **Add launch template configuration**. To remove a launch template, choose **Remove**. 1. Continue specifying any additional settings that you require, and choose **Create settings** to create your new distribution settings resource. ## Add an EC2 launch template to AMI distribution settings from the AWS CLI This section describes how to configure a distribution settings file with a launch template, and use the **create-image** command in the AWS CLI to build and distribute an Image Builder AMI and a new version of the launch template that uses it. 1. **Configure a distribution settings file** Before you can create an Image Builder AMI with a launch template, using the AWS CLI, you must create a distribution configuration JSON structure that specifies the `launchTemplateConfigurations` settings. You must specify at least one `launchTemplateConfigurations` entry in the source Region. The following sample file, named `create-distribution-config-launch-template.json`, shows a few possible scenarios for launch template configuration in the source Region. ``` { "name": "NewDistributionConfiguration", "description": "This is just a test", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "name": "test-{{imagebuilder:buildDate}}-{{imagebuilder:buildVersion}}", "description": "description" }, "launchTemplateConfigurations": [ { "launchTemplateId": "lt-0a1bcde2fgh34567", "accountId": "935302948087", "setDefaultVersion": true }, { "launchTemplateId": "lt-0aaa1bcde2ff3456" }, { "launchTemplateId": "lt-12345678901234567", "accountId": "123456789012" } ] } ], "clientToken": "clientToken1" } ``` 1. **Create the distribution settings** To create an Image Builder distribution settings resource using the [create-distribution-configuration](https://docs.aws.amazon.com/cli/latest/reference/imagebuilder/create-distribution-configuration.html) command in the AWS CLI, provide the following parameters in the command: + Enter the name of the distribution in the `--name` parameter. + Attach the distribution configuration JSON file you created in the `--cli-input-json` parameter. ``` aws imagebuilder create-distribution-configuration --name my distribution name--cli-input-json file://create-distribution-config-launch-template.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). *You can also provide JSON directly in the command, using the `--distributions` parameter.* # Use enhanced AMI distribution capabilities Image Builder offers advanced distribution capabilities that give you flexibility and control over how your AMIs are distributed across regions and accounts. These capabilities separate distribution from the build process, allowing you to distribute existing images on demand, recover from distribution failures efficiently, and implement controlled, multi-stage distribution strategies through customizable workflows. You can use enhanced AMI distribution capabilities in Image Builder to directly perform distribution activities without the need to re-run a complete image build. ## Decoupled Distribution The DistributeImage API accepts three types of source image references: + **AMI ID** – A standard AMI identifier (for example, `ami-0abcdef1234567890`) + **SSM Parameter** – An SSM parameter that stores an AMI ID (for example, `ssm:/my/ami/parameter`) + **Image Builder version ARN** – An Image Builder image version ARN ## Distribution Retry If an image distribution fails, use the `RetryImage` API to retry distribution. This reduces time to troubleshoot the cause of the failure by avoiding a complete image rebuild. Use `RetryImage` after resolving the underlying cause of the distribution failure. The RetryImage API accepts an image build version ARN (for example, `arn:aws:imagebuilder:us-west-2:123456789012:image/my-image/1.0.0/1`). When you invoke the API, Image Builder automatically resumes the distribution process from the point of failure using the original distribution configuration and settings. The `RetryImage` API can retry distributions that failed during the distribution phase, test phase, or integration phase. It works with AMIs in the following states: pending, failed, deleted, or available. **Prerequisites** Before retrying a distribution, ensure the following: + You have identified and resolved the root cause of the failure. Review distribution logs in CloudWatch Logs for error details. + You have the necessary IAM permissions to retry the image build. + For cross-account distribution failures, verify that the `EC2ImageBuilderDistributionCrossAccountRole` in the destination account has the `Ec2ImageBuilderCrossAccountDistributionAccess` policy attached. **Important:** Retrying without fixing the underlying issue will result in repeated failures. ## Distribution Workflows Distribution workflows are a new workflow type that complement build and test workflows, enabling you to define and control the distribution process with sequential steps. With distribution workflows, you can create custom distribution processes that include AMI copy operations, wait-for-action checkpoints, image attribute modifications, and other distribution-related steps. This provides structured control over how your AMIs are distributed, with step-level visibility, parallel distribution capabilities, and granular error reporting. To learn more about creating and customizing workflows, see [Manage Image Workflows](manage-image-workflows.html).