AWS imagebuilder: Add PowerShell examples and IMDSv2 guidance to infra config
Summary
Restructures the Image Builder infrastructure configuration guide: moves the IMDSv2 recommendation note to the top of the page, adds Auto Scaling group parent-instance options (execution role, capacity wait timeout) and a terminate-on-completion note, adds a new 'Build on an instance from an Auto Scaling group' JSON example, and adds a full PowerShell (New-EC2IBInfrastructureConfiguration) section whose examples set InstanceMetadataOptions_HttpToken to required. Also refreshes example names and placeholder values (account IDs, bucket names, key pair names).
Security assessment
The change documents the IMDSv2 hardening recommendation (signed token header for instance metadata, mitigating SSRF-style credential theft via IMDSv1) and adds PowerShell examples that explicitly set '-InstanceMetadataOptions_HttpToken required' plus a hop limit. It also documents the execution role used for Auto Scaling group builds. This is security best-practice documentation rather than a fix for a specific vulnerability or incident, so it is not security_issue_related.
Evidence
+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.
Diff
diff --git a/imagebuilder/latest/userguide/create-infra-config.md b/imagebuilder/latest/userguide/create-infra-config.md index 21d502b..e8bf373 100644 --- a//imagebuilder/latest/userguide/create-infra-config.md +++ b//imagebuilder/latest/userguide/create-infra-config.md @@ -9 +9,5 @@ -This section describes how you can use the Image Builder console or **imagebuilder** commands in the AWS CLI to create an infrastructure configuration. +This section describes how to create an infrastructure configuration. You can use the Image Builder console, **imagebuilder** commands in the AWS CLI, or AWS Tools for PowerShell. + +###### 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. @@ -37,0 +42,6 @@ Mac instances run on `.metal` instance types on a Dedicated Host. Your instance + * **Auto Scaling group (optional)** – Choose a group to build on an instance that's already running in it. Leave this field empty to launch a new instance for every build. For more information, see [Build on an instance from an Auto Scaling group](./infra-config-parent-instance.html). After you choose a group, these fields appear: + + * **Execution role for this group** – Choose **Create new role with required permission** , and then select that role as the execution role for your pipeline. This option isn't available in the AWS GovCloud (US) Regions or the China Regions. + + * **Capacity wait timeout** – How long, from 0 to 3600 seconds, Image Builder waits for an instance in the group before the build fails. + @@ -45,0 +56,2 @@ If you do not supply values for the following settings, they use service-specifi + * By default, the **Terminate instance on completion** check box is selected. To keep your instance when image creation ends without a failure, clear the check box. For AMI builds, Image Builder stops the instance to create the image, so the instance you keep is stopped. + @@ -58,4 +69,0 @@ If you do not supply values for the following settings, they use service-specifi -###### 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. - @@ -86 +94 @@ 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`. +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`. @@ -90,4 +97,0 @@ The following example sets common infrastructure fields. To require IMDSv2 token -###### 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. - @@ -98 +102 @@ The following examples show variations of the JSON file that you might create fo -**Example 1: Configuration to retain an instance from a failed build** +###### Configuration to retain an instance from a failed build @@ -103,0 +108,2 @@ The `instanceProfileName` specifies the instance profile that provides the insta +The following example JSON file defines this infrastructure configuration: + @@ -105 +111 @@ The `instanceProfileName` specifies the instance profile that provides the insta - "name": "ExampleInfraConfigDontTerminate", + "name": "example-infra-config-dont-terminate", @@ -110 +116 @@ The `instanceProfileName` specifies the instance profile that provides the insta - "instanceProfileName": "myIAMInstanceProfileName", + "instanceProfileName": "my-iam-instance-profile-name", @@ -117 +123 @@ The `instanceProfileName` specifies the instance profile that provides the insta - "s3BucketName": "my-logging-bucket", + "s3BucketName": "amzn-s3-demo-logging-bucket", @@ -121 +127 @@ The `instanceProfileName` specifies the instance profile that provides the insta - "keyPair": "myKeyPairName", + "keyPair": "my-key-pair-name", @@ -123 +129 @@ The `instanceProfileName` specifies the instance profile that provides the insta - "snsTopicArn": "arn:aws:sns:us-west-2:123456789012:MyTopic" + "snsTopicArn": "arn:aws:sns:us-west-2:111122223333:my-topic" @@ -126 +132 @@ The `instanceProfileName` specifies the instance profile that provides the insta -###### Example 2: macOS configuration with auto-placement +###### macOS configuration with auto-placement @@ -129,0 +136,2 @@ This example specifies instance types and placement for a Mac instance where the +The following example JSON file defines this infrastructure configuration: + @@ -131 +139 @@ This example specifies instance types and placement for a Mac instance where the - "name": "macOSInfraConfigAutoPlacement", + "name": "macos-infra-config-auto-placement", @@ -141 +149 @@ This example specifies instance types and placement for a Mac instance where the -###### Example 3: macOS configuration with Host ID specified +###### macOS configuration with host ID specified @@ -144,0 +153,2 @@ This example specifies instance type and placement for a Mac instance that targe +The following example JSON file defines this infrastructure configuration: + @@ -146 +156 @@ This example specifies instance type and placement for a Mac instance that targe - "name": "macOSInfraConfigHostPlacement", + "name": "macos-infra-config-host-placement", @@ -157 +167 @@ This example specifies instance type and placement for a Mac instance that targe -###### Example 4: Custom VPC with IMDSv2 and Amazon S3 logging +###### Custom VPC with IMDSv2 and Amazon S3 logging @@ -160,0 +171,2 @@ This example launches instances in a specific subnet and security group, require +The following example JSON file defines this infrastructure configuration: + @@ -162 +174 @@ This example launches instances in a specific subnet and security group, require - "name": "VpcInfraConfigWithLogging", + "name": "vpc-infra-config-with-logging", @@ -174 +186 @@ This example launches instances in a specific subnet and security group, require - "s3BucketName": "my-logging-bucket", + "s3BucketName": "amzn-s3-demo-logging-bucket", @@ -184 +196 @@ This example launches instances in a specific subnet and security group, require -###### Example 5: Dedicated Host placement with a host resource group +###### Dedicated Host placement with a host resource group @@ -187,0 +200,2 @@ This example targets a host resource group instead of a specific host ID. Becaus +The following example JSON file defines this infrastructure configuration: + @@ -189 +203 @@ This example targets a host resource group instead of a specific host ID. Becaus - "name": "HostResourceGroupInfraConfig", + "name": "host-resource-group-infra-config", @@ -195 +209,18 @@ This example targets a host resource group instead of a specific host ID. Becaus - "hostResourceGroupArn": "arn:aws:resource-groups:us-west-2:123456789012:group/my-host-group" + "hostResourceGroupArn": "arn:aws:resource-groups:us-west-2:111122223333:group/my-host-group" + } + } + +###### Build on an instance from an Auto Scaling group + +This example takes the build instance from an existing Amazon EC2 Auto Scaling group and waits up to 10 minutes for an instance if the group has none available. For the requirements, see [Build on an instance from an Auto Scaling group](./infra-config-parent-instance.html). + +The following example JSON file defines this infrastructure configuration: + + { + "name": "parent-instance-infra-config", + "instanceProfileName": "EC2InstanceProfileForImageBuilder", + "parentInstance": { + "autoScalingGroup": { + "name": "my-build-pool", + "capacityWaitTimeoutSeconds": 600 + } @@ -205,0 +237,93 @@ This example targets a host resource group instead of a specific host ID. Becaus +PowerShell + + +The following examples show how to use the [New-EC2IBInfrastructureConfiguration](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2IBInfrastructureConfiguration.html) cmdlet to create an infrastructure configuration. They use the same settings as the AWS CLI examples. + +Tools for PowerShell doesn't take a JSON input file. Instead, most top-level JSON keys map to a cmdlet parameter of the same name, sometimes in singular form, such as `InstanceType`. Each nested setting becomes a parameter named after its parent object and the setting. For example, `logging.s3Logs.s3BucketName` becomes `S3Logs_S3BucketName`, and `placement.tenancy` becomes `Placement_Tenancy`. Array values are comma-separated lists, and tag maps are hashtables. + +The following examples set common infrastructure fields. To require IMDSv2 tokens on the build and test instances, set the `InstanceMetadataOptions_HttpToken` parameter to `required`. + +###### Configuration to retain an instance from a failed build + +This example specifies two instance types, `m7i.large` and `m7i.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` parameter 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.html). + +The following example creates this infrastructure configuration: + + + New-EC2IBInfrastructureConfiguration -Name example-infra-config-dont-terminate ` + -Description "An example that will retain instances of failed builds" ` + -InstanceType m7i.large, m7i.xlarge ` + -InstanceProfileName my-iam-instance-profile-name ` + -SecurityGroupId sg-12345678 ` + -SubnetId subnet-12345678 ` + -S3Logs_S3BucketName amzn-s3-demo-logging-bucket ` + -S3Logs_S3KeyPrefix my-path ` + -KeyPair my-key-pair-name ` + -TerminateInstanceOnFailure $false ` + -SnsTopicArn arn:aws:sns:us-west-2:111122223333:my-topic + +###### macOS configuration with auto-placement + +This example specifies instance types and placement for a Mac instance where the Dedicated Host has auto-placement enabled. + +The following example creates this infrastructure configuration: + + + New-EC2IBInfrastructureConfiguration -Name macos-infra-config-auto-placement ` + -Description "An example infrastructure configuration for macOS." ` + -InstanceProfileName EC2InstanceProfileForImageBuilder ` + -InstanceType mac1.metal, mac2.metal ` + -TerminateInstanceOnFailure $false ` + -Placement_Tenancy host + +###### macOS configuration with host ID specified + +This example specifies instance type and placement for a Mac instance that targets a specific Dedicated Host. + +The following example creates this infrastructure configuration: + + + New-EC2IBInfrastructureConfiguration -Name macos-infra-config-host-placement ` + -Description "An example infrastructure configuration for macOS." ` + -InstanceProfileName EC2InstanceProfileForImageBuilder ` + -InstanceType mac2-m1ultra.metal ` + -TerminateInstanceOnFailure $false ` + -Placement_Tenancy host ` + -Placement_HostId h-1234567890abcdef0 + +###### Custom VPC with IMDSv2 and Amazon S3 logging + +This example launches instances in a specific subnet and security group, requires IMDSv2 tokens, and writes application logs to Amazon S3. Because the example sets the `SubnetId` parameter, it must also set `SecurityGroupId`. + +The following example creates this infrastructure configuration: + + + New-EC2IBInfrastructureConfiguration -Name vpc-infra-config-with-logging ` + -Description "Build in a custom VPC with IMDSv2 and S3 logging" ` + -InstanceType m7i.large, m8i.large ` + -InstanceProfileName EC2InstanceProfileForImageBuilder ` + -SubnetId subnet-12345678 ` + -SecurityGroupId sg-12345678 ` + -InstanceMetadataOptions_HttpToken required ` + -InstanceMetadataOptions_HttpPutResponseHopLimit 2 ` + -S3Logs_S3BucketName amzn-s3-demo-logging-bucket ` + -S3Logs_S3KeyPrefix image-builder-logs ` + -ResourceTag @{ Project = "golden-ami" } ` + -TerminateInstanceOnFailure $true + +###### Dedicated Host placement with a host resource group + +This example targets a host resource group instead of a specific host ID. Because `Placement_Tenancy` is `host`, you can specify a host resource group ARN. Don't also specify `Placement_HostId`. + +The following example creates this infrastructure configuration: +