When working with AWS CDK (Cloud Development Kit), the cdk.out folder plays a crucial role in the deployment process. It contains synthesized CloudFormation templates and assets required for deploying your stacks. However, as your project evolves and you perform multiple deploys, especially in monorepos (a best practice for managing large-scale projects), the cdk.out folder can grow significantly in size. This can lead to inefficiencies and wasted disk space.

In my case, I have created a small Python script to remove unused resources in order to avoid annoying pop-up message “Insufficient disk space” on my corporate laptop.

Why Does the cdk.out Folder Grow?

Each time you run cdk deploy or cdk synth, AWS CDK generates new CloudFormation templates and assets, such as Lambda function code, Docker images, or other resources. These assets are stored in the cdk.out folder. Over time, as you deploy new versions of your stacks or add new stacks to your project, the folder accumulates outdated assets that are no longer referenced by your current CloudFormation templates.

The Problem with Deleting the cdk.out Folder

A straightforward solution might seem to be deleting the cdk.out folder periodically to free up space. While this is possible, it introduces a significant drawback: the next cdk synth or cdk deploy will take much longer. This is because AWS CDK needs to regenerate all the assets and templates from scratch, which can be time-consuming for large projects.

A Smarter Solution: Cleaning Up Unused Assets

A more efficient approach is to clean up only the unused assets in the cdk.out folder while preserving the ones still referenced by your CloudFormation templates. This can be achieved by running a script that reads the CloudFormation templates from the cdk.out folder and removes all assets that are no longer listed in the templates.

Before running the cleanup script, it is recommended to perform a cdk synth with all context enabled. This ensures that all AWS CloudFormation stacks are present in the cdk.out folder, and the script can accurately identify which assets are still in use.

Steps to Clean Up the cdk.out Folder

1. Run cdk synth with All Context Enabled:

Ensure that all stacks are synthesized and present in the cdk.out folder. This step is crucial for the cleanup script to work effectively.

   cdk synth

or

   cdk synth --context ...

2. Execute the Cleanup Script:

Use a script that reads the CloudFormation templates from the cdk.out folder and removes unused assets. This script ensures that only outdated assets are deleted, keeping the folder size manageable without impacting the next deploy. You can find a single-file script for this purpose here. Simply download and run the script in your project directory.

In my case, running my cleanup script reduced the cdk.out folder size from 15GB to 2GB, demonstrating significant space savings.

3. Verify and Deploy:

After running the script, verify that the cdk.out folder contains only the necessary assets. You can then proceed with your next cdk deploy as usual.

Benefits and Conclusion

Managing the cdk.out folder is an important aspect of working with AWS CDK, especially in large-scale projects and monorepos. While deleting the folder entirely can free up disk space, it comes with a clear drawback: longer cdk synth and cdk deploy times due to the need to regenerate all assets.

Using a cleanup script that removes only unused assets provides a more efficient alternative. It keeps disk usage under control without impacting deployment performance, since referenced assets are preserved and do not need to be rebuilt. This approach scales particularly well in monorepos, where multiple stacks and frequent deploys can quickly cause the cdk.out folder to grow.

For accurate results, remember to run a cdk synth with all context enabled before executing the cleanup script. By adopting this approach, you can maintain a clean cdk.out folder, improve deployment efficiency, and keep your AWS CDK workflow running smoothly.

By adopting this approach, you can maintain a streamlined workflow and keep your AWS CDK projects running smoothly. Check out the cleanup script here and give it a try!

For further discussion, you can refer to the related GitHub issue: AWS CDK CLI Issue #786.