DEV Community: Kenta Goto

AWS CDK Deployment Best Practices

Kenta Goto — Sun, 05 Apr 2026 13:22:41 +0000

Best Practices for AWS CDK Deployment

In AWS CDK, you can define and deploy stacks in various ways. However, with so many approaches available, it can be difficult to determine which one is best. In this article, I will share what I consider to be best practices for deploying with AWS CDK.

Rather than covering resource composition or Construct implementation patterns, I have specifically focused the scope on deployment-related practices in CDK.

This article introduces the following four approaches:

Use Static Stack Creation + Stage
Synthesize once, deploy many
Separate the asset build/publish and deploy phases
Commit cdk.context.json

Disclaimer

While this article is titled "Best Practices," the content reflects my own ongoing experimentation and represents just one example. It is not necessarily the definitive answer, so please consider it as a reference.

Additionally, the most appropriate approach may vary depending on your team and environment. Please keep this in mind.

1. Use Static Stack Creation + Stage

The first topic is about how to define stacks. I recommend using static stack creation combined with Stage.

const app = new cdk.App();

new MyStage(app, 'Dev', {
  ...getProps('Dev'),
  env: {
      region: 'us-east-1',
      account: '111111111111',
  },
});

new MyStage(app, 'Stg', {
  ...getProps('Stg'),
  env: {
      region: 'us-east-1',
      account: '222222222222',
  },
});

new MyStage(app, 'Prod', {
  ...getProps('Prod'),
  env: {
      region: 'us-east-1',
      account: '333333333333',
  },
});

Static Stack Creation vs Dynamic Stack Creation

There are two types of approaches to creating stacks: static and dynamic.

Static stack creation is a method where you explicitly define the stack configuration for each environment (such as dev, stg, and prod) in your code. Specifically, you create a separate stack instance with new for each environment.

const app = new cdk.App();
new MyStack(app, 'DevStack', { ... });
new MyStack(app, 'StgStack', { ... });
new MyStack(app, 'ProdStack', { ... });

On the other hand, dynamic stack creation is a method where you create only a single stack instance with new and pass environment information such as dev / stg / prod via the --context (-c) option of cdk deploy to generate environment-specific stacks.

const app = new cdk.App();
const env = app.node.tryGetContext('env') as string;

new MyStack(app, `${env}Stack`, { ... });

Why Static Stack Creation Is Recommended

There are several differences between the two approaches, but the main difference is whether all environments are synthesized at once.

The cdk deploy command internally executes a synthesis process equivalent to the cdk synth command. And the cdk synth command basically synthesizes all stacks in the entire CDK app. This means that with static stack creation, stacks for all environments such as dev / stg / prod are synthesized at once. On the other hand, with dynamic stack creation, only the stack for the environment specified via the --context option of the cdk deploy command is synthesized.

Because of this characteristic, static stack creation offers the advantage of detecting production environment errors at an earlier stage. For example, if the dev code is correct but the prod code has an error, you can detect the error before actually deploying to prod.

For this reason, I recommend static stack creation.

Cases Where Dynamic Stack Creation Is a Better Fit

If you want to avoid having prod fail because of a dev error, dynamic stack creation might be a better fit.

Also, in large-scale projects where synthesizing stacks for all environments at once takes too long, dynamic stack creation might be the better choice.

For more details about each approach, please refer to the article "CDK Environment Management: Static vs Dynamic Stack Creation", which I co-authored with Thorsten Höger, an AWS Hero from Germany.

Hybrid Approach

While I recommended static stack creation, you can also combine it with the dynamic stack creation approach using context.

This is effective, for example, when multiple people share a single AWS account for development and you want to create personal verification environments.

As shown below, by passing information to identify individuals in the stack name via the --context (-c) option of the cdk deploy command, you can dynamically generate stacks for personal environments. If personal environments are only needed for Dev, you can keep the static stack creation code as-is for Stg and Prod.

npx cdk deploy -c owner=goto Dev/*

const owner = app.node.tryGetContext('owner') as string;
const devStageName = owner ? `Dev-${owner}` : 'Dev';

new MyStage(app, devStageName, {
  ...getProps('Dev'),
  env: {
    region: 'us-east-1',
    account: '111111111111',
  },
});

// Stg and Prod are the same as before
// ...

If each person has their own dedicated AWS environment, you can define stacks for personal environments by specifying your own AWS account ID in the account field, without using context.

const app = new cdk.App();

new MyStage(app, 'Dev', {
  ...getProps('Dev'),
  env: {
      region: 'us-east-1',
      account: process.env.AWS_ACCOUNT_ID || '111111111111',
  },
});

Benefits of Stage

Stage is a concept positioned between App and Stack, serving as a unit for grouping multiple stacks. In applications composed of multiple stacks, using the static approach described earlier to explicitly create stack instances with new for each environment would require creating instances for the combination of all environments and stacks, resulting in verbose code.

By using Stage, you can create a Stage instance with new for each environment and define multiple stacks within it, keeping your code clean. Even if you currently have only one stack, it is a good idea to use Stage from the beginning if there is a possibility that stacks will increase in the future.

class MyStage extends cdk.Stage {
  constructor(scope: cdk.App, id: string, props?: cdk.StageProps) {
    super(scope, id, props);

    new StackA(this, 'StackA', { ... });
    new StackB(this, 'StackB', { ... });
    new StackC(this, 'StackC', { ... });
  }
}

const app = new cdk.App();
new MyStage(app, 'Dev', { ... });
new MyStage(app, 'Stg', { ... });
new MyStage(app, 'Prod', { ... });

For more details about Stage, please refer to the article "How to Use AWS CDK Stage and When to Choose Static vs Dynamic Stack Creation."

Notes on Migrating to Stage

Migrating non-Stage stacks to Stage is generally not difficult.

When using Stage, stack names follow the rule ${stageName}-${Stack ID} (e.g., MyStage-SampleStack), so simply introducing Stage will change the stack names. This means a new stack creation process will be triggered (a deletion process for the original stack will not be triggered).

However, StackProps has a property called stackName. By explicitly specifying this (setting it to the previous stack name), you can prevent the ${stageName}- prefix from being added to the stack name, allowing you to maintain the existing stack without creating a new one.

// Before migration
new StackA(app, 'DevStackA', { ... }); // Stack name is `DevStackA`
new StackB(app, 'DevStackB', { ... });
new StackC(app, 'DevStackC', { ... });

// After migration
class MyStage extends cdk.Stage {
  constructor(scope: cdk.App, id: string, props?: cdk.StageProps) {
    super(scope, id, props);

    // Without specifying stackName, the stack name becomes `Dev-StackA`, triggering new stack creation
    new StackA(this, 'StackA', { stackName: `${id}StackA`, ... });
    new StackB(this, 'StackB', { stackName: `${id}StackB`, ... });
    new StackC(this, 'StackC', { stackName: `${id}StackC`, ... });
  }
}

const devStage = new MyStage(app, 'Dev');

In most cases, migrating to Stage does not affect existing resources.

However, it is important to note that destructive changes can occur with some resources.

For more details, please refer to the article "AWS CDK: Resources and Causes of Replacement in Non-Stage to Stage Migration."

2. Synthesize Once, Deploy Many

This is a best practice related to CI/CD pipeline configuration.

If you are experienced in application development, you may have heard the phrase "Build once, deploy many."

In CDK, a similar concept is expressed as "Synthesize once, deploy many." This is the idea of synthesizing the CDK app only once and then deploying multiple times. In other words, the key point is to synthesize the CDK app only once within the CI/CD pipeline.

The Risk of Running Synthesis Multiple Times

In the previous section ("Why Static Stack Creation Is Recommended"), I mentioned that the cdk deploy command internally executes a synthesis process equivalent to the cdk synth command.

When you run the cdk deploy command separately for each environment such as dev / stg / prod, the cdk synth command is also executed for each environment. This means that the synthesis process runs for each environment.

When synthesis is executed multiple times, depending on the code, there is a risk that the first and second synthesis runs could produce different outputs. Even if you believe you have written correct code, unexpected mistakes can occur due to implementation errors or inconsistent versions.

Since synthesis for the development environment and synthesis for the production environment are executed at different times, unintended environmental differences may be introduced. Therefore, it is desirable to run synthesis only once.

Beyond the risk, running the synthesis process twice is also redundant and inefficient. Especially in large-scale applications, synthesis can take a considerable amount of time, potentially leading to a significant increase in deployment time.

How to Achieve This in a CI/CD Pipeline

So how do you achieve "Synthesize once, deploy many" within a CI/CD pipeline?

When you run the cdk synth command, the CDK app code is synthesized, and a set of files called the cloud assembly, including CloudFormation templates, is output to a directory called cdk.out.

On the other hand, the cdk deploy command has an --app (-a) option where you can specify the location of the synthesized cloud assembly. When specified, the synthesis process during the deploy command is skipped, and the deployment is executed based on the specified cloud assembly.

In other words, by synthesizing the CDK app only once in advance, saving the cloud assembly for all environments as an artifact, and then referencing that cloud assembly in subsequent deployment jobs for each environment, you can achieve "Synthesize once, deploy many."

This is also possible precisely because of the "static stack creation" approach mentioned earlier. With the static stack creation approach, cloud assemblies for all environments such as dev / stg / prod are generated in a single synthesis.

Specifically, using GitHub Actions as an example, the configuration would look like this:

jobs:
  synth:
    runs-on: ubuntu-latest
    steps:
      # ... checkout, setup-node, npm ci ...
      - run: npx cdk synth # Without specifying a stack name, same as --all
      - uses: actions/upload-artifact@v4
        with:
          name: cdk-out
          path: cdk.out

  deploy-dev:
    needs: synth
    steps:
      # ... checkout, setup-node, npm ci, download-artifact, configure-aws-credentials ...
      - run: npx cdk deploy --app cdk.out --require-approval never Dev/*

  deploy-stg:
    needs: deploy-dev
    steps:
      # ...
      - run: npx cdk deploy --app cdk.out --require-approval never Stg/*

  deploy-prod:
    needs: deploy-stg
    steps:
      # ...
      - run: npx cdk deploy --app cdk.out --require-approval never Prod/*

For more details about cdk.out, please refer to the article "Why is cdk.out (Cloud Assembly) Necessary in AWS CDK?."

3. Separate the Asset Build/Publish and Deploy Phases

Next is about separating the asset build/publish phase from the deploy phase in AWS CDK.

When you run the cdk deploy command, a series of processes are executed: CDK app synthesis, asset build/publish, and CloudFormation deployment.

Assets refer to things like Lambda function code defined in the CDK app and Docker images used by ECS. During cdk deploy, after CDK app synthesis is complete, Docker images are built, and then the built images and Lambda function code files are uploaded (published) to S3 or ECR.

As introduced in the previous section, using the --app (-a) option allows you to skip the synthesis process, but asset build/publish is still executed during deployment.

Having asset build/publish and deployment executed in the same command is convenient. On the other hand, from the perspective of separating build and deploy (release) as described in the Twelve-Factor App's "Build, release, run" principle, it is desirable to have the asset build/publish and deploy phases separated.

Benefits of Phase Separation

When the asset build/publish and deploy phases are separated in AWS CDK, the deployment job's responsibility becomes simpler, allowing it to focus solely on executing CloudFormation. This provides the following benefits:

Deployments are not affected by temporary build failures, enabling safer execution
When a deployment fails, you can skip the asset build and retry only the deployment
IAM permissions can be minimized for each phase
Heavy processes like Docker builds are performed in a prior phase, reducing the time spent in the deploy phase itself
It becomes possible to deploy using the AWS CLI with CloudFormation directly, without using the CDK CLI in the deploy phase

The cdk publish-assets Command

Previously in the CDK CLI, asset build/publish and deployment were tightly coupled.

While it was possible to perform asset build/publish using the cdk-assets library, this method was not widely adopted because it required a separate dependency from the CDK CLI and was not well documented in the CDK documentation.

To address this, the cdk publish-assets command was added to the CDK CLI, which performs synthesis through asset build/publish without deploying. By using this command, you can separate the asset build/publish and deploy phases.

NOTE: As of April 2026, the cdk publish-assets command is still in an unstable version, so you need to run it with the --unstable=publish-assets option.

# Without specifying a stack name, same as --all
npx cdk publish-assets --unstable=publish-assets

# You can also skip synthesis with the --app option
npx cdk publish-assets --unstable=publish-assets --app cdk.out

Example of Phase Separation in a CI/CD Pipeline

By inserting a job that runs the cdk publish-assets command between the synth job and the deploy job as shown below, you can separate the asset build/publish and deploy phases.

The cdk publish-assets command can also skip synthesis by specifying the cloud assembly synthesized in the synth job via the --app option. This allows you to achieve "Synthesize once, deploy many" while also separating the asset build/publish and deploy phases.

  synth:
    runs-on: ubuntu-latest
    steps:
      # ... checkout, setup-node, npm ci ...
      - run: npx cdk synth
      - uses: actions/upload-artifact@v4
        with:
          name: cdk-out
          path: cdk.out

  publish-assets:
    needs: synth
    runs-on: ubuntu-latest
    steps:
      # ... checkout, setup-node, npm ci, configure-aws-credentials ...
      - uses: actions/download-artifact@v4
        with:
          name: cdk-out
          path: cdk.out
      - run: npx cdk publish-assets --unstable=publish-assets --app cdk.out --all
      # You can also publish for specific stages (stacks)
      # Since these run within the same job, Docker layer caching takes effect and builds after the first one are essentially skipped
      # If AWS environments are separated, switch to a role with access to each account
      # npx cdk publish-assets --unstable=publish-assets --app cdk.out Dev/*
      # npx cdk publish-assets --unstable=publish-assets --app cdk.out Stg/*
      # npx cdk publish-assets --unstable=publish-assets --app cdk.out Prod/*

  deploy-dev:
    needs: publish-assets
    steps:
      # ... checkout, setup-node, npm ci, download-artifact, configure-aws-credentials ...
      - run: npx cdk deploy --app cdk.out --require-approval never Dev/*

Reference

I actually contributed the cdk publish-assets command to AWS CDK! (See the Pull Request.)

The separation of the asset build/publish phase is also discussed in a blog post CDK tips, part 7 – CI/CD for CDK applications by a former CDK maintainer. Please check it out as well.

As described in that blog post, CDK Pipelines also creates a publish-assets stage before the deploy stage.

4. Commit cdk.context.json

The last topic is about committing cdk.context.json.

What Is cdk.context.json?

cdk.context.json is a file that caches values retrieved from an AWS account during synthesis.

For example, it dynamically retrieves and stores information such as Availability Zone details and currently available Amazon Machine Image (AMI) IDs for EC2 instances from the AWS account.

Specifically, when you execute methods called context methods, such as fromLookup(), provided by CDK, the method internally retrieves information from the AWS account via the AWS SDK and stores the result in the cdk.context.json file.

const vpc = Vpc.fromLookup(this, 'Vpc', {
  vpcId,
});

const parameter = StringParameter.valueFromLookup(this, parameterName);

Then, during synthesis or deployment, if the information already exists in the cache (cdk.context.json), the process to retrieve information from the AWS account via the SDK does not run, and the information from the file is used instead.

Benefits of Committing cdk.context.json

There are two main benefits of committing cdk.context.json:

Avoiding non-deterministic behavior
Improving deployment speed

Avoiding Non-Deterministic Behavior

For example, suppose you are deploying with a context method that retrieves the latest AMI for EC2.

If a new AMI version is released at some point, since the CDK implementation retrieves the latest image, the retrieved AMI value may differ from the one used by the already deployed EC2 instance without you realizing it, triggering an EC2 replacement (rebuild).

To avoid such "non-deterministic" behavior where the configuration changes depending on when the deployment is executed, you can cache the AMI information from the time of deployment in the cdk.context.json file. On subsequent deployments, the cached information is referenced to use the same value every time, ensuring "deterministic" behavior.

Improving Deployment Speed

In CDK apps that use context methods, if the relevant information is not found in cdk.context.json during synthesis, a dummy value is stored first and the synthesis completes.

After that, the CDK CLI retrieves the information from the AWS account via the AWS SDK and updates cdk.context.json.

Then the synthesis process runs again, and this time the final cloud assembly is generated based on the values stored in cdk.context.json.

In other words, if cdk.context.json is not committed and the file does not exist, synthesis runs twice, which wastes time.

Additionally, since AWS SDK communication runs every time synthesis or deployment is executed, even more time is wasted.

By committing cdk.context.json, synthesis only needs to run once and no AWS SDK communication is triggered, resulting in improved deployment speed.

More Details on cdk.context.json

For more details about cdk.context.json, please refer to the article "The Necessity of 'cdk.context.json' in AWS CDK."

Official Documentation

The AWS CDK official documentation also covers best practices. Please check it out as well.

Summary

In this article, I introduced the following four approaches as best practices for AWS CDK deployment:

Use Static Stack Creation + Stage
Synthesize once, deploy many
Separate the asset build/publish and deploy phases
Commit cdk.context.json

These approaches may not apply to every project. However, I hope they serve as a reference to help you choose the approach that best fits your project.

AWS CDK Tips: How to Centrally Apply Configurations to Multiple Resources

Kenta Goto — Mon, 23 Mar 2026 09:36:01 +0000

In this article, I will introduce a collection of tips for centrally and collectively applying configurations to the properties of multiple resources in AWS CDK.

The tips for bulk property application covered in this article use the following four features:

Aspects
PropertyInjectors
Mixins
RemovalPolicies

1. Aspects

The first feature I will introduce is Aspects.

Aspects is a feature that allows you to apply the same operation to all resources within any given scope, such as a stack or construct.

1-1. How to Use Aspects

You can apply properties to multiple resources at once by defining a class that implements the IAspect interface and writing property override logic for specific resource types in the visit method, as shown below.

// Aspects are implemented by implementing the IAspect interface
export class BucketVersioningUpdater implements cdk.IAspect {
  public visit(node: IConstruct): void {
    // The visit method is called for every resource within the construct passed to Aspects,
    // so we add a condition to only execute for CfnBucket resources
    if (node instanceof CfnBucket) {
      // If bucket versioning is disabled, override it to enabled
      if (
        !node.versioningConfiguration ||
        (!cdk.Tokenization.isResolvable(node.versioningConfiguration) &&
          node.versioningConfiguration.status !== 'Enabled')
      ) {
        node.addPropertyOverride('VersioningConfiguration', {
          Status: 'Enabled',
        });
      }
    }
  }
}

const app = new cdk.App();
const stack = new CdkSampleStack(app, 'CdkSampleStack');

// Apply BucketVersioningUpdater to all resources in CdkSampleStack
cdk.Aspects.of(stack).add(new BucketVersioningUpdater());

1-2. Reference Article for Aspects

Aspects can be used not only for overriding properties but also for property validation.

For details on how to validate properties with Aspects, please refer to my article How to Choose Validation Approaches in AWS CDK.

1-3. Adjusting the Execution Order of Multiple Aspects

When applying multiple Aspects to the same scope, you can adjust the execution order of each Aspect by specifying a priority. This property was introduced in AWS CDK v2.172.0.

You specify a numeric value for priority, where a smaller number means higher priority and earlier execution. There is also a class called AspectPriority that can be used like an enum, offering static variables such as MUTATING (=200), DEFAULT (=500), and READONLY (=1000). However, if you assign the same priority value to multiple Aspects, their execution order is not guaranteed, so it is recommended to assign different values to each Aspect.

For example, suppose you apply multiple Aspects to a single stack as shown below. This is an example where property overrides are performed first and property validation is performed last. In this case, the Aspects are executed in the order: AspectForOverride -> AspectForOther1 -> AspectForOther2 -> AspectForValidation.

const app = new cdk.App();
const stack = new CdkSampleStack(app, 'CdkSampleStack');

// priority = 1000
cdk.Aspects.of(stack).add(new AspectForValidation(), { priority: cdk.AspectPriority.READONLY });
// priority = 200
cdk.Aspects.of(stack).add(new AspectForOverride(), { priority: cdk.AspectPriority.MUTATING });
// priority = 500
cdk.Aspects.of(stack).add(new AspectForOther1(), { priority: cdk.AspectPriority.DEFAULT });
// priority = 600
cdk.Aspects.of(stack).add(new AspectForOther2(), { priority: 600 });

When using a library like cdk-nag that validates CDK stacks through Aspects, you can also set its priority to be lower (i.e., a larger priority number) so that validation runs after the other Aspects have been executed.

2. PropertyInjectors

The next feature I will introduce is PropertyInjectors.

This feature was introduced in May 2025 with AWS CDK v2.196.0.

PropertyInjectors is a feature that centrally rewrites the props of all resources of any given type of L2 Construct (including some L3 Constructs) within a given scope.

For more details, please refer to Configure constructs with CDK Blueprints in the AWS CDK Developer Guide.

NOTE: The Developer Guide mentioned above introduces this as an approach called "CDK Blueprints," but in this article, I will consistently use the name PropertyInjectors, which is the actual CDK class name, just as I do with the other features (Aspects, RemovalPolicies).

2-1. How to Use PropertyInjectors

For example, suppose you have a requirement to set blockPublicAccess to BLOCK_ALL for all Amazon S3 buckets in a stack. Here is an example of using PropertyInjectors to meet this requirement.

First, create a MyBucketPropsInjector class that implements IPropertyInjector. Specify the PROPERTY_INJECTION_ID exposed by the target L2 Construct in this.constructUniqueId within the constructor, and have the inject method return a new props object with the desired properties overridden.

export class MyBucketPropsInjector implements IPropertyInjector {
  public readonly constructUniqueId: string;

  constructor() {
    // Specify the PROPERTY_INJECTION_ID exposed by the Bucket construct
    this.constructUniqueId = Bucket.PROPERTY_INJECTION_ID;
  }

  // Return new props with the desired properties overridden
  public inject(originalProps: BucketProps, _context: InjectionContext): BucketProps {
    return {
      blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
      ...originalProps,
    };
  }
}

Next, add MyBucketPropsInjector to the desired scope as shown below. This allows you to collectively override blockPublicAccess to BLOCK_ALL for all buckets within the scope.

const app = new App();

// When applying to the App
PropertyInjectors.of(app).add(new MyBucketPropsInjector());

// When applying to a specific stack
new Stack(app, 'MyStack', {
  propertyInjectors: [new MyBucketPropsInjector()],
});

2-2. Avoiding Infinite Loops

Suppose you want to set serverAccessLogsBucket, which is also of type Bucket, in the props of a Bucket using PropertyInjectors.

PropertyInjectors are executed at the time the target Construct is created.

Therefore, if you implement this requirement using the approach introduced above, when a new Bucket is created for serverAccessLogsBucket, PropertyInjectors will be triggered again. Then, the serverAccessLogsBucket creation process will also be executed within that Bucket, causing an infinite loop that results in an error.

To avoid this, you can implement a skip mechanism like the one shown below to prevent the infinite loop.

export class SpecialBucketInjector implements IPropertyInjector {
  public readonly constructUniqueId: string;

  // Flag to determine whether to skip
  private _skip: boolean;

  constructor() {
    this._skip = false;
    this.constructUniqueId = Bucket.PROPERTY_INJECTION_ID;
  }

  public inject(originalProps: BucketProps, context: InjectionContext): BucketProps {
    // If the skip flag is true, return the original props as-is
    if (this._skip) {
      return originalProps;
    }

    let accessLogBucket = originalProps?.serverAccessLogsBucket;
    if (!accessLogBucket) {
      // Since PropertyInjectors are executed when a new Construct is created,
      // set the skip flag to true here
      this._skip = true;

      // Because the skip flag is true, property overriding will not occur for this instance,
      // meaning `serverAccessLogsBucket` will not be overridden for this Bucket
      accessLogBucket = new Bucket(context.scope, 'my-access-log', {
        blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
      });

      // Reset the skip flag to false
      this._skip = false;
    }

    return {
      serverAccessLogsBucket: accessLogBucket,
      ...originalProps,
    };
  }
}

2-3. Differences Between Aspects and PropertyInjectors

Both Aspects and PropertyInjectors can apply properties collectively to multiple resources within any given scope, but there are several differences:

Difference in what they target
Difference in when they are applied

First, regarding the difference in what they target: while Aspects overrides the configuration properties of L1 Constructs, PropertyInjectors rewrites the props of L2 or L3 Constructs themselves. This is the key distinction.

Next, regarding the difference in when they are applied: Aspects are executed during the second phase of the CDK application lifecycle, the "Prepare phase."

Most Constructs are primarily created during the first phase, the "Construct phase." In other words, Aspects are executed by traversing the construct tree after most of the CDK application's Constructs have been created.

On the other hand, since PropertyInjectors directly rewrite the props of L2 or L3 Constructs, the value overrides are applied at the time the Construct is created (during the first "Construct phase" of the lifecycle).

2-4. When to Use Aspects vs PropertyInjectors

Here are some use cases to consider when choosing between Aspects and PropertyInjectors:

Cases where Aspects are more suitable:

When the target resources use L1 Constructs
When you want to make overrides at the granularity of AWS CloudFormation properties
When you want to centrally inspect resource properties (without overriding them)

Cases where PropertyInjectors are more suitable:

When you want to make more abstract overrides at the granularity of L2 or L3 Construct props, rather than at the L1 Construct (CloudFormation) property level
When you want to override properties to prevent errors caused by built-in validation within L2 Constructs (since Aspects are executed after Construct creation is complete, only PropertyInjectors can prevent errors within L2 Constructs)

2-5. Notes on PropertyInjectors Application Timing

As mentioned earlier, PropertyInjectors are executed at the time the target Construct is created.

If you apply PropertyInjectors using PropertyInjectors.of().add after the target Stack has already been created, as shown below, the override process will not be executed.

const app = new App();

new CdkSampleStack(app, 'CdkSampleStack');

// Applying PropertyInjectors here will not work because CdkSampleStack has already been created
PropertyInjectors.of(app).add(new MyBucketPropsInjector());

Instead, call it before the Stack is created, or specify it in the propertyInjectors option of the App or Stack props, as shown below.

const app = new App();

// Apply PropertyInjectors before the stack is created
PropertyInjectors.of(app).add(new MyBucketPropsInjector());
new CdkSampleStack(app, 'CdkSampleStack');

// Or specify it in the stack props
new CdkSampleStack(app, 'CdkSampleStack', {
  propertyInjectors: [new MyBucketPropsInjector()],
});

3. Mixins

The third feature I will introduce is Mixins.

Mixins was introduced as a developer preview feature in AWS CDK v2.229.0. In March 2026, with CDK v2.241.0, the core Mixins functionality was moved to the stable package (aws-cdk-lib) and became Generally Available (GA).

Mixins is a mechanism for adding functionality to constructs through composable abstractions. It enables you to selectively apply capabilities that were traditionally bundled into L2 Constructs to L1 Constructs, or conversely, to partially apply L1 properties to L2 Constructs.

For more details, please check out my article AWS CDK Introduces Mixins: A Major Feature for Flexible Construct Composition (Developer Preview) (NOTE: This article was written when Mixins was still in Developer Preview).

3-1. How to Use Mixins

Mixins are applied using the Mixins.of() method or the with() method of each construct.

import { App, Stack, Mixins } from 'aws-cdk-lib';
import { CfnBucket } from 'aws-cdk-lib/aws-s3';
import { BucketVersioning, BucketAutoDeleteObjects } from 'aws-cdk-lib/aws-s3/mixins';

const app = new App();
const stack = new Stack(app, 'CdkSampleStack');

const bucket = new CfnBucket(stack, 'MyBucketApply');
Mixins.of(bucket) // Mixins
  .apply(new BucketVersioning()) // Apply BucketVersioning to bucket
  .apply(new BucketAutoDeleteObjects()); // Apply BucketAutoDeleteObjects to bucket

new CfnBucket(stack, 'MyBucketWith')
  .with(new BucketVersioning()) // Apply BucketVersioning with Construct's with method
  .with(new BucketAutoDeleteObjects()); // Apply BucketAutoDeleteObjects with Construct's with method

You can also apply Mixins to all resources under a specific scope, similar to Aspects.

import { App, Stack, Mixins, ConstructSelector } from 'aws-cdk-lib';
import { CfnBucket } from 'aws-cdk-lib/aws-s3';
import { BucketVersioning } from 'aws-cdk-lib/aws-s3/mixins';
import { Construct } from 'constructs';

const app = new App();
const stack = new Stack(app, 'CdkSampleStack');
const construct = new Construct(stack, 'MyConstruct');

// Apply to all resources under construct
Mixins.of(construct).apply(new BucketVersioning());

// Apply only to specific resource types under construct
Mixins.of(construct, ConstructSelector.resourcesOfType(CfnBucket.CFN_RESOURCE_TYPE_NAME)) // Limited to CfnBucket
  .apply(new BucketVersioning());

3-2. Creating Custom Mixins

You can easily create custom Mixins by extending the Mixin abstract class.

class CustomVersioningMixin extends Mixin {
  supports(construct: any): boolean {
    return construct instanceof s3.CfnBucket;
  }

  applyTo(bucket: any): void {
    bucket.versioningConfiguration = {
      status: 'Enabled',
    };
  }
}

const bucket = new s3.CfnBucket(stack, 'MyBucket');
Mixins.of(bucket).apply(new CustomVersioningMixin());

3-3. Differences Between Mixins and Aspects

Mixins are similar to Aspects in that they modify properties of resources in a specific scope, but they differ in timing of application.

As explained in the Aspects vs PropertyInjectors comparison (section 2-3), Aspects are executed later in the CDK application lifecycle (in the Prepare phase), after all Constructs have been created. On the other hand, like PropertyInjectors, Mixins are executed immediately when they are called.

// Aspects
const construct = new Construct(scope, 'MyConstruct');
new Bucket(construct, 'MyBucket1');

// Executed after Constructs below this are created
Aspects.of(construct).add(new CustomVersioningAspect());

// Aspects are also applied to MyBucket2
new Bucket(construct, 'MyBucket2');

// Mixins
const construct = new Construct(scope, 'MyConstruct');
new Bucket(construct, 'MyBucket1');

// Executed at this point
Mixins.of(construct).apply(new CustomVersioningMixin());

// Mixins are not applied to MyBucket2
new Bucket(construct, 'MyBucket2');

According to the Mixins RFC, it is recommended to use Mixins to make changes and to use Aspects to validate behaviors.

Additionally, a mechanism to convert between Aspects and Mixins is also provided. You can use Shims.asMixin to apply an existing Aspect immediately as a Mixin, or use Shims.asAspect to delay the application of a Mixin to a later phase during synthesis like an Aspect.

import { Mixins, Shims, Aspects } from 'aws-cdk-lib';

// Applies the aspect immediately
Mixins.of(scope).apply(Shims.asMixin(new SomeAspect()));

// Delays application of the Mixin to a later phase during synthesis
Aspects.of(scope).add(Shims.asAspect(new SomeMixin()));

3-4. Differences Between Mixins and PropertyInjectors

While PropertyInjectors is also similar to Mixins, it is recommended to use Mixins when you want to apply abstractions, and PropertyInjectors when you want to change default behaviors (i.e., when you want to use it as a blueprint).

There are also the following differences:

Mixins
- Target: L1 Constructs + L2 Constructs
- Often used with narrow scope (specific Constructs, etc.)
PropertyInjectors
- Target: L2 Constructs (including some L3 Constructs)
- Often used with broad scope (App level, etc.)

4. RemovalPolicies

The fourth feature I will introduce is RemovalPolicies.

This feature was introduced in AWS CDK v2.183.0.

With RemovalPolicies, you can apply a RemovalPolicy to all resources within any given scope at once.

4-1. How to Use RemovalPolicies

For example, if you want to centrally set the RemovalPolicy for all resources, you can write it as follows:

const app = new App();

// Set the RemovalPolicy to DESTROY for all resources
RemovalPolicies.of(app).destroy();

// Set the RemovalPolicy to RETAIN for all resources
RemovalPolicies.of(app).retain();

4-2. MissingRemovalPolicies

Some resources may already have a RemovalPolicy set internally by L2 Constructs, or you may have explicitly set a RemovalPolicy yourself. If you want to apply a RemovalPolicy collectively to all resources except those that already have one, you can use MissingRemovalPolicies.

const app = new App();

// Set the RemovalPolicy to DESTROY for resources that do not yet have one
MissingRemovalPolicies.of(app).destroy();

Conclusion

In this article, I introduced a collection of tips for centrally and collectively applying configurations to the properties of multiple resources in AWS CDK using the following features:

Aspects
PropertyInjectors
Mixins
RemovalPolicies

By leveraging these features, you can efficiently manage the properties of multiple resources and improve the readability and maintainability of your code.

Zero Orphaned Resources: Force Deleting Any CloudFormation Stack

Kenta Goto — Mon, 16 Mar 2026 08:59:30 +0000

DELETE_FAILED and FORCE_DELETE_STACK

If you've ever worked with AWS CloudFormation, chances are you've encountered DELETE_FAILED. A non-empty S3 bucket, an ECR repository with images still in it, a Custom Resource that doesn't return SUCCESS... You end up manually emptying resources and retrying the deletion over and over. It's painful.

"What about FORCE_DELETE_STACK?" you might think. CloudFormation does provide this feature. However, it merely detaches failed resources from the stack. The resources themselves remain in your AWS account. In other words, it creates orphaned resources, and you still have to delete them manually.

When Stack Deletion Gets Complicated

CloudFormation stack deletion can get complicated beyond just DELETE_FAILED. To begin with, when you want to delete multiple stacks at once, CloudFormation offers no built-in way to do so. On top of that, the following problems come into play.

Inter-Stack Dependencies

When deleting multiple stacks, if there are dependencies via Exports/Imports, getting the order wrong causes an error. The more stacks you have, the less realistic it becomes to manually figure out the correct deletion order.

Slow Deletion Due to VPC Lambda

Stacks containing Lambda functions connected to a VPC have to wait for ENI (Elastic Network Interface) cleanup during deletion. This is extremely slow, sometimes taking tens of minutes for a single stack.

Resource Orphaning from Retain Policies

DeletionPolicy settings like Retain and RetainExceptOnCreate exist to protect important data. But there are times when you want to delete everything cleanly, such as tearing down a dev environment or recreating a stack. In those cases, the stack disappears but the resources remain, becoming orphans.

Deletion Protection

Resource-level deletion protection on EC2 instances, RDS clusters, Cognito user pools, and stack-level TerminationProtection are important safeguards against accidental deletion in production. However, when you actually want to delete an unneeded stack, you have to figure out which resources have protection enabled and disable them one by one.

delstack Solves All of These

delstack is a CLI tool I built to solve all of the problems above. It works with stacks from any IaC tool that uses CloudFormation: AWS CDK, SAM, Amplify, Serverless Framework, and more.

Force Deletion of DELETE_FAILED Resources: Zero Orphaned Resources

It automatically cleans up resources that cause normal deletion to fail, then deletes them. Unlike FORCE_DELETE_STACK, it doesn't leave resources behind. Nested child stacks are processed recursively as well.

It supports over 10 resource types including S3 buckets, S3 Directory/Table/Vector buckets, ECR repositories, Backup Vaults, Athena WorkGroups, IAM groups, nested stacks, and Custom Resources. See the README for the full list of supported resource types.

Resources not in this list are deleted normally without any issues, so delstack isn't just for DELETE_FAILED stacks. You can use it for everyday stack deletion as well.

Automatic Dependency Resolution with Parallel Deletion

When multiple stacks are specified, it automatically analyzes dependencies through CloudFormation Exports/Imports and determines the correct order using reverse topological sort. Independent stacks are deleted in parallel for maximum throughput, and rather than simple step-based batching, it uses dynamic scheduling: as soon as a stack's deletion completes, any stacks that depended on it are immediately started, keeping parallelism as high as possible at all times.

Example: Stacks A, B, C, D, E, F (C->A, D->A, E->B, F->C,D,E)

Step 1: Delete F (no stacks depend on it)
Step 2: Delete C, D, E in parallel (after F completes)
Step 3: Delete B (after E completes)
Step 4: Delete A (after both C and D complete)

VPC Lambda Pre-Optimization

Before deletion begins, it automatically detaches VPC configurations from Lambda functions and deletes their ENIs in parallel. This eliminates the ENI cleanup wait time entirely.

Retain Policy Override

With the -f option, resources with Retain/RetainExceptOnCreate policies are force deleted. Resources are reliably removed along with the stack.

Automatic Deletion Protection Removal

With the -f option, resource-level deletion protection on EC2, RDS, Cognito, CloudWatch Logs, ALB, and more, as well as stack TerminationProtection, are automatically detected and disabled before deletion proceeds. Without -f, protected resources are reported and the process is aborted before stack deletion begins, so it's safe by default.

CDK Integration

With the delstack cdk subcommand, you can run it in a CDK app directory to synthesize, discover all stacks (including cross-region), and delete them with dependency resolution.

How to Use

Install with Homebrew in one line.

brew install go-to-k/tap/delstack

For Linux/Windows, you can use the install script.

curl -fsSL https://raw.githubusercontent.com/go-to-k/delstack/main/install.sh | sh

For other installation methods, see the README.

With interactive mode (-i), just search and select your stacks. Add -f to enable force deletion of resources with Retain policies or deletion protection, and stacks with TerminationProtection.

delstack -i -f

Filter a keyword of stack names(case-insensitive): goto

? Select StackNames.
Nested child stacks and XXX_IN_PROGRESS(e.g. ROLLBACK_IN_PROGRESS) status stacks are not displayed.
(* = TerminationProtection)

 [Use arrows to move, space to select, <right> to all, <left> to none, type to filter]
  [ ]  dev-GOTO-03-TestStack
> [x]  dev-Goto-02-TestStack
  [ ] * dev-goto-01-TestStack

You can also specify stack names directly instead of using interactive mode.

delstack -s stack1 -s stack2 -s stack3

GitHub Actions is supported too, making it easy to integrate stack cleanup into your CI/CD pipeline.

- name: Delete stack
  uses: go-to-k/delstack@main
  with:
    stack-name: YourStack1, YourStack2
    force: true
    region: us-east-1

For CDK apps, set cdk: true to run cdk synth and delete all discovered stacks. You can also pass CDK context values and specify an existing cdk.out directory.

- name: Delete CDK stacks
  uses: go-to-k/delstack@main
  with:
    cdk: true
    # cdk-app: ./cdk.out           # Use existing cdk.out (skip synthesis)
    # cdk-context: env=dev,foo=bar  # CDK context values (comma separated)
    force: true

Conclusion

delstack solves every problem around CloudFormation stack deletion with a single command.

Force deletion with zero orphaned resources
Automatic parallel deletion with dependency resolution
Faster deletion through VPC Lambda optimization
Automatic handling of deletion protection and Retain policies
CDK integration with cross-region support

For detailed options and the full list of supported resources, see the README.

Issues and Stars are welcome: github.com/go-to-k/delstack

Why is cdk.out (Cloud Assembly) Necessary in AWS CDK?

Kenta Goto — Thu, 26 Feb 2026 11:45:47 +0000

What is cdk.out

cdk.out is a directory that stores a collection of files called the cloud assembly.

When you run the cdk synth command or the cdk deploy command, the cloud assembly is generated from your CDK code and stored in the cdk.out directory.

What is the Cloud Assembly

The cloud assembly is a collection of files generated by the synthesis of a CDK application (CDK code). The CDK CLI references this information to deploy resources to the AWS environment.

In other words, the cloud assembly can be considered an intermediate artifact that CDK uses to deploy infrastructure definitions written in CDK code to the AWS environment.

Components of the Cloud Assembly

The cloud assembly primarily consists of the following files and directories:

(stack name).template.json
- CloudFormation template generated by CDK code
(stack name).assets.json
- File describing information about assets used in CDK code
(stack name).metadata.json
- File describing metadata used in CDK code
manifest.json
- File describing metadata of the cloud assembly
tree.json
- File representing the Construct tree structure of resources defined in CDK code
cdk.out
- File storing Cloud Assembly schema version information
asset.(hash value)/
- Directory storing asset files used in CDK code
- Uses hash values calculated for each asset as directory names
- Each asset is classified into two types: S3 assets and Docker image assets, which are uploaded to S3 buckets or ECR repositories created by the cdk bootstrap command when the cdk deploy command is executed
- Docker image assets are built when the cdk deploy command is executed (not when the cdk synth command is executed)
assembly-(stage name)/
- Directory storing cloud assemblies generated for each stage when using Stage Construct

Why cdk.out is Necessary

As explained above, cdk.out is a directory for storing the cloud assembly, which is an intermediate artifact generated from CDK code.

So why is this directory necessary? You might wonder whether it's really necessary to generate and store information needed for deployment as files.

Before explaining this, let me first explain that synthesis can be executed multiple times depending on how CDK commands are used, and the risks associated with this.

Risks of Running Synthesis Multiple Times

The cdk deploy command internally executes synthesis processing equivalent to the synth command.

For example, if you execute cdk deploy after executing cdk synth, synthesis is executed in both synth and deploy, meaning the CDK application is synthesized twice.

In this case, there is a risk that the second synthesis execution will create output different from the first synthesis result. This could cause behavior different from what the developer intended, as a different result might be generated in the next synthesis process even though the developer confirmed and approved the first synthesis result.

On the other hand, even when executing cdk deploy without executing cdk synth, if you manage multiple environments such as development environment (dev) and production environment (prod) with one CDK application, synthesis will be executed every time you deploy to each environment. There is also a risk that unintended environment differences may be introduced because synthesis in the development environment and synthesis in the production environment are executed at different times.

Apart from risks, running the synthesis process twice is redundant and inefficient. Especially for large applications, synthesis can take considerable time, which can lead to a significant increase in deployment time.

Reusing cdk.out with the `--app` Option

I explained the risks of running synthesis multiple times, so how can we avoid these risks?

The cdk deploy command has the --app (-a) option to avoid this.

This option allows you to specify the path to the cdk.out directory. By specifying this, you can deploy using an already synthesized cloud assembly and skip the synthesis that is normally executed during the deploy command. If you know that no code has been changed since the last cdk synth, you can avoid redundant synthesis processing by reusing the cloud assembly with this option.

npx cdk deploy --app ./cdk.out

You can also explicitly separate synthesis and deployment execution by specifying a command to directly synthesize CDK code. This command is typically the same as the command defined in the app property of the cdk.json file.

npx cdk deploy --app "npx ts-node --prefer-ts-exts bin/cdk-sample.ts"

# For environments where TypeScript can be executed with Node.js
npx cdk deploy --app "node bin/cdk-sample.ts"

With this option, you can specify cdk.out as the synthesis result and deploy using the same cloud assembly in multiple environments such as development and production. In other words, you can reuse cdk.out with the --app option. This avoids the risks of running synthesis multiple times and also avoids redundant synthesis processing.

npx cdk synth

npx cdk deploy -a ./cdk.out DevStack
npx cdk deploy -a ./cdk.out ProdStack

Separating Synthesis and Deployment

I explained that reusing cdk.out with the --app option can avoid the risks of running synthesis multiple times. This is precisely because cdk.out enables the separation of synthesis and deployment.

In this way, being able to separate synthesis and deployment can be said to be the necessity of cdk.out in AWS CDK.

Additionally, if a mechanism supports the cloud assembly, you can deploy using the cloud assembly from applications other than the CDK CLI. For example, tools like cdk-assets also reference the cloud assembly to manage assets. In this way, separating synthesis and deployment, such as performing synthesis with CDK and deployment with tools other than the CDK CLI, enables flexible workflows in CDK application development.

synthesize once, deploy many

In application development such as containers, there is an approach called "build once, deploy many." This is the idea of building an application only once and deploying that build artifact to multiple environments.

The approach of reusing cdk.out with the --app option in CDK is exactly the same idea. It can be called "synthesize once, deploy many," where synthesis is performed only once and deployment can be done multiple times afterward.

Other Benefits and Use Cases of cdk.out

Asset Caching

cdk.out includes asset directories that store asset files used in CDK code. This includes code files used by Lambda and ECS, Dockerfiles, and other files.

As a CDK mechanism, if an asset with the same hash value as the asset used in the CDK code to be synthesized already exists during synthesis, the bundling process for that asset is skipped and the existing asset is reused. In other words, cdk.out also functions as a cache for assets.

Utilizing cdk.out in CI/CD Pipelines

I mentioned that cdk.out allows you to deploy using the same cloud assembly in multiple environments. Specifically, you can utilize cdk.out in CI/CD pipelines such as GitHub Actions as follows:

jobs:
  synthesize:
    runs-on: ubuntu-latest
    steps:
      - run: npm ci
      - run: npx cdk synth
      - uses: actions/upload-artifact@v6
        with:
          name: cdk-out
          path: cdk.out

  deploy-dev:
    needs: synthesize
    steps:
      - uses: actions/download-artifact@v6
      - run: npx cdk deploy --app cdk.out DevStack

  deploy-prod:
    needs: deploy-dev
    steps:
      - uses: actions/download-artifact@v6
      - run: npx cdk deploy --app cdk.out ProdStack

Reference Materials

In the explanations so far, I mentioned that multiple deployments are possible based on a single synthesis, but did you know that there are actually two types of CDK stack creation methods: static stack creation and dynamic stack creation?

The approach of performing synthesis only once introduced this time is possible with the static stack creation approach. On the other hand, dynamic stack creation also has other benefits, so if you are interested in the differences between them, please check out the article "CDK Environment Management: Static vs Dynamic Stack Creation". This is an article I co-authored with Thorsten Höger, an AWS Hero from Germany.

Also, an article by a former CDK maintainer is helpful, so please take a look.

cdk.out Bloat and How to Deal with It

cdk.out Bloat

We learned that cdk.out plays an important role in CDK, but by repeating synthesis, new files and directories accumulate, and it can reach several GB before you know it.

This is because a new asset directory is created when application files are updated. Especially for container applications using Docker, the size tends to be particularly large.

Additionally, since the cdk deploy command also builds Docker images, not only cdk.out but also built images stored in local Docker will continue to increase.

cdk-agc

To optimize such bloated cdk.out, I created a tool called cdk-agc.

(It's very useful, so please star it on GitHub if you like!)

Specifically, it does the following:

Deletes old asset files and directories in cdk.out that are not used by the current stack
Automatically deletes locally built Docker images if the deleted assets are Docker assets
Deletes temporary CDK directories accumulated in $TMPDIR
No installation required - just run the command with npx and it executes immediately

This optimizes cdk.out, removes accumulated Docker images, and saves local disk space. Furthermore, if you cache cdk.out in CI/CD, it can significantly reduce cache size, improving the efficiency of your CI/CD pipeline.

No installation required - you can run it immediately by adding npx to the command, so please feel free to try it.

You can use -d for dry run, -k to specify retention period, and -t to clean up temporary directories in $TMPDIR, so please use them according to your needs.

# Navigate to the CDK project with cdk.out you want to optimize
cd my-cdk-project

# Clean up cdk.out (also deletes built Docker asset images)
npx cdk-agc

# Check files to be deleted with dry run feature
npx cdk-agc -d

# Keep files modified within 24 hours
npx cdk-agc -k 24

# Clean up temporary directories in $TMPDIR
npx cdk-agc -t

Conclusion

cdk.out is often overlooked, but it plays an important role in CDK application development. By understanding and properly utilizing cdk.out, you can develop CDK applications more efficiently.

AWS CDK Hotswap Deployments Now Support Bedrock AgentCore Runtime

Kenta Goto — Thu, 29 Jan 2026 12:56:45 +0000

AWS CDK's hotswap deployments now support Bedrock AgentCore Runtime.

What are hotswap deployments?

Hotswap deployments refer to deployments using the --hotswap option with the cdk deploy command. Instead of updating the CloudFormation stack, this feature directly updates the changed resources using the AWS SDK internally in CDK, significantly reducing deployment time.

npx cdk deploy --hotswap

AWS CDK generates CloudFormation templates from CDK code by executing an internal process called "synthesis". Then, it deploys CloudFormation stacks based on those templates.

However, even when only application-side files such as Lambda function code or container images are changed, CDK still requires CloudFormation stack deployment, which takes time.

Since application code changes more frequently than infrastructure definitions, the wait time caused by CloudFormation deployment for each code change can degrade the development experience.

To address such cases, CDK provides the hotswap deployment feature. When using hotswap deployments, changes to application-side files such as Lambda function code or container images can be directly updated to resources without performing CloudFormation deployment processing. This significantly reduces deployment time and accelerates the development cycle.

However, this hotswap feature only supports specific changes to certain resources, such as Lambda function code assets and ECS image assets. For details on supported resources, please refer to the official documentation.

Developer Guide: cdk deploy

How hotswap deployments work

In hotswap deployment, synthesis processing is first executed to generate a CloudFormation template based on the implemented CDK code.

Next, it obtains the differences between that template and the template of the actually deployed stack.

If the properties of the resources with differences are hotswap-compatible, it retrieves the current configuration values using AWS SDK Get APIs. Then, combining the information from the newly generated template with the information obtained from the AWS SDK, it finally updates the differences using AWS SDK Update APIs.

Hotswap support for Bedrock AgentCore Runtime

AWS CDK CLI v2.1102.0 added hotswap deployment support for Bedrock AgentCore Runtime.

Actually, I contributed this feature to the AWS CDK.

feat(cli): support hotswap for AWS::BedrockAgentCore::Runtime

This was one of the most challenging CDK contributions I've ever done. I particularly struggled with aspects unrelated to CDK's features and implementation, such as dependencies and integration tests.

By the way, CDK is divided into the Construct library repository and the CLI repository, and this feature is implemented on the CLI repository side.

How to use hotswap deployments with Bedrock AgentCore Runtime

Bedrock AgentCore Runtime supports container images (ECR) or code files (S3) as runtime sources. As of January 2026, S3 only supports Python.

The hotswap deployment introduced this time supports both ECR and S3 updates.

Version

Please update the aws-cdk version to v2.1102.0 or later.

NOTE: aws-cdk is the CDK CLI, and aws-cdk-lib is the Construct library. The hotswap feature this time is a CLI-side feature.

NOTE: Make sure aws-cdk-lib and @aws-cdk/aws-bedrock-agentcore-alpha are also installed.

Example package.json:

"devDependencies": {
  // ...,
  // ...,
  "aws-cdk": "2.1102.0"
},
"dependencies": {
  "@aws-cdk/aws-bedrock-agentcore-alpha": "^2.235.0-alpha.0",
  "aws-cdk-lib": "2.235.0",

ECR source implementation example

First, here's an implementation example using container images.

The AgentRuntimeArtifact.fromAsset method builds the local Dockerfile, automatically pushes it to a CDK-managed ECR, and allows you to specify it as the Runtime source.

NOTE: You need to prepare application code and Dockerfile in the ArtifactDirectory directory in advance, but this is omitted in this article.

const runtimeArtifact = AgentRuntimeArtifact.fromAsset(path.join(__dirname, 'ArtifactDirectory'));

const runtimeECR = new Runtime(this, 'RuntimeECR', {
  runtimeName: 'runtime_ecr',
  description: 'Runtime',
  agentRuntimeArtifact: runtimeArtifact,
  environmentVariables: {
    LOG_LEVEL: 'INFO',
  },
});

S3 source implementation example

Next, here's an implementation example using code files.

First, upload local code files to S3 using the Asset construct from the aws-cdk-lib/aws-s3-assets module.

Then, you can specify that S3 object as the Runtime source using the AgentRuntimeArtifact.fromS3 method.

const asset = new Asset(this, 'CodeAsset', {
  path: path.join(__dirname, 'ArtifactDirectory'),
});

const runtimeArtifact = AgentRuntimeArtifact.fromS3(
  {
    bucketName: asset.s3BucketName,
    objectKey: asset.s3ObjectKey,
  },
  AgentCoreRuntime.PYTHON_3_13,
  ['app.py'],
);

const runtimeS3 = new Runtime(this, 'RuntimeS3', {
  runtimeName: 'runtime_s3',
  agentRuntimeArtifact: runtimeArtifact,
  description: 'Runtime',
  environmentVariables: {
    LOG_LEVEL: 'INFO',
  },
});

Executing hotswap deployment

After completing the CDK implementation as described above, first deploy without the --hotswap option.

NOTE: This example shows the case using S3 source CDK code, but the same applies to ECR source.

npx cdk deploy

Next, make changes only to the application code, not the CDK code.

Then, before performing hotswap deployment, try running the cdk diff command.

npx cdk diff

You should see differences in the AgentRuntimeArtifact of the Runtime resource, as shown below. Since AgentRuntimeArtifact is a hotswap-supported property, you can execute hotswap deployment.

[~] AWS::BedrockAgentCore::Runtime RuntimeS3 RuntimeS39E2E9695
 └─ [~] AgentRuntimeArtifact
     └─ [~] .CodeConfiguration:
         └─ [~] .Code:
             └─ [~] .S3:
                 └─ [~] .Prefix:
                     ├─ [-] a18dede8bbfbfc4db1d3a434052cab2fe8ea82c01a945a1d66127d63b5523299.zip
                     └─ [+] f2793197e0247f4f89ebcf16787e78399b4de6c255ff8e57d7d1766ac38d4113.zip

Then, execute deployment with the --hotswap option.

npx cdk deploy --hotswap

If a message like hotswapped! is displayed as shown below, the hotswap deployment has succeeded. The deployment time should be significantly reduced compared to when not using hotswap deployment.

(  Synthesis time: 3.45s

� The --hotswap and --hotswap-fallback flags deliberately introduce CloudFormation drift to speed up deployments
� They should only be used for development - never use them for your production Stacks!

CdkSampleStack: start: Building CdkSampleStack Template
CdkSampleStack: success: Built CdkSampleStack Template
CdkSampleStack: start: Publishing CdkSampleStack Template (current_account-us-east-1-2ad80d58)
CdkSampleStack: success: Published CdkSampleStack Template (current_account-us-east-1-2ad80d58)
CdkSampleStack: deploying... [1/1]

( hotswapping resources:
   ( AWS::BedrockAgentCore::Runtime 'runtime_s3-iImLoZB224'
   ( AWS::BedrockAgentCore::Runtime 'runtime_s3-iImLoZB224' hotswapped!

Bedrock AgentCore Runtime properties that support hotswap

The following properties of Bedrock AgentCore Runtime support hotswap deployment:

In other words, hotswap deployment is only executed when these properties are changed.

agentRuntimeArtifact
description
environmentVariables

If changes include other properties, only changes to the above properties are applied with hotswap deployment, and changes to other properties are ignored.

Using the --hotswap-fallback option allows you to fall back to a full CloudFormation deployment.

npx cdk deploy --hotswap-fallback

By the way, I aligned these three properties with Lambda's hotswap-supported properties.

Internally, the target properties can be increased as much as desired, but targeting properties that don't change frequently doesn't provide much benefit, so I simply narrowed it down to the minimum necessary properties, just like Lambda.

If there are properties you'd like to be targeted, please let me know and I'll consider changes.

Precautions for hotswap deployments

Never use in production environments

While this seemingly convenient hotswap deployment feature is useful, it must not be used in production environments.

This is because hotswap deployment intentionally introduces drift (inconsistency between the template and actual resource state) to the CloudFormation stack, which can cause unexpected behavior when trying to update the CloudFormation stack later.

Therefore, use hotswap deployments to improve development speed in development environments.

Be aware of tokens

For example, when defining an S3 source using BucketDeployment and Source.asset() as shown below, hotswap doesn't work.

const bucket = new Bucket(this, 'CodeBucket');

// Not recommended (hotswap doesn't work)
const deployment = new aws_s3_deployment.BucketDeployment(this, 'Deploy', {
  sources: [aws_s3_deployment.Source.asset(path.join(__dirname, 'agent-code'))],
  destinationBucket: bucket,
  extract: false,
});

const agentRuntimeArtifact = AgentRuntimeArtifact.fromS3(
  {
    bucketName: bucket.bucketName,
    objectKey: cdk.Fn.select(0, deployment.objectKeys), // Token, resolved at deployment time
  },
  AgentCoreRuntime.PYTHON_3_13,
  ['app.py'],
);

The objectKey generated here is a token, which is information that is not resolved during synthesis but is resolved at deployment time. On the CloudFormation template, it is represented using functions like Fn::GetAtt or Ref.

In that case, even if you upload the changed code files, the property value specifying the S3 information of Runtime on the CloudFormation template remains a value using functions like Fn::GetAtt, and no difference occurs, so hotswap doesn't work. Therefore, please use the Asset construct as shown above.

"AgentRuntimeArtifact": {
  "CodeConfiguration": {
  "Code": {
    "S3": {
    "Bucket": {
      "Ref": "CodeBucketFF4C7AD6"
    },
    "Prefix": {
      "Fn::Select": [
      0,
      {
        "Fn::GetAtt": [
        "DeployCustomResource218AF6A4",
        "SourceObjectKeys"
        ]
      }
      ]
    }
    }
  },

If hotswap is not being executed, check whether it's a token.

Specifically, look at the CloudFormation template generated by CDK and check if it's something like Fn::GetAtt whose value doesn't change even when modified.

Making it more convenient

When using S3 as a source, it's tedious to manually call the Asset construct every time, right?

Actually, I've submitted a pull request to AWS CDK to address this.

feat(bedrock-agentcore-alpha): add fromCodeAsset method to create runtime artifact with local code assets

Once this is merged, you'll be able to simply specify the directory path of code files using the AgentRuntimeArtifact.fromCodeAsset method, and it will upload to S3 for you, as shown below.

const runtimeArtifact = agentcore.AgentRuntimeArtifact.fromCodeAsset({
  path: path.join(__dirname, 'ArtifactDirectory'),
  runtime: agentcore.AgentCoreRuntime.PYTHON_3_13,
  entrypoint: ['app.py'],
});

Conclusion

If there are any bugs, I'd appreciate it if you could let me know. I'll fix them immediately.

AWS CDK IAM Role Management: Preventing Automatic Policy Updates

Kenta Goto — Thu, 11 Dec 2025 11:14:15 +0000

Table of Contents
Automatic IAM Role Generation in L2 Constructs
withoutPolicyUpdates()
mutable in fromRoleArn()
Role.customizeRoles()
Conclusion

Automatic IAM Role Generation in L2 Constructs

One of the major features of AWS CDK is that most L2 Constructs automatically generate IAM roles with the necessary permissions for the resources.

On the other hand, most Constructs also allow you to pass a custom role you created yourself, so you can avoid automatic generation.

However, even in that case, the L2 Construct often automatically grants the necessary permissions to the custom role you created and passed.

withoutPolicyUpdates()

However, if you want to manage IAM roles yourself, you may also want to manage the policies yourself, so there may be cases where you want to avoid having permissions automatically granted to your custom role within the L2 Construct.

In such cases, you can use the withoutPolicyUpdates() method of the Role Construct to avoid automatic permission grants to your custom role.

const role = new iam.Role(stack, 'ExecutionRole', {
  assumedBy: new iam.ServicePrincipal('bedrock-agentcore.amazonaws.com'),
});

// Add the necessary policies yourself
role.addToPrincipalPolicy(statement);

new agentcore.Runtime(stack, 'TestRuntime', {
  runtimeName: 'integ_test_runtime',
  agentRuntimeArtifact: runtimeArtifact,
  executionRole: role.withoutPolicyUpdates(), // Pass the return value of withoutPolicyUpdates(), not role
});

mutable in fromRoleArn()

In CDK, you can pseudo-import a role created outside the stack into the CDK stack using static methods such as fromRoleArn() of the Role Construct.

This allows you to use the convenient methods provided by the Construct in your CDK code even for manually created resources, making it a very useful feature.

For IAM roles imported with the fromRoleArn() method, you can also set mutable: false to prevent policies from being automatically attached.

const importedRole = iam.Role.fromRoleArn(stack, 'ImportedRole', 'my-role-arn', {
  mutable: false,
});

new agentcore.Runtime(stack, 'TestRuntime', {
  runtimeName: 'integ_test_runtime',
  agentRuntimeArtifact: runtimeArtifact,
  executionRole: importedRole,
});

Role.customizeRoles()

Using the Role.customizeRoles() method, you can output a report of what IAM roles and policies would be generated by L2 Constructs without actually creating them.

const app = new cdk.App();
const stack = new cdk.Stack(app, 'LambdaStack');

iam.Role.customizeRoles(stack);

const key = new kms.Key(stack, 'BucketKey');
const bucket = new s3.Bucket(stack, 'Bucket', {
  encryptionKey: key,
});
const handler = new lambda.Function(stack, 'Handler', {
  runtime: lambda.Runtime.NODEJS_22_X,
  handler: 'index.handler',
  code: lambda.Code.fromInline(`
    exports.handler = async function(event, context) {
      console.log("Event: ", event);
      return;
    };
  `),
});

bucket.grantRead(handler);

This generates two files: iam-policy-report.txt and iam-policy-report.json.

<missing role> (LambdaStack/Handler/ServiceRole)

AssumeRole Policy:
[
  {
    "Action": "sts:AssumeRole",
    "Effect": "Allow",
    "Principal": {
      "Service": "lambda.amazonaws.com"
    }
  }
]

Managed Policy ARNs:
[
  "arn:(PARTITION):iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
]

Managed Policies Statements:
NONE

Identity Policy Statements:
[
  {
    "Action": [
      "s3:GetObject*",
      "s3:GetBucket*",
      "s3:List*"
    ],
    "Effect": "Allow",
    "Resource": [
      "(LambdaStack/Bucket/Resource.Arn)",
      "(LambdaStack/Bucket/Resource.Arn)/*"
    ]
  },
  {
    "Action": [
      "kms:Decrypt",
      "kms:DescribeKey"
    ],
    "Effect": "Allow",
    "Resource": "(LambdaStack/BucketKey/Resource.Arn)"
  }
]

{
  "roles": [
    {
      "roleConstructPath": "LambdaStack/Handler/ServiceRole",
      "roleName": "missing role",
      "missing": true,
      "assumeRolePolicy": [
        {
          "Action": "sts:AssumeRole",
          "Effect": "Allow",
          "Principal": {
            "Service": "lambda.amazonaws.com"
          }
        }
      ],
      "managedPolicyArns": ["arn:(PARTITION):iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"],
      "managedPolicyStatements": [],
      "identityPolicyStatements": [
        {
          "Action": ["s3:GetObject*", "s3:GetBucket*", "s3:List*"],
          "Effect": "Allow",
          "Resource": ["(LambdaStack/Bucket/Resource.Arn)", "(LambdaStack/Bucket/Resource.Arn)/*"]
        },
        {
          "Action": ["kms:Decrypt", "kms:DescribeKey"],
          "Effect": "Allow",
          "Resource": "(LambdaStack/BucketKey/Resource.Arn)"
        }
      ]
    }
  ]
}

Based on this report, you can create IAM roles/policies yourself and specify them in the usePrecreatedRoles option of customizeRoles to safely switch to self-managing IAM roles.

const stack = new Stack(app, 'LambdaStack');

iam.Role.customizeRoles(stack, {
  usePrecreatedRoles: {
    'LambdaStack/Handler/ServiceRole': 'lambda-service-role',
  },
});

NOTE: The above examples are quoted from the Security And Safety Dev Guide in the CDK repository's Wiki and the official documentation Define permissions for L2 constructs with the AWS CDK, so please refer to them for more details.

Conclusion

If you don't want to leave the generation/granting of IAM roles and permissions (policies) to automatic generation by L2 Constructs in CDK, it would be good to remember these methods.

AWS CDK Introduces Mixins: A Major Feature for Flexible Construct Composition (Developer Preview)

Kenta Goto — Tue, 25 Nov 2025 10:48:26 +0000

AWS CDK has newly introduced Mixins as a major feature that will become the core of future CDK development, currently available as a Developer Preview.

This feature is expected to significantly change how CDK will be used in the future.

CDK Version Used in This Article (Updated on February 13, 2026)

The CDK versions used in this article are as follows:

CDK: aws-cdk-lib: 2.238.0
Mixins module: @aws-cdk/mixins-preview: 2.238.0-alpha.0
CDK CLI: aws-cdk: 2.1106.0

At the time of publication, this article used v2.229.0 when Mixins was released, but due to several breaking changes, the version has been upgraded to v2.238.0 and the sample code in this article has been updated accordingly. Additionally, new features have been added, so those have been included as well.

What are Mixins (Updated on March 3, 2026)

As of November 2025, Mixins is in Developer Preview. Please be aware that the specification and behavior may change significantly in the future.

Update: In March 2026, with CDK v2.241.0, the core Mixins functionality was moved to the stable package (aws-cdk-lib) and became Generally Available (GA)!

The remaining features (individual Mixin classes beyond the core functionality, etc.) continue to be developed in the preview package.

For details, see the following PR: https://github.com/aws/aws-cdk/pull/37055

Overview of Mixins

Mixins is a mechanism for applying composable abstractions to any Construct, regardless of whether it's an L1 or L2 Construct.

It was introduced in CDK v2.229.0, but as of November 2025, it is still in Developer Preview. Not all features are fully available yet, and more functionality and improvements are planned to be added in the future.

This article explains the overview and usage of Mixins in a more accessible way, based on the content from the Mixins README and RFC.

README
RFC
- As of November 25, 2025, the RFC has not been merged yet, so the PR link is provided above.
- The RFC is likely not to be merged yet as more features are planned to be added.

Characteristics of Mixins

Mixins enables the partial application of abstractions to L1 Constructs or custom constructs that were traditionally done with L2 Constructs, allowing users to introduce only the features they need without using L2 Constructs.

This makes it possible to selectively introduce only the necessary features, even when some abstractions of L2 Constructs are attractive but others are not desired.

Additionally, when new features are added to AWS services, new properties are immediately reflected in L1 Constructs, but it takes time for them to be reflected in L2 Constructs. By using Mixins, users can easily and safely apply new properties to L2 Constructs (without using escape hatches) before those properties are added to L2 Constructs.

In other words, Mixins reduces the gap between L1 and L2 Constructs, enabling more flexible construct design.

Furthermore, Mixins also provides a mechanism to abstractly apply common patterns such as encryption across various AWS services.

Installation

Since Mixins is still in Developer Preview, it is provided as the @aws-cdk/mixins-preview package.

npm install -D @aws-cdk/mixins-preview

Note

If you encounter errors when running cdk deploy or cdk synth after introducing Mixins in an existing CDK project (TypeScript), first check your tsconfig.json.

The newer version of CDK CLI (2.1033.0) generates the following configuration, so if your project's configuration differs, aligning it may resolve the issue.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": [
      "es2022"
    ],
    ...,
    ...,
    "skipLibCheck": true,
}

How to Use Mixins

Mixins are applied using the Mixins.of() method or the with() method of each construct.

The with() method becomes available by importing the @aws-cdk/mixins-preview/with module in the file where you use it (import '@aws-cdk/mixins-preview/with').

NOTE: The .with() method is currently available only in JavaScript and TypeScript. The import is only required during the preview period. Once the API is stable, the .with() method will be available by default on all constructs in all languages.

import * as cdk from 'aws-cdk-lib';
import '@aws-cdk/mixins-preview/with';
import { CfnBucket } from 'aws-cdk-lib/aws-s3';
import { Mixins } from '@aws-cdk/mixins-preview/core';
import { BucketVersioning, AutoDeleteObjects } from '@aws-cdk/mixins-preview/aws-s3/mixins';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'CdkSampleStack');

const bucket = new CfnBucket(stack, 'MyBucketApply');
Mixins.of(bucket) // Mixins
  .apply(new BucketVersioning()) // Apply BucketVersioning to bucket
  .apply(new AutoDeleteObjects()); // Apply AutoDeleteObjects to bucket

new CfnBucket(stack, 'MyBucketWith')
  .with(new BucketVersioning()) // Apply BucketVersioning with Construct's with method
  .with(new AutoDeleteObjects()); // Apply AutoDeleteObjects with Construct's with method

You can also apply Mixins to all resources under a specific scope, similar to Aspects.

import * as cdk from 'aws-cdk-lib';
import '@aws-cdk/mixins-preview/with';
import { BucketVersioning } from '@aws-cdk/mixins-preview/aws-s3/mixins';
import { Mixins, ConstructSelector } from '@aws-cdk/mixins-preview/core';
import { Construct } from 'constructs';
import { CfnBucket } from 'aws-cdk-lib/aws-s3';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'CdkSampleStack');
const construct = new Construct(stack, 'MyConstruct');

// Apply to all resources under construct
Mixins.of(construct).apply(new BucketVersioning());

// Apply only to specific resource types under construct
Mixins.of(construct, ConstructSelector.resourcesOfType(CfnBucket.CFN_RESOURCE_TYPE_NAME)) // Limited to CfnBucket
  .apply(new BucketVersioning());

// Apply only to resources matching specific ID patterns under construct
Mixins.of(construct, ConstructSelector.byId('.*-prod-.*')) // Limited to resources whose ID contains "-prod-"
  .apply(new ProductionSecurityMixin()); // ProductionSecurityMixin is an example of custom Mixins

Types of Mixins

There are several types of Mixins patterns available:

Cross-Service Mixins
Resource-Specific Mixins
L1 Property Mixins
Log Delivery Mixins

Cross-Service Mixins

These are Mixins that can be applied across multiple AWS services.

For example, EncryptionAtRest is a Mixin that enables encryption across AWS resources that support it.

NOTE: The EncryptionAtRest Mixin is not yet included in the current CDK release, but it is introduced in the README examples. It is expected to be introduced soon, so this article uses that example as well.

import { Mixins } from '@aws-cdk/mixins-preview/core';
import { App, Stack } from 'aws-cdk-lib';
import { CfnLogGroup } from 'aws-cdk-lib/aws-logs';
import { CfnBucket } from 'aws-cdk-lib/aws-s3';

const app = new App();
const stack = new Stack(app, 'MyStack');

const bucket = new CfnBucket(stack, 'Bucket');
Mixins.of(bucket).apply(new EncryptionAtRest());

const logGroup = new CfnLogGroup(stack, 'LogGroup');
Mixins.of(logGroup).apply(new EncryptionAtRest());

Resource-Specific Mixins

Resource-specific Mixins are also available for each AWS service (resource).

For example, there are AutoDeleteObjects, which automatically deletes objects using a custom resource Lambda for S3 buckets, BucketVersioning, which enables versioning, and BucketPolicyStatementsMixin, which adds IAM policy statements to the bucket policy.

By applying these Mixins to L1 Constructs, you can introduce the same abstractions as L2 Constructs without using L2 Constructs.

While versioning can be easily enabled with just L1 Constructs, it is convenient when applying to multiple resources at once, similar to Aspects.

import {
  AutoDeleteObjects,
  BucketVersioning,
  BucketPolicyStatementsMixin,
} from '@aws-cdk/mixins-preview/aws-s3/mixins';
import { Mixins } from '@aws-cdk/mixins-preview/core';
import { App, Stack } from 'aws-cdk-lib';
import { PolicyStatement, AnyPrincipal, PolicyDocument } from 'aws-cdk-lib/aws-iam';
import { CfnBucket, CfnBucketPolicy } from 'aws-cdk-lib/aws-s3';

const app = new App();
const stack = new Stack(app, 'MyStack');

const bucket = new CfnBucket(stack, 'Bucket');

Mixins.of(bucket).apply(new AutoDeleteObjects());

Mixins.of(bucket).apply(new BucketVersioning());

const bucketPolicy = new CfnBucketPolicy(stack, 'BucketPolicy', {
  bucket: bucket,
  policyDocument: new PolicyDocument(),
});
Mixins.of(bucketPolicy).apply(
  new BucketPolicyStatementsMixin([
    new PolicyStatement({
      actions: ['s3:GetObject'],
      resources: ['*'],
      principals: [new AnyPrincipal()],
    }),
  ]),
);

L1 Property Mixins

These are Mixins that allow you to easily apply L1 properties that have not yet been introduced to L2 Constructs.

For example, by passing a Mixin called CfnBucketPropsMixin, which applies L1 properties, to the with() method of an L2 Construct, you can apply L1 properties that have not yet been introduced to L2 Constructs in a typed manner.

Traditionally, applying L1 properties to L2 Constructs required using escape hatches, which had the problem of lacking type safety. Using Mixins makes it easier to apply them in a typed manner.

import * as cdk from 'aws-cdk-lib';
import '@aws-cdk/mixins-preview/with';
import { CfnBucketPropsMixin } from '@aws-cdk/mixins-preview/aws-s3/mixins';
import { Bucket } from 'aws-cdk-lib/aws-s3';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'CdkSampleStack');

new Bucket(stack, 'Bucket').with(
  new CfnBucketPropsMixin({
    versioningConfiguration: { status: 'Enabled' },
    publicAccessBlockConfiguration: {
      blockPublicAcls: true,
      blockPublicPolicy: true,
    },
  }),
);

L1 Property Mixins also provide two merge strategies: MERGE and OVERRIDE.

MERGE (default): Merge the specified properties into the existing properties
OVERRIDE: Overwrite the existing properties with the specified properties

import * as cdk from 'aws-cdk-lib';
import '@aws-cdk/mixins-preview/with';
import { CfnBucketPropsMixin } from '@aws-cdk/mixins-preview/aws-s3/mixins';
import { Mixins } from '@aws-cdk/mixins-preview/core';
import { PropertyMergeStrategy } from '@aws-cdk/mixins-preview/mixins';
import { CfnBucket } from 'aws-cdk-lib/aws-s3';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'CdkSampleStack');

const bucket = new CfnBucket(stack, 'Bucket');
bucket.versioningConfiguration = { status: 'Enabled' };

// MERGE
// versioningConfiguration becomes: { status: 'Enabled', newProperty: 'Disabled' }
// -> status: 'Enabled' remains
Mixins.of(bucket).apply(
  new CfnBucketPropsMixin(
    { versioningConfiguration: { newProperty: 'Disabled' } },
    { strategy: PropertyMergeStrategy.MERGE },
  ),
);

// OVERRIDE
// versioningConfiguration becomes: { newProperty: 'Disabled' }
// -> status: 'Enabled' is removed
Mixins.of(bucket).apply(
  new CfnBucketPropsMixin(
    { versioningConfiguration: { newProperty: 'Disabled' } },
    { strategy: PropertyMergeStrategy.OVERRIDE },
  ),
);

While the two types of Mixins mentioned earlier are implemented individually in the CDK repository, L1 Property Mixins are automatically generated for all L1 Constructs in the CDK repository.

Log Delivery Mixins

Mixins for Vended logs delivery are also provided.

The following is an example of CfnDistributionLogsMixin, which is specific to CloudFront Distribution, but Vended logs Mixins are provided for several other AWS services as well (CfnUserPoolLogsMixin, CfnVPCLogsMixin, CfnLoadBalancerLogsMixin, etc.).

import * as cdk from 'aws-cdk-lib';
import '@aws-cdk/mixins-preview/with';
import { Bucket } from 'aws-cdk-lib/aws-s3';
import { CfnDistributionLogsMixin } from '@aws-cdk/mixins-preview/aws-cloudfront/mixins';
import { Distribution } from 'aws-cdk-lib/aws-cloudfront';
import { S3BucketOrigin } from 'aws-cdk-lib/aws-cloudfront-origins';
import { LogGroup } from 'aws-cdk-lib/aws-logs';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'CdkSampleStack');

const bucket = new Bucket(stack, 'MyBucket');
const distribution = new Distribution(stack, 'Distribution', {
  defaultBehavior: {
    origin: S3BucketOrigin.withOriginAccessControl(bucket),
  },
});

// Create log destination
const logGroup = new LogGroup(stack, 'DeliveryLogGroup');

// Configure log delivery using the mixin
distribution.with(CfnDistributionLogsMixin.CONNECTION_LOGS.toLogGroup(logGroup));

Log Delivery Mixins are also automatically generated for each supported AWS service in the CDK repository.

Error Handling

requireAll and requireAny

When Mixins are applied using the apply() method, the processing is skipped for resources that do not support that Mixin.

If you want to check whether there are any resources under the scope to which the Mixin is applied that do not support the Mixin, use the requireAll() or requireAny() methods.

The requireAll() method requires all resources under the scope to support the Mixin. If even one resource does not support it, an error will be thrown.

The requireAny() method requires at least one resource under the scope to support the Mixin. If no resources support it, an error will be thrown.

// Skip if there are resources that do not support EncryptionAtRest under construct
Mixins.of(construct).apply(new EncryptionAtRest());

// Throw an error if any resource under construct does not support BucketVersioning
Mixins.of(construct).requireAll().apply(new BucketVersioning());

// Apply if at least one resource under construct supports BucketVersioning
Mixins.of(construct).requireAny().apply(new BucketVersioning());

report and selectedConstructs

The report and selectedConstructs methods are also provided for performing manual assertions based on the results of Mixin applications.

report is used to retrieve information about resources to which Mixins were successfully applied. The return value is an array of the MixinApplication interface, allowing you to confirm which Mixin was applied to which Construct.

selectedConstructs is used to retrieve the list of Constructs that were filtered as Mixin application targets by the second argument of Mixins.of() (or if unspecified). The return value is an array of the IConstruct interface, allowing you to check which Constructs were targeted before the Mixin was applied.

import * as cdk from 'aws-cdk-lib';
import '@aws-cdk/mixins-preview/with';
import { BucketVersioning } from '@aws-cdk/mixins-preview/aws-s3/mixins';
import { Mixins } from '@aws-cdk/mixins-preview/core';
import { Queue } from 'aws-cdk-lib/aws-sqs';
import { Bucket, CfnBucket } from 'aws-cdk-lib/aws-s3';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'CdkSampleStack');

new Bucket(stack, 'MyBucket');
new Queue(stack, 'MyQueue');

// Get an application report for manual assertions
const report = Mixins.of(stack).apply(new BucketVersioning()).report;

report.forEach(({ construct, mixin }) => {
  cdk.Annotations.of(stack).addInfoV2(
    `mixins-report:${mixin.constructor.name}`,
    `Applied mixin ${mixin.constructor.name} to construct ${construct.node.path}`,
  );
});

// Get the list of constructs that were selected by the selector
const constructs = Mixins.of(
  stack,
  ConstructSelector.resourcesOfType(CfnQueue.CFN_RESOURCE_TYPE_NAME),
).apply(new BucketVersioning()).selectedConstructs;

constructs.forEach((construct) => {
  cdk.Annotations.of(stack).addInfoV2(
    `mixins-selected:${construct.node.path}`,
    `Selected construct: ${construct.node.path}`,
  );
});

In the case of the above code, you will get output like the following when running cdk deploy:

❯ npx cdk deploy
[Info at /CdkSampleStack] Applied mixin BucketVersioning to construct CdkSampleStack/MyBucket/Resource [ack: mixins-report:BucketVersioning]
[Info at /CdkSampleStack] Selected construct: CdkSampleStack/MyQueue/Resource [ack: mixins-selected:CdkSampleStack/MyQueue/Resource]

Creating Custom Mixins

You can easily create custom Mixins by implementing the IMixin interface.

You can also create one with some of IMixin already implemented by extending the Mixin abstract class.

NOTE: It is recommended to always extend the Mixin abstract class rather than implementing IMixin directly. While the experience is similar, extending Mixin will make future transitions easier for authors.

The following example is a custom Mixin that enables versioning for S3 buckets.

// or class CustomVersioningMixin implements IMixin {
class CustomVersioningMixin extends Mixin {
  supports(construct: any): boolean {
    return construct instanceof s3.CfnBucket;
  }

  applyTo(bucket: any): void {
    bucket.versioningConfiguration = {
      status: 'Enabled',
    };
  }
}

const bucket = new s3.CfnBucket(stack, 'MyBucket');
Mixins.of(bucket).apply(new CustomVersioningMixin());

Differences from Aspects

Mixins are similar to Aspects in that they modify properties of resources in a specific scope, but they differ in timing of application.

Aspects are not executed at call time, but are executed later in the synthesis process of the CDK application (in the Prepare phase after Construct creation is complete in the CDK application lifecycle).

In other words, while Aspects are executed after all Constructs defined in the CDK application have been created, Mixins are executed immediately when they are called.

Aspects

const construct = new Construct(scope, 'MyConstruct');
new Bucket(construct, 'MyBucket1');

// Executed after Constructs below this are created
Aspects.of(construct).add(new CustomVersioningAspect());

// Aspects are also applied to MyBucket2
new Bucket(construct, 'MyBucket2');

Mixins

const construct = new Construct(scope, 'MyConstruct');
new Bucket(construct, 'MyBucket1');

// Executed at this point
Mixins.of(construct).apply(new CustomVersioningMixin());

// Mixins are not applied to MyBucket2
new Bucket(construct, 'MyBucket2');

This means that Mixins are a form of imperative programming, while Aspects are a form of declarative programming.

According to the Mixins RFC, it is recommended to use Mixins to make changes and to use Aspects to validate behaviors.

We recommend to use Mixins to make changes, and to use Aspects to validate behaviors.

There are also other differences between Mixins and Aspects, as described below:

With mixins, you make explicit decisions about each construct's capabilities. With aspects, you set policies that the CDK applies automatically during synthesis. Mixins give you precise control and type safety, while aspects provide broad governance and compliance enforcement.

Mixins
- You can make explicit decisions about each Construct's capabilities
- Provides precise control and type safety
Aspects
- You can set policies that the CDK applies automatically during synthesis
- Provides broad governance and compliance enforcement

The RFC also mentions that a mechanism will be introduced to convert between Aspects and Mixins, but as of v2.229.0, this feature has not yet been introduced.

// Applies the aspect immediately
Mixins.of(scope).apply(Shims.fromAspect(new TaggingAspect({ Environment: 'prod' })));

// Delays application of the Mixin to the synthesis phase
Aspects.of(scope).add(Shims.fromMixin(new EncryptionAtRest()));

Differences from Property Injectors

Property Injectors is a feature that allows you to centrally rewrite properties (props) for all instances of "a specific type of L2 Construct (including some L3 Constructs)" within an App, Stack, or Construct. It was introduced in AWS CDK v2.196.0.

export class MyBucketPropsInjector implements IPropertyInjector {
  public readonly constructUniqueId: string;

  constructor() {
    this.constructUniqueId = Bucket.PROPERTY_INJECTION_ID;
  }

  public inject(originalProps: BucketProps, _context: InjectionContext): BucketProps {
    return {
      blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
      ...originalProps,
    };
  }
}

const app = new App();
PropertyInjectors.of(app).add(new MyBucketPropsInjector());

While Property Injectors is also similar to Mixins, it is recommended to use Mixins when you want to apply abstractions, and Property Injectors when you want to change default behaviors (i.e., when you want to use it as a blueprint).

There are also the following differences:

Mixins
- Target: L1 Constructs + L2 Constructs
- Often used with narrow scope (specific Constructs, etc.)
Property Injectors
- Target: L2 Constructs (including some L3 Constructs)
- Often used with broad scope (App level, etc.)

For more details on Property Injectors, please refer to the article.

EventBridge Event Patterns

The Mixins package also provides a mechanism for generating EventBridge event patterns in a type-safe manner. (While this feature itself is not a Mixin, it is included in the same package.)

This feature works with both L1 and L2 Constructs.

For example, for S3 bucket events, you can use the BucketEvents class to generate event patterns for S3 bucket object creation events in a type-safe way.

import * as cdk from 'aws-cdk-lib';
import '@aws-cdk/mixins-preview/with';
import { BucketEvents } from '@aws-cdk/mixins-preview/aws-s3/events';
import * as events from 'aws-cdk-lib/aws-events';
import * as targets from 'aws-cdk-lib/aws-events-targets';
import { Function } from 'aws-cdk-lib/aws-lambda';
import { Bucket, CfnBucket } from 'aws-cdk-lib/aws-s3';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'CdkSampleStack');
const fn = new Function(stack, 'Function', { ... });

// Works with L2 constructs
const bucket = new Bucket(stack, 'Bucket');

// BucketEvents from Mixins
const bucketEvents = BucketEvents.fromBucket(bucket);

new events.Rule(stack, 'Rule', {
  eventPattern: bucketEvents.objectCreatedPattern({
    object: { key: events.Match.wildcard('uploads/*') },
    eventMetadata: {
      region: events.Match.prefix('us-'),
      version: ['0'],
    },
  }),
  targets: [new targets.LambdaFunction(fn)],
});

// Also works with L1 constructs
const cfnBucket = new CfnBucket(stack, 'CfnBucket');

// BucketEvents from Mixins
const cfnBucketEvents = BucketEvents.fromBucket(cfnBucket);

new events.CfnRule(stack, 'CfnRule', {
  state: 'ENABLED',
  eventPattern: cfnBucketEvents.objectCreatedPattern({
    object: { key: events.Match.wildcard('uploads/*') },
    eventMetadata: {
      region: events.Match.prefix('us-'),
      version: ['0'],
    },
  }),
  targets: [{ arn: fn.functionArn, id: 'L1' }],
});

These event patterns are automatically generated in the CDK repository for EventBridge events available in the AWS Event Schema Registry.

For example, for S3 events, the following patterns are available:

objectCreatedPattern() - Object creation events
objectDeletedPattern() - Object deletion events
objectTagsAddedPattern() - Object tagging events
awsAPICallViaCloudTrailPattern() - CloudTrail API call events

Conclusion

Mixins is an important feature that will become the core of future CDK development.

Although it is still in Developer Preview and there are still insufficient features and behaviors, it is worth paying attention to as it has the potential to significantly change how CDK will be used in the future.

AWS CDK Unit Testing Advanced Tips: Aligning Feature Flags and Skipping Bundling

Kenta Goto — Tue, 28 Oct 2025 14:30:45 +0000

AWS CDK Unit Testing Advanced Tips

In the previous article AWS CDK Unit Testing Guide: When and How to Use Different Test Types, I introduced basic concepts of unit testing in CDK, including when and how to use them.

In this article, I will introduce two advanced tips for CDK unit testing:

Aligning feature flags with production environments
Skipping bundling

AWS CDK Unit Testing Advanced Tips
Table of Contents
1. Aligning Feature Flags with Production Environments
- What are Feature Flags?
- Feature Flag Behavior in Unit Tests
- Template Differences Caused by Feature Flag Discrepancies
- How to Align Feature Flags
2. Skipping Bundling
- About NodejsFunction Bundling
- How to Skip Bundling
- Image Asset Building Does Not Run in Unit Tests
Conclusion

1. Aligning Feature Flags with Production Environments

What are Feature Flags?

AWS CDK uses feature flags to enable breaking changes with new functionality through an opt-in approach. This ensures existing CDK code behavior is preserved while allowing new CDK features to be adopted at your own pace. (For details, please refer to the official documentation.)

Feature flags can be configured in the context section within cdk.json.

(Additionally, you can set feature flags through other methods such as the context prop in App or Stack within CDK code, or via command line arguments like cdk deploy --context xx=yy.)

{
  "context": {
    "@aws-cdk/aws-iam:minimizePolicies": true
  }
}

Feature flags are automatically added to cdk.json when creating a CDK project, i.e., when executing cdk init. Specifically, the feature flags introduced in CDK at that time are set with their default values.

Even when new functionality with feature flags is added to new CDK versions, those feature flags are generally not automatically added to existing CDK projects' cdk.json files. This means that upgrading CDK versions won't change the behavior of existing CDK code. (Rarely, some feature flags may be enabled by default.)

If you want to enable feature flags in existing projects, you must explicitly set the new feature flags in cdk.json yourself.

Feature Flag Behavior in Unit Tests

Feature flags are typically applied when configured in cdk.json.

However, in CDK unit tests using the Template class from the assertions module, cdk.json is not read.

This is because CDK is internally divided into CDK CLI and CDK App, with cdk.json being read by CDK CLI. However, unit tests call CDK App directly without going through CDK CLI. As a result, unit tests perform CDK synthesis without reading cdk.json.

Therefore, in unit tests, all feature flags enabled in cdk.json become disabled.

*Some feature flags are enabled by default even without explicit configuration.

Template Differences Caused by Feature Flag Discrepancies

As mentioned above, all feature flags become disabled when running unit tests. This means there may be configuration differences between templates actually deployed and templates generated in tests due to feature flags.

For example, suppose @aws-cdk/aws-iam:minimizePolicies feature flag is set to true in cdk.json.

Consider the following CDK code:

export class CdkSampleStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const role = new cdk.aws_iam.Role(this, 'Role', {
      assumedBy: new cdk.aws_iam.ServicePrincipal('lambda.amazonaws.com'),
    });

    role.addToPrincipalPolicy(
      new cdk.aws_iam.PolicyStatement({
        actions: ['s3:GetObject'],
        resources: ['arn:aws:s3:::my-bucket/*'],
      }),
    );

    role.addToPrincipalPolicy(
      new cdk.aws_iam.PolicyStatement({
        actions: ['s3:PutObject'],
        resources: ['arn:aws:s3:::my-bucket/*'],
      }),
    );
  }
}

When @aws-cdk/aws-iam:minimizePolicies is true, CDK automatically merges multiple different actions for the same resource or multiple identical statements.

This means the above CDK code results in a single Action array containing both s3:GetObject and s3:PutObject:

  "RoleDefaultPolicy5FFB7DAB": {
   "Type": "AWS::IAM::Policy",
   "Properties": {
    "PolicyDocument": {
     "Statement": [
      {
       "Action": [
        "s3:GetObject",
        "s3:PutObject"
       ],
       "Effect": "Allow",
       "Resource": "arn:aws:s3:::my-bucket/*"
      }
     ],
      ...

However, if you write a snapshot test like the following in unit tests:

const getTemplate = (): Template => {
  const app = new App();
  const stack = new CdkSampleStack(app, 'CdkSampleStack');
  return Template.fromStack(stack);
};

test('Snapshot', () => {
  const template = getTemplate();
  expect(template.toJSON()).toMatchSnapshot();
});

The template generated by this test would look like this. Unlike the previous template, s3:GetObject and s3:PutObject are written as separate statements.

    "RoleDefaultPolicy5FFB7DAB": {
      "Properties": {
        "PolicyDocument": {
          "Statement": [
            {
              "Action": "s3:GetObject",
              "Effect": "Allow",
              "Resource": "arn:aws:s3:::my-bucket/*",
            },
            {
              "Action": "s3:PutObject",
              "Effect": "Allow",
              "Resource": "arn:aws:s3:::my-bucket/*",
            },
          ],
          ...
      },
      "Type": "AWS::IAM::Policy",
    },

While this may not be a significant difference, some feature flags can fundamentally change processing behavior, potentially causing unexpected differences in actual deployment results.

How to Align Feature Flags

Here's how to align feature flags between templates actually deployed and templates generated in tests.

When you want to align feature flags between production environment and tests, you need to explicitly pass context loaded from cdk.json to props of App etc.

Therefore, create a function like getContext below that reads the actual cdk.json and returns context. Then pass it to the context prop of App.

// Function that reads actual cdk.json and returns `context`
const getContext = (): Record<string, any> => {
  const cdkJsonPath = path.join(__dirname, '..', 'cdk.json');
  const cdkJson = JSON.parse(fs.readFileSync(cdkJsonPath, 'utf-8'));
  return cdkJson.context || {};
};

const getTemplate = (): Template => {
  const app = new App({
    context: {
      ...getContext(), // Call it here
    },
  });
  const stack = new CdkSampleStack(app, 'CdkSampleStack');
  return Template.fromStack(stack);
};

This ensures the generated template matches what's actually deployed, improving test reliability.

      "RoleDefaultPolicy5FFB7DAB": {
        "Properties": {
          "PolicyDocument": {
            "Statement": [
              {
-               "Action": "s3:GetObject",
-               "Effect": "Allow",
-               "Resource": "arn:aws:s3:::my-bucket/*",
-             },
-             {
-               "Action": "s3:PutObject",
+               "Action": [
+                 "s3:GetObject",
+                 "s3:PutObject",
+               ],
                "Effect": "Allow",
                "Resource": "arn:aws:s3:::my-bucket/*",
              },
            ],

2. Skipping Bundling

About NodejsFunction Bundling

For example, there's a construct called NodejsFunction that automatically bundles TypeScript code to JavaScript and creates Lambda functions with Node.js runtime.

This construct uses esbuild for bundling when esbuild is available in your CDK project's node_modules (i.e., when esbuild is included in package.json's devDependencies).

*If esbuild is not available, or if the forceDockerBundling property in bundling is set to true, Docker bundling is executed. However, esbuild is more lightweight, so many people probably use esbuild.

export class CdkSampleStack2 extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    new NodejsFunction(this, 'NodejsWithoutDocker', {
      entry: path.join(__dirname, 'lambda', 'index.ts'),
      handler: 'handler',
      runtime: Runtime.NODEJS_22_X,
    });
  }
}

How to Skip Bundling

In CDK unit tests, bundling of Lambda code like above is also performed.

However, if you're already testing Lambda code bundling in application tests, you might want to skip bundling in CDK tests to reduce test time.

Actually, you can skip bundling for all stacks by specifying an empty array for BUNDLING_STACKS in context as follows:

const getTemplate = (): Template => {
  const app = new App({
    context: {
      [BUNDLING_STACKS]: [], // This
    },
  });
  const stack = new CdkSampleStack(app, 'CdkSampleStack');
  return Template.fromStack(stack);
};

test('Snapshot', () => {
  const template = getTemplate();
  expect(template.toJSON()).toMatchSnapshot();
});

However, bundling is not skipped when using Docker instead of esbuild. In such cases, you should use esbuild.

esbuild is not installed
bundling.forceDockerBundling is set to true
Using Code.fromDockerBuild()

export class CdkSampleStack2 extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    new NodejsFunction(this, 'NodejsWithDocker', {
      entry: path.join(__dirname, 'lambda', 'index.ts'),
      handler: 'handler',
      runtime: Runtime.NODEJS_22_X,
      bundling: {
        forceDockerBundling: true,
      },
    });

    new Function(this, 'FromDockerBuild', {
      code: Code.fromDockerBuild(path.join(__dirname, '..')),
      handler: 'handler',
      runtime: Runtime.NODEJS_22_X,
    });
  }
}

Image Asset Building Does Not Run in Unit Tests

The above case was about Lambda code uploaded as file assets to S3 for use by Lambda. (runtime specifies the runtime corresponding to each code.)

On the other hand, when using image assets (Docker images) for Docker Lambda or ECS, Docker builds are not executed in unit tests at all.

Therefore, you don't need to specify BUNDLING_STACKS in such cases.

Code.fromAssetImage()
DockerImageFunction
DockerImageAsset

export class CdkSampleStack2 extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    new Function(this, 'FromAssetImage', {
      code: Code.fromAssetImage(path.join(__dirname, '..')),
      handler: Handler.FROM_IMAGE,
      runtime: Runtime.FROM_IMAGE,
    });

    new DockerImageFunction(this, 'DockerImageFunction', {
      code: DockerImageCode.fromImageAsset(path.join(__dirname, '..')),
    });

    new DockerImageAsset(this, 'DockerImageAsset', {
      directory: path.join(__dirname, '..'),
    });
  }
}

Here's a brief explanation of the reason.

Lambda code bundling runs within the construct, i.e., within CDK App. However, building image assets like Docker images runs in CDK CLI, not CDK App.

Also, CDK unit tests call CDK App directly without going through CDK CLI.

Therefore, image asset building performed by CDK CLI is not executed in unit tests.

Conclusion

I have introduced advanced tips for unit testing in AWS CDK.

Based on the basic tips article introduced at the beginning, please consider using these advanced tips as well.

AWS CDK Unit Testing Guide: When and How to Use Different Test Types

Kenta Goto — Tue, 07 Oct 2025 11:43:18 +0000

Types of Unit Tests in AWS CDK

There are three main types of unit tests in AWS CDK:

Snapshot tests
Fine-grained assertions tests
Validation tests

Snapshot Tests

What are Snapshot Tests?

Snapshot tests in AWS CDK are tests that output the AWS CloudFormation template synthesized from CDK code and compare it with the template generated from a previous test run to detect template differences.

import { App } from 'aws-cdk-lib';
import { Match, Template } from 'aws-cdk-lib/assertions';
import { MyStack } from '../lib/my-stack';

describe('MyStack Tests', () => {
  test('Snapshot Tests', () => {
    const app = new App();
    const stack = new MyStack(app, 'MyStack');

    const template = Template.fromStack(stack);
    expect(template.toJSON()).toMatchSnapshot();
  });
});

When you run this test file, a __snapshots__ directory is created directly under the test directory, and a snapshot file named my-stack.test.ts.snap is saved inside. The snapshot file is saved in JSON format of the CloudFormation template. Then it compares the snapshot saved from the previous test run with the template generated by the current CDK code, and if there are differences, the test fails.

If the difference is as expected, you can update the snapshot file to the one generated this time by running the test with the command npx jest --updateSnapshot.

Use Cases for Snapshot Tests

I believe snapshot tests are essential in almost all cases in AWS CDK development, except for some early development phases.

They are particularly effective in the following scenarios:

AWS CDK version updates
CDK code refactoring
Difference management in version control systems

1. AWS CDK Version Updates

One major reason to use snapshot tests is that as long as the snapshot test passes when you update the AWS CDK library version, there is no difference in the CloudFormation template, meaning you can guarantee there is no impact on deployed resources.

The AWS CDK library has various changes added with each version update, and new features are added and bugs are fixed, which can sometimes change the output of CloudFormation templates.

However, in projects developing with AWS CDK, if the content of the generated CloudFormation template changes when upgrading the AWS CDK version, unexpected changes may occur to already deployed resources. Snapshot tests can detect and prevent this in advance.

Basically, on the AWS CDK library development side, which is OSS (Open Source Software), development is carried out to minimize changes to the generated CloudFormation templates, but it may inevitably change sometimes, so it becomes important for users to perform snapshot tests on their side. (However, there are mechanisms in place to prevent breaking changes in AWS CDK OSS development, so you can rest assured.)

2. CDK Code Refactoring

Snapshot tests are also very useful when refactoring CDK code.

Basically, in refactoring, it is required that the behavior (CloudFormation template in CDK) does not change before and after the code change.

By utilizing snapshot tests, you can confirm that the CloudFormation template generated by refactoring is the same as before refactoring.

3. Difference Management in Version Control Systems

When managing code including snapshot files with version control systems like Git, they demonstrate even more powerful effects when making resource definition changes during development and operation.

This is because update differences are visualized and recorded not only at the CDK code granularity but also at the CloudFormation template granularity.

You can also check unexpected changes that are difficult to understand at the CDK code level, minimizing risks related to resource definition changes.

Fine-grained Assertions Tests

What are Fine-grained Assertions Tests?

Fine-grained assertions tests in AWS CDK are tests that extract part of the generated CloudFormation template and check that part. This allows you to test detailed components such as what kind of resources are generated.

For example, you can perform fine-grained tests such as "Are two AWS::SNS::Subscription resources generated?" or "Is nodejs20.x set for the Runtime of AWS::Lambda::Function?"

import { App, assertions } from 'aws-cdk-lib';
import { Match, Template } from 'aws-cdk-lib/assertions';
import { MyStack } from '../lib/my-stack';

const getTemplate = (): assertions.Template => {
  const app = new App();
  const stack = new MyStack(app, 'MyStack');
  return Template.fromStack(stack);
};

describe('Fine-grained assertions tests', () => {
  test('Two SNS subscriptions are created', () => {
    const template = getTemplate();
    template.resourceCountIs('AWS::SNS::Subscription', 2);
  });

  test('Lambda has nodejs20.x', () => {
    const template = getTemplate();
    template.hasResourceProperties('AWS::Lambda::Function', {
      Handler: 'handler',
      Runtime: 'nodejs20.x',
    });
  });
});

Use Cases for Fine-grained Assertions Tests

For these fine-grained assertions tests, the theory of specifically when and what tests to write hasn't been well established yet, I feel.

This is because you can perform various checks at fine granularities such as per resource and per property, and a wide range of test cases can be considered. Also, if you write tests for all resources, it becomes an even more enormous amount, and there are cases where the redundancy and maintenance difficulty outweigh the benefits of testing.

Therefore, while this is my personal judgment criteria, I think it's good to use them in the following scenarios:

Loop processing
Conditional branching
Property override
Definitions you especially want to guarantee
Value specification using props

As a premise, AWS CDK can be written in programming languages, so you can perform resource definition code writing "procedurally", but it's also possible to write resource definitions "declaratively".

*Here, "declarative" refers to declaring the existence of resources, such as "create resource XX." On the other hand, "procedural" refers to writing resource creation procedures procedurally, such as "to create resource XX, first perform this process, then perform this process."

As infrastructure definitions, I think "declarative" is often preferable because you can easily understand what resources are generated just by looking at the definition. Since AWS CDK is primarily a tool for infrastructure definition, it will often be written "declaratively."

And in declarative descriptions like "create resource A," it is self-evident that "resource A is created." For the benefit of confirming something self-evident, fine-grained assertions tests can create code that is almost the same as the resource definition side code, leading to the troublesome nature of dual definition, which can increase test maintenance costs.

For such reasons, as my personal judgment criteria, I think it's good to use them in the above scenarios rather than writing detailed fine-grained assertions tests for all resources.

1. Loop Processing

While I mentioned writing resource definitions "declaratively" above, when using loop processing to generate resources, it becomes "procedural" code writing.

In other words, what kind of resources are generated by this is no longer self-evident.

Therefore, when using loop processing to generate resources, it becomes important to write fine-grained assertions tests to confirm that the loop processing is working correctly.

Specifically, suppose you have the following CDK code:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { Topic } from 'aws-cdk-lib/aws-sns';

export interface MyStackProps extends cdk.StackProps {
  appNames: string[];
}

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: MyStackProps) {
    super(scope, id, props);

    // Make unique combinations considering cases with duplicate elements
    const appNames = new Set(props.appNames);

    for (const appName of appNames) {
      new Topic(this, `${appName}Topic`, {
        displayName: `${appName}Topic`,
      });
    }
  }
}

For resource definitions using loop processing like this, you can write fine-grained assertions tests as follows:

import { App } from 'aws-cdk-lib';
import { Match, Template } from 'aws-cdk-lib/assertions';
import { MyStack } from '../lib/my-stack';

describe('Fine-grained assertions tests', () => {
  test('SNS Topics are created', () => {
    const appNames = ['App1', 'App1', 'App2'];
    const expectedNumberOfTopics = 2;

    const app = new App();
    const stack = new MyStack(app, 'MyStack', {
      appNames: appNames,
    });
    const template = Template.fromStack(stack);

    template.resourcePropertiesCountIs(
      'AWS::SNS::Topic',
      {
        DisplayName: Match.stringLikeRegexp('Topic'),
      },
      expectedNumberOfTopics,
    );
  });
});

2. Conditional Branching

When using conditional branching like if statements to change whether resources are generated per environment, it's also important to confirm that the conditional branching is working correctly.

Suppose you have the following CDK code:

import * as cdk from 'aws-cdk-lib';
import { CfnWebACL } from 'aws-cdk-lib/aws-waf';
import { Construct } from 'constructs';

export interface MyStackProps extends cdk.StackProps {
  isProd: boolean;
}

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: MyStackProps) {
    super(scope, id, props);

    if (props.isProd) {
      new CfnWebACL(this, 'WebAcl', {
        // ...
      });
    }
  }
}

To confirm that CfnWebACL is created when isProd is true, you can write a test like this:

import { App } from 'aws-cdk-lib';
import { Template } from 'aws-cdk-lib/assertions';
import { MyStack } from '../lib/my-stack';

describe('Fine-grained assertions tests', () => {
  test('Web ACL is created in prod', () => {
    const app = new App();
    const stack = new MyStack(app, 'MyStack', {
      isProd: true,
    });
    const template = Template.fromStack(stack);

    template.resourceCountIs('AWS::WAFv2::WebACL', 1);
  });
});

Now, for cases where you change whether to specify properties per environment:

import * as cdk from 'aws-cdk-lib';
import { Distribution } from 'aws-cdk-lib/aws-cloudfront';
import { Construct } from 'constructs';

export interface MyStackProps extends cdk.StackProps {
  isProd: boolean;
}

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: MyStackProps) {
    super(scope, id, props);

    // ...

    new Distribution(this, 'Distribution', {
      // ...
      webAclId: props.isProd ? webAclId : undefined,
    });
  }
}

For example, you can also write a test to confirm that webAclId is "not associated" when isProd is false.

The characteristic is that you can use the Match.absent method to confirm that the corresponding property has "no value specified".

import { App } from 'aws-cdk-lib';
import { Match, Template } from 'aws-cdk-lib/assertions';
import { MyStack } from '../lib/my-stack';

describe('Fine-grained assertions tests', () => {
  test('Web ACL is not associated in dev', () => {
    const app = new App();
    const stack = new MyStack(app, 'MyStack', {
      isProd: false,
    });
    const template = Template.fromStack(stack);

    template.hasResourceProperties('AWS::CloudFront::Distribution', {
      DistributionConfig: {
        // Confirm that WebACLId property is not specified
        WebACLId: Match.absent(),
      },
    });
  });
});

3. Property Override

In AWS CDK, it's common to define resources using L2 Constructs provided by CDK.

However, in cases where you want to set properties not supported by L2 Constructs, you may use escape hatches to cast to L1 Constructs and then override properties using methods like addPropertyOverride.

In this case, you can't use Construct types for property specification and need to write properties according to the CloudFormation template structure yourself, making description mistakes more likely to occur, especially for hierarchical properties.

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { Bucket, CfnBucket } from 'aws-cdk-lib/aws-s3';

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    const bucket = new Bucket(this, 'Bucket');

    // Use escape hatch on Bucket to override properties
    const cfnSrcBucket = bucket.node.defaultChild as CfnBucket;
    cfnSrcBucket.addPropertyOverride('NotificationConfiguration.EventBridgeConfiguration.EventBridgeEnabled', true);
  }
}

When using override to overwrite resource definitions like this, you can write tests to confirm that it's reflected as intended.

import { App, assertions } from 'aws-cdk-lib';
import { Match, Template } from 'aws-cdk-lib/assertions';
import { MyStack } from '../lib/my-stack';

const getTemplate = (): assertions.Template => {
  const app = new App();
  const stack = new MyStack(app, 'MyStack');
  return Template.fromStack(stack);
};

describe('Fine-grained assertions tests', () => {
  // Whether properties are correctly overridden using escape hatch
  test('EventBridge is enabled', () => {
    const template = getTemplate();
    template.hasResourceProperties('AWS::S3::Bucket', {
      NotificationConfiguration: {
        EventBridgeConfiguration: { EventBridgeEnabled: true },
      },
    });
  });
});

4. Definitions You Especially Want to Guarantee

Next is the case of writing tests for definitions you especially want to guarantee.

This is a test for "declarative" code writing as I explained at the beginning.

Earlier, I explained as if we wouldn't write fine-grained assertions tests for "declarative," i.e., resource definitions that are self-evident, but it's also important to write tests for definitions you especially want to guarantee.

For example, you can write tests as a form of "intention declaration" for important definitions compared to other properties, such as "we want to set this property to realize certain requirements." If another developer changes that setting in the future, the corresponding test will fail, and by referring to the failed test, they can understand the original designer's intention, leading to the propagation of intention.

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { Bucket } from 'aws-cdk-lib/aws-s3';

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new Bucket(this, 'Bucket', {
      lifecycleRules: [{ expiration: cdk.Duration.days(100) }],
    });
  }
}

If you want to guarantee the expiration setting in this lifecycleRules, you can write a test like this:

import { App, assertions } from 'aws-cdk-lib';
import { Template } from 'aws-cdk-lib/assertions';
import { MyStack } from '../lib/my-stack';

const getTemplate = (): assertions.Template => {
  const app = new App();
  const stack = new MyStack(app, 'MyStack');
  return Template.fromStack(stack);
};

describe('Fine-grained assertions tests', () => {
  test('Expiration for lifecycle must be specified', () => {
    const template = getTemplate();

    template.hasResourceProperties('AWS::S3::Bucket', {
      LifecycleConfiguration: {
        Rules: [
          {
            ExpirationInDays: 100,
            Status: 'Enabled',
          },
        ],
      },
    });
  });
});

In this case, when you change property values due to requirement changes during development, you need to change the test side values accordingly. If you just want to confirm whether a property can be specified, you can use the Match.anyValue method to confirm without specifying specific values, which can reduce test maintenance costs.

import { Match } from 'aws-cdk-lib/assertions';

// ...

template.hasResourceProperties('AWS::S3::Bucket', {
  LifecycleConfiguration: {
    Rules: [
      {
        ExpirationInDays: Match.anyValue(),
        Status: 'Enabled',
      },
    ],
  },
});

Also, when adding definitions using methods provided by CDK like addDependency, there may be cases where you want to guarantee that it's reflected as intended.

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { LogGroup, ResourcePolicy } from 'aws-cdk-lib/aws-logs';
import { PolicyStatement, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
import { HostedZone } from 'aws-cdk-lib/aws-route53';
import { Bucket, CfnBucket } from 'aws-cdk-lib/aws-s3';

export interface MyStackProps extends cdk.StackProps {
  domainName: string;
}

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: MyStackProps) {
    super(scope, id, props);

    const logGroup = new LogGroup(this, 'QueryLogGroup');
    const hostedZone = new HostedZone(this, 'HostedZone', {
      zoneName: props.domainName,
      queryLogsLogGroupArn: logGroup.logGroupArn,
    });
    const resourcePolicy = new ResourcePolicy(this, 'QueryLogResourcePolicy', {
      policyStatements: [
        new PolicyStatement({
          principals: [new ServicePrincipal('route53.amazonaws.com')],
          actions: ['logs:CreateLogStream', 'logs:PutLogEvents'],
          resources: [logGroup.logGroupArn],
        }),
      ],
    });

    // Make HostedZone depend on QueryLogResourcePolicy
    hostedZone.node.addDependency(resourcePolicy);
  }
}

In this example, you can confirm whether the expected dependencies are added between resources by writing a test like this:

import { App, assertions } from 'aws-cdk-lib';
import { Match, Template } from 'aws-cdk-lib/assertions';
import { MyStack } from '../lib/my-stack';

const getTemplate = (): assertions.Template => {
  const app = new App();
  const stack = new MyStack(app, 'MyStack', {
    domainName: 'example.com',
  });
  return Template.fromStack(stack);
};

describe('Fine-grained assertions tests', () => {
  // Whether intended dependencies are defined by addDependency
  test('HostedZone depends on QueryLogResourcePolicy', () => {
    const template = getTemplate();
    template.hasResource('AWS::Route53::HostedZone', {
      DependsOn: [Match.stringLikeRegexp('QueryLogResourcePolicy')],
    });
  });
});

5. Value Specification Using Props

Fine-grained assertions tests are also useful in scenarios where you specify resource properties using props values passed to Stacks or Constructs. Specifically, you write tests to confirm that props values are correctly reflected in resources.

This helps prevent forgetting to pass values that can occur when resource properties are not "hard-coded" with specific values directly.

import { App, assertions } from 'aws-cdk-lib';
import { Template } from 'aws-cdk-lib/assertions';
import { MyStack } from '../lib/my-stack';

const getTemplate = (): assertions.Template => {
  const app = new App();
  const stack = new MyStack(app, 'MyStack', {
    messageRetentionPeriodInDays: 10,
  });
  return Template.fromStack(stack);
};

describe('Fine-grained assertions tests', () => {
  test('messageRetentionPeriodInDays from props', () => {
    const template = getTemplate();

    template.hasResourceProperties('AWS::SNS::Topic', {
      // Confirm that props values are correctly passed
      ArchivePolicy: { MessageRetentionPeriod: 10 },
    });
  });
});

Also, to test resource definitions with actually deployed CDK code, I think there are many cases where you want to use the props defined for passing to the actual Stack as-is rather than test-specific props.

In this case, you can guarantee that values passed from props are specified without specifying specific values by using the properties that the props have for confirmation, reducing test maintenance costs.

import { App, assertions } from 'aws-cdk-lib';
import { Template } from 'aws-cdk-lib/assertions';
import { myStackProps } from '../lib/config';
import { MyStack } from '../lib/my-stack';

const getTemplate = (): assertions.Template => {
  const app = new App();

  // Use the props defined for passing to the actual Stack as-is
  const stack = new MyStack(app, 'MyStack', myStackProps);

  return Template.fromStack(stack);
};

describe('Fine-grained assertions tests', () => {
  test('messageRetentionPeriodInDays from props', () => {
    const template = getTemplate();

    template.hasResourceProperties('AWS::SNS::Topic', {
      ArchivePolicy: { MessageRetentionPeriod: myStackProps.messageRetentionPeriod },
    });
  });
});

Validation Tests

What are Validation Tests?

The third type I'll explain, validation tests, are tests related to validation as the name suggests.

Validation refers to processing that verifies the validity of values through conditional branching and other means. In AWS CDK, validation processing is sometimes implemented for properties of props that are inputs to Stacks or Constructs.

For example, in validation tests, you can write code to verify that input values for certain properties fall within a specific range.

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { Bucket } from 'aws-cdk-lib/aws-s3';

export interface MyStackProps extends cdk.StackProps {
  lifecycleDays: number;
}

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: MyStackProps) {
    super(scope, id, props);

    if (!cdk.Token.isUnresolved(props.lifecycleDays) && props.lifecycleDays > 400) {
      throw new Error('Lifecycle days must be 400 days or less');
    }

    new Bucket(this, 'Bucket', {
      lifecycleRules: [
        {
          expiration: cdk.Duration.days(props.lifecycleDays),
        },
      ],
    });
  }
}

*The cdk.Token.isUnresolved method is a method to check whether a value is not a Token.

For such CDK code, you can write validation tests like this. It's a test to confirm that an error occurs when unacceptable input values are passed.

import { App } from 'aws-cdk-lib';
import { MyStack } from '../lib/my-stack';

describe('Validation tests', () => {
  test('lifecycle days must be lower than or equal to 400 days', () => {
    const app = new App();

    expect(() => {
      new MyStack(app, 'MyStack', { lifecycleDays: 500 });
    }).toThrowError('Lifecycle days must be 400 days or less');
  });
});

Use Cases for Validation Tests

When you implement any validation processing for properties received by Stacks or Constructs, whether that validation processing is working correctly is a very important confirmation item, so validation tests are definitely tests you want to write. It would be good to write test cases for each validation.

Conversely, if you don't implement any particular validation processing, they become unnecessary.

Good Things to Know About CDK Unit Tests

Count Checks and Auto-generated Resources

In fine-grained assertions tests, you can write tests to confirm the count of specific resource types using methods like resourceCountIs of the Template class in the assertions module.

const template = Template.fromStack(stack);
template.resourceCountIs('AWS::Logs::LogGroup', 5);

On the other hand, L2 Constructs commonly used in CDK sometimes automatically generate several resources internally to follow best practices or provide a better developer experience. So, for example, like the test above, even if you think you defined 5 resources of that type, there might actually be 6 resources generated.

Also, even if you set the count to 6 in the test considering such cases, when you look at that value later, the breakdown may be unclear, leading to confusion and cognitive load, so be careful. Unless you particularly want to confirm the count including auto-generated resources, auto-generated resources can also be confirmed from snapshot test update differences, so it might be good to consider simply omitting such count checks. If you still want to keep the test, it's also good to write comments clearly so the intention is understood.

Alternatively, please consider using the resourcePropertiesCountIs method to test counts limited to resources with specific properties or values.

const template = Template.fromStack(stack);
template.resourcePropertiesCountIs(
  'AWS::Logs::LogGroup',
  {
    // Limited to log groups with the naming convention '/aws/lambda/my-app/'
    LogGroupName: Match.stringLikeRegexp('/aws/lambda/my-app/'),
  },
  5,
);

Tests per Construct

In this article, I basically introduced examples of unit tests for actually defined Stack classes.

However, when writing CDK code, you often create custom Constructs and combine them to define Stacks.

In such cases, by writing unit tests for each custom Construct, you can perform tests within the scope of that Construct and confirm behavior without being affected by other Constructs. This allows you to guarantee the reliability and reusability of individual Constructs.

Also, by separating test files for each Construct, each test file becomes cohesive by responsibility and simpler, which might increase understandability.

Specifically, you can define an empty stack and add only the custom Construct you want to test to perform tests.

import { Stack } from 'aws-cdk-lib';
import { Template } from 'aws-cdk-lib/assertions';
import { MyConstruct } from '../lib/constructs/my-construct';

test('Construct Tests', () => {
  // Define an empty stack
  const stack = new Stack();

  // Add the Construct you want to test to the above Stack
  new MyConstruct(stack, 'MyConstruct', {
    messageRetentionPeriodInDays: 10,
  });

  const template = Template.fromStack(stack);

  template.hasResourceProperties('AWS::SNS::Topic', {
    ArchivePolicy: { MessageRetentionPeriod: 10 },
  });
});

However, as the number of Constructs increases, trying to write tests for every Construct can result in a very large number of tests. Also, even if you write tests for each Construct, you definitely want to write tests for the Stack that becomes the actual deployed environment configuration. In that case, you need to be careful because if you don't properly separate the test scope and responsibilities to avoid duplication between Stack tests and Construct tests, test maintenance can become difficult.

It might be good to use the distinction of writing Construct-level tests only for Constructs where you especially want to guarantee reusability. Alternatively, if there are no particular cases of reusing Constructs, the option of not writing unit tests for each Construct is also fine.

Recommended Minimal Configuration

Introducing all the tests introduced in this article together can be quite challenging.

Therefore, if you want to introduce CDK unit tests easily with minimal configuration, it's good to start with snapshot tests first. They are easy to introduce and the ability to detect unexpected changes in deployed CloudFormation templates is a very significant benefit.

Summary

I introduced the following three types of unit tests in AWS CDK and their use cases:

Snapshot tests
Fine-grained assertions tests
Validation tests

How to Choose Validation Approaches in AWS CDK

Kenta Goto — Tue, 05 Aug 2025 12:31:58 +0000

Table of Contents
Introduction
Validation in AWS CDK
AWS CDK Application Lifecycle
Validation Methods in AWS CDK
- 1. Immediate Throw
- 2. Aspects
- 3. addValidation
- 4. Annotations
Supplement: Template Rewriting with addPropertyOverride
Summary

Introduction

In AWS CDK, validation of values received from users is essential for both those who use AWS CDK to build application and infrastructure environments and those who contribute to AWS CDK itself. Moreover, this validation method can be implemented in basically the same way for both perspectives.

This article introduces how to use validation methods that are common to both "users" and "developers" of AWS CDK.

Validation in AWS CDK

Since AWS CloudFormation operates internally in AWS CDK, if you deploy without validating incorrect values, errors may occur during stack creation or updates in CloudFormation. By performing validation within AWS CDK code, you can terminate the application with an error before CloudFormation deployment is executed, allowing users to prevent deployment errors in advance. This enables safer and more rapid error detection and correction.

AWS CDK Application Lifecycle

The timing of execution for various validation methods in AWS CDK differs according to the application lifecycle of AWS CDK. The AWS CDK lifecycle consists of the following four phases:

Construct phase
Prepare phase
Validate phase
Synthesize phase

For details on each phase, please refer to the AWS CDK Developer Guide. Basically, most of the CDK code written by users is executed in the first Construct phase.

Validation Methods in AWS CDK

The four validation methods in AWS CDK that we will introduce are:

Immediate Throw
Aspects
addValidation
Annotations

1. Immediate Throw

This is the simplest validation method when using AWS CDK. Note that the term "immediate throw" is not official naming but rather a name I have given for convenience in this article.

Immediate throw involves checking values received through props passed as the third argument during construct initialization, or arguments passed to construct methods, using "if" statements and similar logic, and generating errors when values are unacceptable for the application.

This method is executed in the Construct phase, which is the earliest stage among the four phases mentioned earlier, where construct generation processing occurs. Since early error detection can localize the impact of errors, it is generally recommended to consider using this method first.

Specifically, you check parameters received through construct props (here MyConstructProps) against application requirements using "if" statements, and throw errors when requirements are not met.

import { Construct } from 'constructs';

export interface MyConstructProps {
  readonly myFlag: boolean;
  readonly myParam?: number;
}

export class MyConstruct extends Construct {
  constructor(scope: Construct, id: string, props: MyConstructProps) {
    super(scope, id);

    if (props.myFlag && props.myParam !== undefined) {
      throw new Error('myParam cannot be specified when myFlag is true');
    }
  }
}

Token

There is one point to note with immediate throw: Token.

Token is a mechanism for storing values that will be resolved later in the lifecycle using temporary values. For example, it is used internally when handling number or string type values in AWS CDK that are represented by CloudFormation's !Ref and determined at deployment time.

This means that if a validation target parameter is a Token, the value is still unknown at this lifecycle stage, making validation impossible. Therefore, when performing validation with immediate throw, you need to check whether the parameter is a Token and skip validation if it is a Token.

Specifically, you use the isUnresolved method of the Token class to check if it's a Token, and only check validation conditions when it's not a Token (when it returns false). If a parameter is a Token, even if the user actually passes a value like 100, it stores a value unrelated to the actual value like -1.88815458970875e+289. If you put this through conditional logic like if (param < 0), it will cause unexpected errors.

import { Token } from 'aws-cdk-lib';
import { Construct } from 'constructs';

export interface MyConstructProps {
  readonly myParam: number;
}

export class MyConstruct extends Construct {
  constructor(scope: Construct, id: string, props: MyConstructProps) {
    super(scope, id);

    // When Token, Token.isUnresolved(props.myParam) returns true
    // If props.myParam is a Token, it stores values unrelated to the actual value like -1.88815458970875e+289
    if (!Token.isUnresolved(props.myParam) && props.myParam < 0) {
      throw new Error('myParam must be 0 or greater');
    }
  }
}

For example, valueAsString returned by the CfnParameter construct, or bucketName returned by the Bucket construct which is an L2 construct for Amazon S3 buckets, have values that are resolved during actual deployment, so they are stored as Tokens within CDK code. It's common to pass these parameters to constructs through props. However, since constructs themselves cannot know what comes from where through props parameters, and they always have the possibility of being Tokens, caution is required.

2. Aspects

Next is validation using the Aspects feature.

Aspects is a method for applying operations to all configurations within a specific scope, such as a stack or construct. This is executed in the Prepare phase, which is the second phase of the lifecycle.

Aspects is not specifically a validation feature, but it is effective when you want to centrally validate specific types of resources within a stack. For example, it can be used for validation like "Are versioning settings applied to all S3 buckets in the stack?"

import { App, Aspects, IAspect, Stack, Tokenization } from 'aws-cdk-lib';
import { CfnBucket } from 'aws-cdk-lib/aws-s3';
import { IConstruct } from 'constructs';

// Aspects is implemented by implementing the IAspect interface
export class BucketVersioningChecker implements IAspect {
  // Write validation content in the visit method
  public visit(node: IConstruct) {
    // Since the visit method is applied to all resources inside the Construct passed by Aspects, use conditional logic to execute only for CfnBucket resources
    if (node instanceof CfnBucket) {
      // Generate an error if bucket versioning configuration is disabled
      if (
        !node.versioningConfiguration ||
        (!Tokenization.isResolvable(node.versioningConfiguration) && node.versioningConfiguration.status !== 'Enabled')
      ) {
        throw new Error('Versioning is not enabled');
      }
    }
  }
}

const app = new App();
const stack = new Stack(app, 'MyStack');

// Apply BucketVersioningChecker to all resources in MyStack
Aspects.of(stack).add(new BucketVersioningChecker());

3. addValidation

Next is the validation method using the addValidation method.

The addValidation is a method of the Node class that Stack and Construct internally hold as variables, and is executed in the Validate phase, which is the third phase of the lifecycle.

The use case for the addValidation is for delayed evaluation to validate cases where parameter values change not only during construct initialization (when generating a construct with new) but also after construct methods are called.

For example, "There is an array-type parameter that can be set through both props and methods, and you want to check the number of elements in that array". This means cases where no array-type parameter is passed through props during construct generation, but elements are added to the array by calling construct methods afterward. In this scenario, if you perform validation immediately in the constructor and throw an error, it would only check the parameter state before any method calls are made. Therefore, the addValidation is optimal for such cases.

An implementation example of the addValidation is as follows:

export interface MyConstructProps {
  readonly myVariables: string[];
}

export class MyConstruct extends Construct {
  public readonly myVariables: string[];

  constructor(scope: Construct, id: string, props: MyConstructProps) {
    super(scope, id);
    this.myVariables = props.myVariables;

    // Pass an object of IValidation interface type with a validate method to addValidation
    this.node.addValidation({ validate: () => this.validateVariables() });
  }

  // For readability, the actual validation content is written in a separate method
  private validateVariables(): string[] {
    const errors: string[] = [];
    if (this.myVariables.length > 3) {
      errors.push(`myVariables should have at most 3 elements, current count: ${this.myVariables.length}`);
    }
    return errors;
  }

  // This method allows adding elements to the array after construct generation
  public addVariable(variable: string) {
    this.myVariables.push(variable);
  }
}

The addValidation method takes an object of IValidation interface type with a validate(): string[] method as an argument. You write the actual validation content in the validate method.

interface IValidation {
  validate(): string[];
}

Furthermore, a characteristic of addValidation is that instead of throwing errors, it stores error messages in a string[] type array and returns them. This allows displaying multiple errors at once.

  private validateVariables(): string[] {
    const errors: string[] = [];
    if (this.myVariables.length > 3) {
      errors.push(`myVariables should have at most 3 elements, current count: ${this.myVariables.length}`);
    }
    return errors;
  }

By using addValidation this way, even in cases where props don't pass any elements to the array and elements are added through methods after construct initialization, validation can be delayed and cause errors.

const app = new App();
const stack = new Stack(app, 'MyStack');
const myConstruct = new MyConstruct(stack, 'MyConstruct', { myVariables: [] });

myConstruct.addVariable('variable1');
myConstruct.addVariable('variable2');
myConstruct.addVariable('variable3');
myConstruct.addVariable('variable4');

Error: Validation failed with the following errors:
  [MyStack/MyConstruct] myVariables should have at most 3 elements, current count: 4

4. Annotations

Finally, there's the method using Annotations.

Annotations is a feature for attaching errors and warnings to constructs. This chapter focuses on error output methods rather than value checking methods. Since this can be called directly from constructs or from Aspects and addValidation, the processing execution timing depends on those phases, but the triggering (output) of attached errors is performed by the CDK CLI after all phases of the CDK application are completed.

For example, if you generate an error through Annotations within Aspects, that processing itself is executed in the Prepare phase and the error is attached to the construct. However, the error output processing to users is performed after all application phases are completed. If an error is detected by addValidation in the Validate phase after calling Annotations in Aspects, the Annotations error will not be triggered, meaning it will not be output.

Unlike previous methods, Annotations has the characteristic that you can issue warnings instead of errors by using the addWarningV2 method. This makes it effective for expressing "not good but not serious enough for an error". For example, it's often used when deprecated parameters are specified.

import { Annotations } from 'aws-cdk-lib';
import { Construct } from 'constructs';

export interface MyConstructProps {
  /**
    @deprecated Use `newParam` instead
   */
  readonly oldParam?: string;
  readonly newParam?: string;
  readonly arrayParam: string[];
}

export class MyConstruct extends Construct {
  constructor(scope: Construct, id: string, props: MyConstructProps) {
    super(scope, id);

    // Issue a warning when oldParam is specified
    if (props.oldParam !== undefined) {
      Annotations.of(this).addWarningV2(
        'MyConstruct:oldParam',
        `'oldParam' parameter is deprecated. Please use 'newParam' instead.`,
      );
    }

    // Issue an error when arrayParam is empty
    if (props.arrayParam.length === 0) {
      Annotations.of(this).addError(`'arrayParam' cannot be empty`);
    }
  }
}

You can also attach errors to constructs using the addError method. The behavior of this error is distinctive.

In Annotations, if an error is attached through the addError method, the error is output like other validations, but synthesis itself succeeds. Successful synthesis means that even when errors are output, cloud assembly is generated. Cloud assembly refers to manifest.json and AWS CloudFormation template files generated based on CDK code, stored in the cdk.out directory at the top level of the CDK project. Immediate throw and addValidation do not generate cloud assembly when errors occur.

This leads to different behavior in multi-stack applications. In multi-stack applications, if one stack has an error attached by Annotations, cdk synth and cdk deploy will fail for the stack with the attached error. However, synth and deploy will succeed for other normal stacks.

For example, if an application has two stacks, StackA and StackB, and StackA has an error attached by Annotations, cdk synth StackA will error, but cdk synth StackB will succeed. With immediate throw and similar methods, if one stack has an error, all other stacks will also fail.

While Annotations has these characteristics, it's generally safer to use immediate throw and similar methods. Cases for attaching errors with Annotations include situations where the CDK resource declaration is correct but errors occur due to environmental factors such as missing context values referenced through context methods. This usage pattern is also recommended in the AWS CDK repository's DESIGN_GUIDELINES.

It would also be the only approach when you want to issue warnings without making them errors.

Supplement: Template Rewriting with addPropertyOverride

In AWS CDK, you can directly rewrite the contents of CloudFormation templates generated during the Synthesize phase using methods like addPropertyOverride. This method allows you to forcibly enable S3 bucket versioning settings, for example.

import { CfnBucket } from 'aws-cdk-lib/aws-s3';

declare const cfnBucket: s3.CfnBucket;

cfnBucket.addPropertyOverride('VersioningConfiguration.Status', 'NewStatus');

This template rewriting process is executed in the Synthesize phase, which is the last phase of the AWS CDK lifecycle. This means that template rewriting is not yet reflected when the various validations mentioned earlier are executed. Therefore, these rewritten contents cannot be properly validated by any method. Caution is needed as unintended errors may occur in the following cases:

When declaring an S3 bucket construct, versioning configuration is not specified
addPropertyOverride is called in Aspects (Prepare phase) to set versioning configuration to enabled
Validation by addValidation (Validate phase) errors when there are S3 buckets without enabled versioning configuration

*policyValidationBeta1 allows validation in this case, but note that it is still an experimental feature.

Summary

We have introduced the following four validation methods in AWS CDK along with their characteristics and usage patterns:

Immediate Throw
Aspects
addValidation
Annotations

These are validation methods that can be used commonly whether you're "using" or "developing" AWS CDK. By understanding the characteristics of each and selecting appropriate validation methods, let's write safer and more reliable AWS CDK code.

Easily Delete S3 Vectors with cls3

Kenta Goto — Wed, 30 Jul 2025 06:57:35 +0000

Amazon S3 Vectors

S3 Vectors

In July 2025, Amazon S3 Vectors, a new service, was announced. (As of July 2025, this is still in preview.)

AWS Blog: Introducing Amazon S3 Vectors

For more details, please refer to the following documentation:

Amazon S3 User Guide: S3 Vectors

S3 Bucket Types

With the introduction of S3 Vectors, Vector Buckets have been added as a new type of bucket in S3.

This means S3 now has the following types of buckets:

General Buckets
- Traditional S3 buckets
Directory Buckets
- S3 Express One Zone
Table Buckets
- S3 Tables
Vector Buckets
- S3 Vectors
- Still in preview as of July 2025

S3 Vectors Components

The components of Vector Buckets in S3 Vectors are as follows:

Vector Bucket
- Stores multiple indexes
Index
- Stores vector data

To delete a Vector Bucket, you must first delete all indexes within it.

With cls3, I've made this simple - you can now do it with a single command.

cls3

What is cls3?

cls3 is a convenient CLI tool for S3 deletion that I develop as an OSS project.

Blog post about cls3

The GitHub repository is here. (Stars would be appreciated!)

cls3 GitHub Repository

Existing Features

Please refer to the blog post and GitHub repository mentioned above for details.

Specifically, cls3 can:

Delete buckets or empty them
Search and select multiple buckets in interactive mode
Delete multiple buckets in parallel
Delete multiple buckets across regions
Delete buckets with versioning enabled
Delete only old versions of objects
Delete Directory Buckets for S3 Express One Zone
Delete Table Buckets for S3 Tables
Delete only objects with specific key prefixes
Provide features for GitHub Actions
Automatically retry on throttling errors during bulk deletions

Installation

Various installation methods are available:

Homebrew
One-liner script
- Linux, Darwin (macOS) and Windows
aqua
asdf
GitHub Releases
- Direct download from browser
Git clone + install
- For developers using Go

*For detailed installation instructions, see the following link:

Installation Guide

S3 Vectors Vector Bucket Deletion Feature

Vector Buckets Mode

The functionality to delete S3 Vectors Vector Buckets has been added to cls3 v0.27.0.

cls3 allows you to specify bucket names directly using the CLI option (-b), or specify buckets interactively through interactive mode (-i) by searching.

With this release, I've introduced Vector Buckets Mode, which makes it easy to delete S3 Vectors Vector Buckets as shown below: (using interactive mode as an example)

The "-V (uppercase) | --vectorBucketsMode" option deletes the contents of Vector Buckets, specifically all indexes in the specified Vector Bucket.

When combined with "-f | --forceMode", you can delete the entire Vector Bucket in addition to all indexes.

When combined with "-k | --keyPrefix", you can delete only indexes with specific prefixes.

Important Notes

S3 Vectors is still in preview, and API specifications may change in the future.

Therefore, Vector Buckets Mode might temporarily become unavailable. When this happens, cls3's Vector Buckets Mode will be updated to match future S3 Vectors specification changes.

Additionally, since this is currently in preview, the API behavior can be unstable at times. For this reason, cls3 internally sets certain parallel execution limits. I plan to tune this in the future.

Summary

I've introduced functionality to easily delete S3 Vectors Vector Buckets in cls3.

I hope this will encourage you to use this tool not only for S3 Vectors but also for deleting regular S3 buckets. I believe it will be very useful.

AWS CDK: Resources and Causes of Replacement in Non-Stage to Stage Migration

Kenta Goto — Mon, 28 Jul 2025 11:18:36 +0000

What is a Stage

AWS CDK has a concept called Stage. This is like an abstraction of stacks, and using Stages makes it easier to manage multiple stacks together.

For specific examples, I have covered them in the following article:

How to Use AWS CDK Stage and When to Choose Static vs Dynamic Stack Creation

Resource Replacement in Stages

In CDK, a resource is replaced when its logical ID is changed.

Additionally, migrating non-Stage resources to a Stage changes the Construct path.

However, since logical IDs are generated based on the construct path below the stack, logical IDs basically do not change even when migrating to a Stage. In other words, resource replacement does not occur in most cases.

Resources That Get Replaced When Migrating to Stage and Their Causes

However, some resources do get replaced when migrating from non-Stage to Stage.

There are three causes for replacement of these resources:

Logical ID changes
Physical name changes
Replacement property changes

Fundamentally, the information that changes when migrating non-Stage resources to a Stage is information based on the Construct path.

For example, this.node.path and this.node.addr. Similarly, Names.nodeUniqueId and Names.uniqueId, which generate unique IDs using that information, are also affected.

Let's look at specific resource examples.

* Note: The resource examples introduced below are only some of the resources that get replaced. This is not a comprehensive list. Please be aware that there are other resources that may get replaced.

SecurityGroup

First, with SecurityGroup, replacement occurs due to a change in a Replacement property called GroupDescription in CloudFormation.

When you explicitly specify a value for description in SecurityGroupProps, replacement does not occur. However, when unspecified, the Construct path this.node.path is used. When migrating to a Stage, the path changes, resulting in a change to the GroupDescription value.

The CDK internal code that causes this is as follows:

packages/aws-cdk-lib/aws-ec2/lib/security-group.ts

const groupDescription = props.description || this.node.path;

SecurityGroup Ingress/Egress Rules

Replacement also occurs with SecurityGroup Ingress/Egress rules.

Specifically, replacement occurs with addIngressRule (SecurityGroupIngress) and with addEgressRule (SecurityGroupEgress) when allowAllOutbound is false.

This is caused by logical ID changes.

const sg1 = new SecurityGroup(this, 'SecurityGroup1', {
  vpc: vpc,
  allowAllOutbound: true,
});
const sg2 = new SecurityGroup(this, 'SecurityGroup2', {
  vpc: vpc,
  allowAllOutbound: false, // Rules won't be added with addEgressRule when true
});

sg2.addIngressRule(sg1, Port.tcp(80), 'Allow traffic from sg1 to sg2 on port 80');
sg2.addEgressRule(sg1, Port.tcp(80), 'Allow traffic from sg2 to sg1 on port 80');

The CDK internal code that causes this is as follows:

this.uniqueId and peer.uniqueId internally use a method called Names.nodeUniqueId(this.node), which outputs a unique ID based on the construct path.

Since this value is ultimately passed to the resource's Construct ID and used as the logical ID, when migrating to a Stage, this result changes, and replacement occurs due to the logical ID change.

packages/aws-cdk-lib/aws-ec2/lib/security-group.ts

  protected determineRuleScope(
    peer: IPeer,
    connection: Port,
    fromTo: 'from' | 'to',
    remoteRule?: boolean): RuleScope {
    if (remoteRule && SecurityGroupBase.isSecurityGroup(peer) && differentStacks(this, peer)) {
      // Reversed
      const reversedFromTo = fromTo === 'from' ? 'to' : 'from';
      return { scope: peer, id: `${this.uniqueId}:${connection} ${reversedFromTo}` };
    } else {
      // Regular (do old ID escaping to in order to not disturb existing deployments)
      return { scope: this, id: `${fromTo} ${this.renderPeer(peer)}:${connection}`.replace('/', '_') };
    }
  }

  private renderPeer(peer: IPeer) {
    if (Token.isUnresolved(peer.uniqueId)) {
      // Need to return a unique value each time a peer
      // is an unresolved token, else the duplicate skipper
      // in `sg.addXxxRule` can detect unique rules as duplicates
      return this.peerAsTokenCount++ ? `'{IndirectPeer${this.peerAsTokenCount}}'` : '{IndirectPeer}';
    } else {
      return peer.uniqueId;
    }
  }

StepFunctions LogGroup in CustomResource Provider

In the CustomResource Provider construct, when isCompleteHandler is specified, a StepFunctions StateMachine is created internally.

const isCompleteHandler = new Function(this, 'MyFunction', {
  runtime: Runtime.NODEJS_22_X,
  handler: 'index.handler',
  code: Code.fromAsset(path.join(__dirname, 'lambda')),
});
new Provider(this, 'Provider', {
  onEventHandler,
  isCompleteHandler,
});

In the LogGroup of this StateMachine, this.node.addr is used for the log group name (logGroupName), which is the physical name.

Also, this.node.addr is a hash value generated based on the construct path.

When migrating to a Stage, this value changes, causing the physical name to change and replacement to occur.

The CDK internal code that causes this is as follows:

packages/aws-cdk-lib/custom-resources/lib/provider-framework/waiter-state-machine.ts

const logGroup =
  logOptions?.destination ??
  new LogGroup(this, 'LogGroup', {
    // Log group name should start with `/aws/vendedlogs/` to not exceed Cloudwatch Logs Resource Policy
    // size limit.
    // https://docs.aws.amazon.com/step-functions/latest/dg/bp-cwl.html
    //
    // By using the auto-generated name of the Lambda created in the `Provider` that calls this
    // `WaiterStateMachine` construct, even if the `Provider` (or its parent) is deleted and then
    // created again, the log group name will not duplicate previously created one with removal
    // policy `RETAIN`. This is because that the Lambda will be re-created again with auto-generated name.
    // The `node.addr` is also used to prevent duplicate names no matter how many times this construct
    // is created in the stack. It will not duplicate if called on other stacks.
    logGroupName: `/aws/vendedlogs/states/waiter-state-machine-${this.isCompleteHandler.functionName}-${this.node.addr}`,
  });

Lambda Event Source

When using SqsEventSource or SnsEventSource with the Lambda Function's addEventSource method, replacement also occurs because the logical ID changes during Stage migration. Other event sources like S3EventSource, DynamoEventSource, and KinesisEventSource behave similarly.

const func = new Function(this, 'MyFunction', {
  runtime: Runtime.NODEJS_22_X,
  handler: 'index.handler',
  code: Code.fromAsset(path.join(__dirname, 'lambda')),
});

func.addEventSource(new SqsEventSource(queue));
func.addEventSource(new SnsEventSource(topic));

However, when using the addEventSourceMapping method or EventSourceMapping Construct, replacement does not occur.

func.addEventSourceMapping('MyEventSourceMapping', {
  eventSourceArn: 'arn:aws:sqs:us-east-1:123456789012:MyQueue',
});

new EventSourceMapping(this, id, {
  target: func,
  eventSourceArn: 'arn:aws:sqs:us-east-1:123456789012:MyQueue',
});

The corresponding CDK internal code is as follows:

In SqsEventSource, Names.nodeUniqueId is used, which is passed to the EventSourceMapping's Construct ID and used for logical ID generation. When migrating to a Stage, this value changes, and replacement occurs due to the logical ID change.

packages/aws-cdk-lib/aws-lambda-event-sources/lib/sqs.ts

  public bind(target: lambda.IFunction) {
    const eventSourceMapping = target.addEventSourceMapping(`SqsEventSource:${Names.nodeUniqueId(this.queue.node)}`, {
      batchSize: this.props.batchSize,
      maxBatchingWindow: this.props.maxBatchingWindow,
      maxConcurrency: this.props.maxConcurrency,
      reportBatchItemFailures: this.props.reportBatchItemFailures,
      enabled: this.props.enabled,
      eventSourceArn: this.queue.queueArn,
      filters: this.props.filters,
      filterEncryption: this.props.filterEncryption,
      metricsConfig: this.props.metricsConfig,
    });

Also, while the above SqsEventSource changes the logical ID of AWS::Lambda::EventSourceMapping, SnsEventSource changes the logical ID of AWS::Lambda::Permission.

This is due to the implementation of the LambdaSubscription class that is called internally, rather than the EventSource itself. Here too, Names.nodeUniqueId is used.

packages/aws-cdk-lib/aws-sns-subscriptions/lib/lambda.ts

  public bind(topic: sns.ITopic): sns.TopicSubscriptionConfig {
    // Create subscription under *consuming* construct to make sure it ends up
    // in the correct stack in cases of cross-stack subscriptions.
    if (!Construct.isConstruct(this.fn)) {
      throw new ValidationError('The supplied lambda Function object must be an instance of Construct', topic);
    }

    this.fn.addPermission(`AllowInvoke:${Names.nodeUniqueId(topic.node)}`, {
      sourceArn: topic.topicArn,
      principal: new iam.ServicePrincipal('sns.amazonaws.com'),
    });

SNS Topic Lambda Subscription

As mentioned above, when using LambdaSubscription (aws-cdk-lib/aws-sns-subscriptions) with the SNS Topic's addSubscription method, replacement also occurs during Stage migration.

const topic = new Topic(this, 'MyTopic');
const func = new Function(this, 'MyFunction', {
  runtime: Runtime.NODEJS_22_X,
  handler: 'index.handler',
  code: Code.fromAsset(path.join(__dirname, 'lambda')),
});

topic.addSubscription(new LambdaSubscription(func));

S3 Bucket Lambda Notification (Destination)

When using LambdaDestination (aws-cdk-lib/aws-s3-notifications) with the S3 Bucket's addEventNotification method, replacement of AWS::Lambda::Permission similar to the above cases also occurs during Stage migration.

const bucket = new Bucket(this, 'MyBucket');
const func = new Function(this, 'MyFunction', {
  runtime: Runtime.NODEJS_22_X,
  handler: 'index.handler',
  code: Code.fromAsset(path.join(__dirname, 'lambda')),
});

bucket.addEventNotification(EventType.OBJECT_CREATED, new LambdaDestination(func));

fromGeneratedSecret in RDS Credentials

When using fromGeneratedSecret for credentials in RDS/Aurora DatabaseCluster etc., replacement also occurs because the logical ID changes during Stage migration. Here, the logical ID of the SecretsManager Secret is changed.

Also, when using methods like fromPassword, fromUsername, or fromSecret, replacement does not occur.

new DatabaseCluster(this, 'Cluster', {
  engine,
  vpc,
  writer,
  credentials: Credentials.fromGeneratedSecret('clusteradmin'),
});

The corresponding CDK internal code is as follows:

Specifically, within the internally called DatabaseSecret, the logical ID is overridden (overrideLogicalId) with a value using Names.uniqueId.

packages/aws-cdk-lib/aws-rds/lib/database-secret.ts

if (props.replaceOnPasswordCriteriaChanges) {
  const hash = md5hash(
    JSON.stringify({
      // Use here the options that influence the password generation.
      // If at some point we add other password customization options
      // they should be added here below (e.g. `passwordLength`).
      excludeCharacters,
    }),
  );
  const logicalId = `${Names.uniqueId(this)}${hash}`;

  const secret = this.node.defaultChild as secretsmanager.CfnSecret;
  secret.overrideLogicalId(logicalId.slice(-255)); // Take last 255 chars
}

Summary

Basically, logical IDs do not change when migrating to a Stage, so replacement does not occur. However, since some resources may experience replacement, it's good to verify with snapshot tests and similar methods.

DEV Community: Kenta Goto

AWS CDK Deployment Best Practices

Best Practices for AWS CDK Deployment

Disclaimer

1. Use Static Stack Creation + Stage

Static Stack Creation vs Dynamic Stack Creation

Why Static Stack Creation Is Recommended

Cases Where Dynamic Stack Creation Is a Better Fit

Hybrid Approach

Benefits of Stage

Notes on Migrating to Stage

2. Synthesize Once, Deploy Many

The Risk of Running Synthesis Multiple Times

How to Achieve This in a CI/CD Pipeline

3. Separate the Asset Build/Publish and Deploy Phases

Benefits of Phase Separation

The cdk publish-assets Command

Example of Phase Separation in a CI/CD Pipeline

Reference

4. Commit cdk.context.json

What Is cdk.context.json?

Benefits of Committing cdk.context.json

Avoiding Non-Deterministic Behavior

Improving Deployment Speed

More Details on cdk.context.json

Official Documentation

Summary

AWS CDK Tips: How to Centrally Apply Configurations to Multiple Resources

1. Aspects

1-1. How to Use Aspects

1-2. Reference Article for Aspects

1-3. Adjusting the Execution Order of Multiple Aspects

2. PropertyInjectors

2-1. How to Use PropertyInjectors

2-2. Avoiding Infinite Loops

2-3. Differences Between Aspects and PropertyInjectors

2-4. When to Use Aspects vs PropertyInjectors

2-5. Notes on PropertyInjectors Application Timing

3. Mixins

3-1. How to Use Mixins

3-2. Creating Custom Mixins

3-3. Differences Between Mixins and Aspects

3-4. Differences Between Mixins and PropertyInjectors

4. RemovalPolicies

4-1. How to Use RemovalPolicies

4-2. MissingRemovalPolicies

Conclusion

Zero Orphaned Resources: Force Deleting Any CloudFormation Stack

DELETE_FAILED and FORCE_DELETE_STACK

When Stack Deletion Gets Complicated

Inter-Stack Dependencies

Slow Deletion Due to VPC Lambda

Resource Orphaning from Retain Policies

Deletion Protection

delstack Solves All of These

Force Deletion of DELETE_FAILED Resources: Zero Orphaned Resources

Automatic Dependency Resolution with Parallel Deletion

VPC Lambda Pre-Optimization

Retain Policy Override

Automatic Deletion Protection Removal

CDK Integration

How to Use

Conclusion

Why is cdk.out (Cloud Assembly) Necessary in AWS CDK?

What is cdk.out

What is the Cloud Assembly

Components of the Cloud Assembly

Why cdk.out is Necessary

Risks of Running Synthesis Multiple Times

Reusing cdk.out with the --app Option

Separating Synthesis and Deployment

synthesize once, deploy many

Other Benefits and Use Cases of cdk.out

Asset Caching

Utilizing cdk.out in CI/CD Pipelines

Reference Materials

cdk.out Bloat and How to Deal with It

cdk.out Bloat

cdk-agc

Conclusion

Reusing cdk.out with the `--app` Option