feat(imagebuilder-alpha): add support for Image Recipe Construct #36092

tarunb12 · 2025-11-18T08:21:26Z

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 ImageRecipe construct.

Description of changes

This change implements the ImageRecipe construct, which is a higher-level construct of CfnImageRecipe.

Example

const userData = ec2.UserData.forLinux();
userData.addS3DownloadCommand({
  bucket: s3.Bucket.fromBucketName(this, 'Bucket', `test-bucket-${this.account}`),
  bucketKey: 'test-key',
  localFile: 's3-executable.sh',
});
userData.addExecuteFileCommand({ filePath: 's3-executable.sh' });
userData.addCommands('User Data complete!');

const imageRecipe = new imagebuilder.ImageRecipe(this, 'ImageRecipe', {
  imageRecipeName: 'test-image-recipe',
  imageRecipeVersion: '1.0.0',
  description: 'An Image Recipe',
  // Use an AL2023 base image
  baseImage: imagebuilder.BaseImage.fromSsmParameterName(
    this,
    'MachineImage',
    '/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-default-x86_64',
  ),
  // Use an AWS-managed component, shared component, self-owned component with parameters, and marketplace component
  components: [
    {
      component: imagebuilder.AwsManagedComponent.updateOS(this, 'UpdateOS', {
        platform: imagebuilder.Platform.Linux,
      }),
    },
    {
      component: imagebuilder.Component.fromComponentArn(
        this,
        'ComplianceTestComponent',
        `arn:${this.partition}:imagebuilder:${this.region}:123456789012:component/compliance-test/2025.x.x.x`,
      ),
    },
    {
      component: imagebuilder.AwsMarketplaceComponent.fromAwsMarketplaceComponentAttributes(
        this,
        'MarketplaceComponent',
        {
          name: 'marketplace-component-name',
          marketplaceProductId: '12345678-1234-1234-1234-123456789012',
        },
      ),
    },
    {
      component: imagebuilder.Component.fromComponentAttributes(this, 'CustomComponent', {
        componentName: 'custom-component',
      }),
      parameters: {
        CUSTOM_PARAMETER_KEY: imagebuilder.ComponentParameterValue.fromString('custom-parameter-value'),
      },
    },
  ],
  workingDirectory: '/var/tmp',
  // Optional - retain the SSM agent after the build, and apply custom userdata
  uninstallSsmAgentAfterBuild: false,
  userDataOverride: userData,
  // Optional - attach additional block device to the build instance
  blockDevices: [
    {
      deviceName: '/dev/sda1',
      mappingEnabled: true,
      volume: ec2.BlockDeviceVolume.ebs(50, {
        deleteOnTermination: true,
        iops: 1000,
        volumeType: ec2.EbsDeviceVolumeType.GP3,
        throughput: 1000,
        encrypted: true,
        kmsKey: kms.Key.fromLookup(this, 'VolumeKey', { aliasName: 'alias/volume-encryption-key' }),
      }),
    },
  ],
  // Optional - specify tags to apply to the output AMI
  amiTags: {
    Environment: 'production',
  },
});

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

ozelalisen

Thanks for considering patterns from previous PRs, left first round of comments

ozelalisen · 2025-11-18T11:00:55Z

packages/@aws-cdk/aws-imagebuilder-alpha/lib/image-recipe.ts

+      resource: 'image-recipe',
+      resourceName: `${this.physicalName}/${imageRecipeVersion}`,
+    });
+    this.imageRecipeVersion = cdk.Fn.select(2, cdk.Fn.split('/', imageRecipe.attrArn));


This should not be belong here, it was related to fromImageRecipeAttributes method

yeah good call. we can actually use .getAtt('Version') here (for some reason, that is not modeled as .attrVersion on the L1)

packages/@aws-cdk/aws-imagebuilder-alpha/lib/base-image.ts

ozelalisen · 2025-11-18T15:17:46Z

packages/@aws-cdk/aws-imagebuilder-alpha/lib/image-recipe.ts

+   *
+   * @default - this is false if the Systems Manager agent is pre-installed on the base image. Otherwise, this is true.
+   */
+  readonly uninstallSsmAgentAfterBuild?: boolean;


What happens if on my baseimage there is not any ssmagent, and I set this as true?

it behaves the same as the default behavior - the output image will not contain the SSM agent

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

packages/@aws-cdk/aws-imagebuilder-alpha/lib/recipe-base.ts

+  public static fromString(value: string): ComponentParameterValue {
+    return new ComponentParameterValue([value]);
+  }


There can be multiple values but, only one value can be saved via this method

The API/CFN input is string list, but only one element is supported for now (to support the simple string data type), so that it can be extended once stringList is supported here

ozelalisen · 2025-11-18T15:22:08Z

packages/@aws-cdk/aws-imagebuilder-alpha/lib/recipe-base.ts

+/**
+ * The parameter value for a component parameter
+ */
+export class ComponentParameterValue {


I do not see any purpose with this class, because parameter value can only be list of strings, so we do not need create an additional parameter value class, this pattern is useful, when value is any that can be number, string, bool.

Yeah - I created it like this so that when Image Builder components support more parameter value data types, we can extend it easily here, rather than having to deprecate the property if we add support for stringLists or booleans for example

So, it is expected that this might be extended for different types?

Correct - that was the intent of making this class

ozelalisen · 2025-11-18T15:23:01Z

packages/@aws-cdk/aws-imagebuilder-alpha/lib/recipe-base.ts

+   * @default - no parameters. if the component contains parameters, their default values will be used. otherwise, any
+   *            required parameters that are not included will result in a build failure
+   */
+  readonly parameters?: { [name: string]: ComponentParameterValue };


This can be simplify as:

Suggested change

readonly parameters?: { [name: string]: ComponentParameterValue };

readonly parameters?: { [name: string]: string[] };

I think we should keep this as ComponentParameterValue. As noted in the other comment, a string list is accepted in API/CFN, but only one element is supported since only the string data type is supported. When stringList, boolean, etc. is supported, ComponentParameterValue would be the better option here, following CDK design guideline for union data types

packages/@aws-cdk/aws-imagebuilder-alpha/lib/base-image.ts

packages/@aws-cdk/aws-imagebuilder-alpha/README.md

Pull request has been modified.

ozelalisen · 2025-11-19T17:06:09Z

packages/@aws-cdk/aws-imagebuilder-alpha/lib/recipe-base.ts

+  /**
+   * Indicates whether the recipe is an Image Recipe
+   *
+   * @internal
+   */
+  _isImageRecipe(): this is IImageRecipe;


What is the purpose of this?

We are gonna use this in Image/ImagePipeline constructs. In those constructs, recipe: IRecipeBase will be accepted which can be either an image or container recipe. This method helps us know which recipe, so that we can map it to the correct parameter in the L1 definition. There will be a similar method for IContainerRecipe.

ozelalisen · 2025-11-19T17:06:40Z

packages/@aws-cdk/aws-imagebuilder-alpha/lib/recipe-base.ts

+/**
+ * The parameter value for a component parameter
+ */
+export class ComponentParameterValue {


So, it is expected that this might be extended for different types?

ozelalisen · 2025-11-19T17:07:21Z

packages/@aws-cdk/aws-imagebuilder-alpha/lib/image-recipe.ts

+  /**
+   * Indicates whether the recipe is an Image Recipe
+   *
+   * @internal
+   */
+  public _isImageRecipe(): this is IImageRecipe {
+    return true;
+  }
+}


What is purpose of this?

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

aws-cdk-automation requested a review from a team November 18, 2025 08:21

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 18, 2025

tarunb12 marked this pull request as ready for review November 18, 2025 09:01

ozelalisen self-assigned this Nov 18, 2025

ozelalisen previously requested changes Nov 18, 2025

View reviewed changes

pahud mentioned this pull request Nov 18, 2025

PRs with Conflicts - 9 PR(s) need attention pahud/aws-cdk#13

Open

tarunb12 force-pushed the imagebuilder-image-recipe branch from 56b4365 to f41878c Compare November 19, 2025 03:23

tarunb12 force-pushed the imagebuilder-image-recipe branch 2 times, most recently from 336df49 to aef71d7 Compare November 19, 2025 03:36

pahud mentioned this pull request Nov 19, 2025

CI Pending Approval - 1 PR(s) need attention pahud/aws-cdk#11

Open

aws-cdk-automation added the pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. label Nov 19, 2025

feat(imagebuilder-alpha): add support for Image Recipe Construct

7ca9300

tarunb12 force-pushed the imagebuilder-image-recipe branch from aef71d7 to 7ca9300 Compare November 19, 2025 04:23

ozelalisen reviewed Nov 19, 2025

View reviewed changes

	readonly parameters?: { [name: string]: ComponentParameterValue };
	readonly parameters?: { [name: string]: string[] };

feat(imagebuilder-alpha): add support for Image Recipe Construct #36092

Are you sure you want to change the base?

feat(imagebuilder-alpha): add support for Image Recipe Construct #36092

Conversation

tarunb12 commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue

Reason for this change

Description of changes

Example

Describe any new or updated permissions being added

Description of how you validated changes

Checklist

Uh oh!

ozelalisen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tarunb12 Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tarunb12 commented Nov 18, 2025 •

edited

Loading

tarunb12 Nov 19, 2025 •

edited

Loading