feat(imagebuilder-alpha): add support for Distribution Configuration Construct #36005

tarunb12 · 2025-11-11T05:22:43Z

Issue

Reason for this change

This change adds a new alpha module for EC2 Image Builder L2 Constructs (@aws-cdk/aws-imagebuilder-alpha), as outlined in aws/aws-cdk-rfcs#789. This PR specifically implements the DistributionConfiguration construct.

Description of changes

This change implements the DistributionConfiguration construct, which is a higher-level construct of CfnDistributionConfiguration.

Example

const distributionConfiguration = new imagebuilder.DistributionConfiguration(this, 'DistributionConfiguration', {
  distributionConfigurationName: 'test-distribution-configuration',
  description: 'A Distribution Configuration',
  amiDistributions: [
    {
      // Distribute AMI to us-east-2 and publish the AMI ID to an SSM parameter
      region: 'us-east-2',
      ssmParameters: [
        {
          parameter: ssm.StringParameter.fromStringParameterAttributes(this, 'CrossRegionParameter', {
            parameterName: '/imagebuilder/ami',
            forceDynamicReference: true
          })
        }
      ]
    }
  ]
});

// For AMI-based image builds - add an AMI distribution in the current region
distributionConfiguration.addAmiDistributions({
  amiName: 'imagebuilder-{{ imagebuilder:buildDate }}',
  amiDescription: 'Build AMI',
  amiKmsKey: kms.Key.fromLookup(this, 'ComponentKey', { aliasName: 'alias/distribution-encryption-key' }),
  // Copy the AMI to different accounts
  amiTargetAccountIds: ['123456789012', '098765432109'],
  // Add launch permissions on the AMI
  amiLaunchPermission: {
    organizationArns: [
      this.formatArn({ region: '', service: 'organizations', resource: 'organization', resourceName: 'o-1234567abc' })
    ],
    organizationalUnitArns: [
      this.formatArn({
        region: '',
        service: 'organizations',
        resource: 'ou',
        resourceName: 'o-1234567abc/ou-a123-b4567890'
      })
    ],
    userGroups: ['all'],
    userIds: ['234567890123']
  },
  // Attach tags to the AMI
  amiTags: {
    Environment: 'production',
    Version: '{{ imagebuilder:buildVersion }}'
  },
  // Optional - publish the distributed AMI ID to an SSM parameter
  ssmParameters: [
    {
      parameter: ssm.StringParameter.fromStringParameterAttributes(this, 'Parameter', {
        parameterName: '/imagebuilder/ami',
        forceDynamicReference: true
      })
    },
    {
      amiAccount: '098765432109',
      dataType: ssm.ParameterDataType.TEXT,
      parameter: ssm.StringParameter.fromStringParameterAttributes(this, 'CrossAccountParameter', {
        parameterName: 'imagebuilder-prod-ami',
        forceDynamicReference: true
      })
    }
  ],
  // Optional - create a new launch template version with the distributed AMI ID
  launchTemplates: [
    {
      launchTemplate: ec2.LaunchTemplate.fromLaunchTemplateAttributes(this, 'LaunchTemplate', {
        launchTemplateName: 'imagebuilder-ami'
      }),
      setDefaultVersion: true
    },
    {
      accountId: '098765432109',
      launchTemplate: ec2.LaunchTemplate.fromLaunchTemplateAttributes(this, 'CrossAccountLaunchTemplate', {
        launchTemplateName: 'imagebuilder-cross-account-ami'
      }),
      setDefaultVersion: true
    }
  ],
  // Optional - enable Fast Launch on an imported launch template
  fastLaunchConfigurations: [
    {
      enabled: true,
      launchTemplate: ec2.LaunchTemplate.fromLaunchTemplateAttributes(this, 'FastLaunchLT', {
        launchTemplateName: 'fast-launch-lt'
      }),
      maxParallelLaunches: 10,
      targetSnapshotCount: 2
    }
  ],
  // Optional - license configurations to apply to the AMI
  licenseConfigurationArns: [
    'arn:aws:license-manager:us-west-2:123456789012:license-configuration:lic-abcdefghijklmnopqrstuvwxyz'
  ]
});

Describe any new or updated permissions being added

N/A - new L2 construct in alpha module

Description of how you validated changes

Validated with unit tests and integration tests. Manually verified generated CFN templates as well.

Checklist

My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

packages/@aws-cdk/aws-imagebuilder-alpha/lib/distribution-configuration.ts

Pull request has been modified.

packages/@aws-cdk/aws-imagebuilder-alpha/lib/distribution-configuration.ts

Pull request has been modified.

packages/@aws-cdk/aws-imagebuilder-alpha/lib/distribution-configuration.ts

Pull request has been modified.

packages/@aws-cdk/aws-imagebuilder-alpha/lib/distribution-configuration.ts

...ages/@aws-cdk/aws-imagebuilder-alpha/test/integ.all-parameters.distribution-configuration.ts

packages/@aws-cdk/aws-imagebuilder-alpha/lib/distribution-configuration.ts

kumsmrit · 2025-11-18T11:24:27Z

@Mergifyio refresh

mergify · 2025-11-18T11:24:44Z

refresh

✅ Pull request refreshed

kumsmrit · 2025-11-18T11:26:32Z

@Mergifyio queue

mergify · 2025-11-18T11:26:39Z

queue

🟠 Waiting for conditions to match

any of: [🔀 queue conditions]
- all of: [📌 queue conditions of queue default-merge]
  - label~=no-squash
  - any of:
    - -label~=pr/needs-integration-tests-deployment
    - check-success=Deploy integration test snapshots (requires pr/needs-integration-tests-deployment label)
  - #approved-reviews-by >= 1 [🛡 GitHub branch protection]
  - #approved-reviews-by>=1
  - #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  - #changes-requested-reviews-by=0
  - -approved-reviews-by~=author
  - -closed
  - -label~=(blocked|do-not-merge)
  - -merged
  - -title~=(WIP|wip)
  - check-success=build
  - check-success=validate-pr
  - any of: [🛡 GitHub branch protection]
    - check-success = validate-pr
    - check-neutral = validate-pr
    - check-skipped = validate-pr
  - any of: [🛡 GitHub branch protection]
    - check-success = build
    - check-neutral = build
    - check-skipped = build
- all of: [📌 queue conditions of queue default-squash]
  - any of:
    - -label~=pr/needs-integration-tests-deployment
    - check-success=Deploy integration test snapshots (requires pr/needs-integration-tests-deployment label)
  - #approved-reviews-by >= 1 [🛡 GitHub branch protection]
  - #approved-reviews-by>=1
  - #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  - #changes-requested-reviews-by=0
  - -approved-reviews-by~=author
  - -closed
  - -label~=(blocked|do-not-merge|no-squash|priority-pr)
  - -merged
  - -title~=(WIP|wip)
  - base!=release
  - check-success=build
  - check-success=validate-pr
  - any of: [🛡 GitHub branch protection]
    - check-success = validate-pr
    - check-neutral = validate-pr
    - check-skipped = validate-pr
  - any of: [🛡 GitHub branch protection]
    - check-success = build
    - check-neutral = build
    - check-skipped = build
- all of: [📌 queue conditions of queue priority-squash]
  - label~=priority-pr
  - any of:
    - -label~=pr/needs-integration-tests-deployment
    - check-success=Deploy integration test snapshots (requires pr/needs-integration-tests-deployment label)
  - #approved-reviews-by >= 1 [🛡 GitHub branch protection]
  - #approved-reviews-by>=1
  - #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  - #changes-requested-reviews-by=0
  - -approved-reviews-by~=author
  - -closed
  - -label~=(blocked|do-not-merge|no-squash)
  - -merged
  - -title~=(WIP|wip)
  - base!=release
  - check-success=build
  - check-success=validate-pr
  - any of: [🛡 GitHub branch protection]
    - check-success = validate-pr
    - check-neutral = validate-pr
    - check-skipped = validate-pr
  - any of: [🛡 GitHub branch protection]
    - check-success = build
    - check-neutral = build
    - check-skipped = build
-closed [📌 queue requirement]
-conflict [📌 queue requirement]
-draft [📌 queue requirement]
any of: [📌 queue -> configuration change requirements]
- -mergify-configuration-changed
- check-success = Configuration changed

kumsmrit · 2025-11-18T11:49:07Z

@Mergifyio queue

mergify · 2025-11-18T11:49:11Z

Pull request has been modified.

kumsmrit · 2025-11-18T13:27:31Z

@Mergifyio queue

kumsmrit · 2025-11-18T13:36:38Z

@Mergifyio refresh

kumsmrit · 2025-11-18T15:18:19Z

@Mergifyio queue

mergify · 2025-11-18T15:18:25Z

kumsmrit · 2025-11-18T16:06:03Z

@Mergifyio queue

mergify · 2025-11-18T16:13:42Z

ozelalisen · 2025-11-18T16:15:40Z

@Mergifyio requeue

mergify · 2025-11-18T16:15:49Z

requeue

☑️ This pull request is already queued

ozelalisen · 2025-11-18T16:16:19Z

@Mergifyio update

mergify · 2025-11-18T16:16:25Z

update

✅ Branch has been successfully updated

mergify · 2025-11-18T16:51:16Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

github-actions · 2025-11-18T16:51:33Z

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.

aws-cdk-automation requested a review from a team November 11, 2025 05:22

github-actions bot added p2 beginning-contributor [Pilot] contributed between 0-2 PRs to the CDK labels Nov 11, 2025

aws-cdk-automation added the pr/needs-further-review PR requires additional review from our team specialists due to the scope or complexity of changes. label Nov 11, 2025

tarunb12 force-pushed the imagebuilder-distribution branch 3 times, most recently from 1de77fb to cfde029 Compare November 11, 2025 06:41

tarunb12 marked this pull request as ready for review November 11, 2025 09:30

kumsmrit self-assigned this Nov 11, 2025

kumsmrit requested changes Nov 12, 2025

View reviewed changes

kumsmrit reviewed Nov 12, 2025

View reviewed changes