AWS imagebuilder: Image Builder distribution config: SSM parameter constraints and OU sharing
Summary
Clarifies Systems Manager parameter validation rules for AMI IDs (aws:ec2:image dataType, ec2:DescribeImages and ssm:GetParameter permissions, text dataType to skip validation, per-account uniqueness), documents EC2 Fast Launch as same-account-only, corrects the KMS key wording, and adds a new Example 4 that shares an AMI with an organizational unit and updates a launch template. Also includes formatting/link cleanups and an ARN typo fix.
Security assessment
The change documents required IAM permissions (ec2:DescribeImages, ssm:GetParameter) for AMI-ID parameter validation and shows launchPermission with organizationalUnitArns for OU-wide AMI sharing; these are authorization/permission-boundary and sharing-control considerations, but the text documents existing service behavior rather than addressing a specific vulnerability or incident.
Evidence
* If the parameter already exists in your account, it must be a `String` type parameter, and its data type must match the `dataType` that you specify. Otherwise, Image Builder rejects the distribution configuration. Image Builder checks this with your credentials when you create or update the distribution configuration, so you need `ssm:GetParameter` for the parameter. Image Builder doesn't check parameters in other accounts at that time.
Diff
diff --git a/imagebuilder/latest/userguide/cr-upd-ami-distribution-settings.md b/imagebuilder/latest/userguide/cr-upd-ami-distribution-settings.md index cc01573..7d6c716 100644 --- a//imagebuilder/latest/userguide/cr-upd-ami-distribution-settings.md +++ b//imagebuilder/latest/userguide/cr-upd-ami-distribution-settings.md @@ -56 +56,13 @@ We recommend that you don't pass the [AWSServiceRoleForImageBuilder](./security- - * 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. + * When the parameter data type is `aws:ec2:image` (the default if you omit `dataType`), Systems Manager validates the parameter value as an AMI ID, so you must also add the `ec2:DescribeImages` action. + + + + +**Parameter constraints** + + + * To skip AMI ID validation, set the data type to `text`. + + * If the parameter already exists in your account, it must be a `String` type parameter, and its data type must match the `dataType` that you specify. Otherwise, Image Builder rejects the distribution configuration. Image Builder checks this with your credentials when you create or update the distribution configuration, so you need `ssm:GetParameter` for the parameter. Image Builder doesn't check parameters in other accounts at that time. + + * The account that the parameter belongs to (`amiAccountId`, or your own account if you omit it) must be one of the Region's target distribution accounts. Parameter names must be unique per target account in each Region. @@ -109 +121 @@ Then, when Image Builder copies your image, EC2 Fast Launch automatically create -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. +EC2 Fast Launch configurations are same-account only. You can specify at most one fast launch configuration per account in a Region. Image Builder doesn't support cross-account distribution for AMIs with EC2 Fast Launch pre-enabled. Image Builder enables fast launch only on the AMI that your account owns in the destination Region. For AMI copies that Image Builder distributes to other accounts, enable fast launch from the account that owns the copy. @@ -115 +127 @@ Distribution configurations include the output AMI name, specific Region setting -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)**. +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). @@ -136 +148 @@ Follow these steps to create a new AMI distribution configuration in the AWS Man -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. +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. @@ -284,0 +297,39 @@ This example stores the output AMI ID in an AWS Systems Manager Parameter Store +###### Example 4: Share with an OU and update a launch template + +This example assumes that you run the build in `us-west-2`. It copies the AMI to `eu-west-1`, shares the AMI with an organizational unit in both Regions, and creates a new version of an Amazon EC2 launch template in `us-west-2` that references the new AMI ID. + + { + "name": "OrgShareWithLaunchTemplate", + "description": "Shares the AMI with an OU and updates a launch template.", + "distributions": [ + { + "region": "us-west-2", + "amiDistributionConfiguration": { + "name": "AppImage {{ imagebuilder:buildDate }}", + "launchPermission": { + "organizationalUnitArns": [ + "arn:aws:organizations::123456789012:ou/o-123example/ou-1234-myorganizationalunit" + ] + } + }, + "launchTemplateConfigurations": [ + { + "launchTemplateId": "lt-0ab1234c56d789012", + "setDefaultVersion": true + } + ] + }, + { + "region": "eu-west-1", + "amiDistributionConfiguration": { + "name": "AppImage {{ imagebuilder:buildDate }}", + "launchPermission": { + "organizationalUnitArns": [ + "arn:aws:organizations::123456789012:ou/o-123example/ou-1234-myorganizationalunit" + ] + } + } + } + ] + } + @@ -295 +346 @@ This example stores the output AMI ID in an AWS Systems Manager Parameter Store -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_. +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_. @@ -304 +355 @@ You can change your AMI distribution configuration. However, the changes you mak -AWS Management Console +Console @@ -307 +358 @@ AWS Management Console -Follow these steps to an AMI distribution configuration in the AWS Management Console: +Follow these steps to update an AMI distribution configuration in the AWS Management Console: @@ -329 +380 @@ 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. +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. @@ -336 +387 @@ Use a file-editing tool to create a JSON file with the keys shown in the followi - "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/update-ami-distribution-configuration.json", + "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/update-ami-distribution-configuration", @@ -378 +429 @@ Use a file-editing tool to create a JSON file with the keys shown in the followi -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. +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. @@ -385 +436 @@ For more detailed information, see **[update-distribution-configuration](https:/ -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. +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. @@ -393 +444,3 @@ Use a file editing tool to create a JSON file with keys as shown in the followin -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. +This file is named `ami-dist-config-win-fast-launch.json` in the command example shown in the next step. + +`maxParallelLaunches` caps how many instances EC2 Fast Launch launches at the same time to build the pre-provisioned snapshots, and `targetResourceCount` is the number of snapshots to keep on hand. In this example, `maxParallelLaunches` is greater than `targetResourceCount`, so Amazon EC2 launches instances for all of the target resources at the same time. If `targetResourceCount` is higher than `maxParallelLaunches`, Amazon EC2 first launches `maxParallelLaunches` instances, and then launches more as those instances finish, until it reaches the target resource count. `maxParallelLaunches` must be 6 or greater. @@ -440 +493 @@ You can specify the `launchTemplateName` instead of the `launchTemplateId` in th -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_. +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_. @@ -455 +508 @@ You can streamline the **create-distribution-configuration** command that you us -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_. +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_. @@ -504 +557 @@ Save the file as `export-vm-disks.json`. Use the file name in the **create-distr -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_. +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_.