AWS imagebuilder documentation change
Summary
Added prerequisites for SSM parameters, restructured AMI distribution configuration documentation, added SSM parameter configuration examples, and removed redundant CLI update section
Security assessment
Added prerequisites section specifies required IAM permissions (ssm:PutParameter, ec2:DescribeImages) for secure SSM parameter storage of AMI IDs. While this improves security documentation, there's no evidence of addressing a specific vulnerability.
Diff
diff --git a/imagebuilder/latest/userguide/cr-upd-ami-distribution-settings.md b/imagebuilder/latest/userguide/cr-upd-ami-distribution-settings.md index 8de6e346f..17d4ca13d 100644 --- a//imagebuilder/latest/userguide/cr-upd-ami-distribution-settings.md +++ b//imagebuilder/latest/userguide/cr-upd-ami-distribution-settings.md @@ -5 +5 @@ -Create an AMI distribution configuration from the consoleCreate distribution settings for output AMIs from the AWS CLIUpdate AMI distribution settings from the consoleCreate distribution settings to enable EC2 Fast Launch for output AMIsCreate distribution settings for output VM disks from the AWS CLIUpdate AMI distribution settings from the AWS CLI +Prerequisites for SSM output parametersCreate an AMI distribution configurationUpdate an AMI distribution configurationCreate distribution settings to enable EC2 Fast Launch for output AMIsCreate distribution settings for output VM disks from the AWS CLI @@ -13 +13 @@ This section covers creating and updating distribution configurations for an Ima - * Create an AMI distribution configuration from the console + * Prerequisites for SSM output parameters @@ -15 +15 @@ This section covers creating and updating distribution configurations for an Ima - * Create distribution settings for output AMIs from the AWS CLI + * Create an AMI distribution configuration @@ -17 +17 @@ This section covers creating and updating distribution configurations for an Ima - * Update AMI distribution settings from the console + * Update an AMI distribution configuration @@ -23 +22,0 @@ This section covers creating and updating distribution configurations for an Ima - * Update AMI distribution settings from the AWS CLI @@ -26,0 +26 @@ This section covers creating and updating distribution configurations for an Ima +## Prerequisites for SSM output parameters @@ -28 +28,15 @@ This section covers creating and updating distribution configurations for an Ima -## Create an AMI distribution configuration from the console +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. + + + + +## Create an AMI distribution configuration @@ -32 +46,6 @@ Distribution configurations include the output AMI name, specific Region setting -###### To create a new AMI distribution configuration: +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: @@ -85,0 +105,6 @@ To add another launch template configuration, choose **Add launch template confi + 4. 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. + @@ -93 +118 @@ To add another launch template configuration, choose **Add launch template confi -## Create distribution settings for output AMIs from the AWS CLI +AWS CLI @@ -95 +119,0 @@ To add another launch template configuration, choose **Add launch template confi -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)**. @@ -103,2 +127 @@ Use a file-editing tool to create a JSON file with keys shown in one of the foll -Accounts - +###### Example 1: Distribute to AWS accounts @@ -144,2 +167 @@ This example distributes an AMI to two Regions, and specifies AWS accounts that -Organizations and OUs - +###### Example 2: Distribute to Organizations and OUs @@ -169,0 +192,24 @@ This example distributes an AMI to the source Region, and specifies organization +###### 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" + } + ] + } + ] + } + @@ -185 +231,3 @@ For more detailed information, see **[create-distribution-configuration](https:/ -## Update AMI distribution settings from the console +## 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. @@ -187 +235 @@ For more detailed information, see **[create-distribution-configuration](https:/ -You can change your AMI distribution settings using the Image Builder console. The updated distribution settings are used for all automated and manual pipeline deployments going forward. 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 @@ -189 +237,2 @@ You can change your AMI distribution settings using the Image Builder console. T -###### Update AMI distribution configuration + +Follow these steps to an AMI distribution configuration in the AWS Management Console: @@ -201 +250 @@ You can also select the check box next to the **Configuration name** , then choo - 4. 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 from the console. + 4. 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. @@ -207,0 +257,57 @@ You can also select the check box next to the **Configuration name** , then choo +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" + ] + } + } + } + ] + } + + 2. ###### 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 (\\) 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.html) section. + + + + @@ -336,56 +441,0 @@ For more detailed information, see **[create-distribution-configuration](https:/ -## Update AMI distribution settings 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 AMI, using the AWS CLI. - - 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 `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" - ] - }