This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.

Preserve deployed resources when refactoring CDK code

With AWS Cloud Development Kit (AWS CDK) refactoring, you can refactor your CDK code, such as renaming constructs, moving resources between stacks, and reorganizing your application, while preserving your deployed resources instead of replacing them. This feature helps you maintain good software engineering best practices without resulting in unintentional resource replacements.

What is CDK refactoring with resource preservation?

When you deploy a CDK application, AWS CloudFormation identifies resources by their logical IDs. The AWS CDK generates these logical IDs based on the construct ID and its path in the construct tree. If you change a construct’s ID or move it to a different location in your code, AWS CloudFormation typically interprets this as a request to create a new resource and delete the old one. For stateful resources such as databases, storage buckets, or queues, this replacement can cause service interruptions or data loss.

CDK refactoring addresses this challenge by:

You can perform CDK refactoring using either the CDK CLI cdk refactor command or the CDK Toolkit Library’s refactor action. This guide primarily discusses the CLI approach, but the underlying principles apply to both methods. For information on using the Toolkit Library, see Perform programmatic actions using the CDK Toolkit Library.

Benefits of CDK refactoring

CDK refactoring offers the following benefits for AWS CDK developers:

How the CDK CLI cdk refactor command works

First, you deploy your initial CDK application to establish baseline resources in your AWS account. After refactoring your CDK code, such as renaming constructs or moving resources between stacks, use the cdk refactor command to begin the process of refactoring your deployed resources.

When you run the refactor command, the CDK CLI detects your local changes by comparing your current code with the deployed state. It verifies that your CDK application contains exactly the same set of resources as the deployed state, differing only in their locations in the construct tree. The CDK CLI then generates a refactor plan that maps the old resource locations to their new locations. The CDK CLI shows you the proposed changes and, after your confirmation, uses AWS CloudFormation’s refactoring API to update the logical IDs of resources without replacing them.

Behind the scenes, the CDK CLI determines which resources have been moved by comparing their properties and dependencies, identifying resources that are functionally equivalent but have different paths in the construct tree. If it detects any resource additions, deletions, or modifications, the refactoring operation will be rejected with an error message.

Example of preserving resources when refactoring CDK code

In this example, we preserve deployed resources while refactoring our CDK code using the CDK CLI cdk refactor command.

Our example CDK application consists of a single stack containing an S3 bucket, a CloudFront distribution, and a Lambda function. The construct tree is structured as follows:

App
└─ MyStack
   ├─ Bucket
   ├─ Distribution
   └─ Function

The following is an example of our application code:

const app = new cdk.App();
const myStack = new cdk.Stack(app, 'MyStack');

const bucket = new s3.Bucket(myStack, 'Bucket');
const distribution = new cloudfront.Distribution(myStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

Now, imagine you want to refactor this code to:

After refactoring, the construct tree would look like this:

App
├─ WebStack
│  ├─ WebsiteOrigin
│  └─ Distribution
└─ MyStack
   └─ Function

And the refactored code would be:

// Refactored structure
const app = new cdk.App();

// New WebStack with the bucket and distribution
const webStack = new cdk.Stack(app, 'WebStack');
const bucket = new s3.Bucket(webStack, 'WebsiteOrigin');
const distribution = new cloudfront.Distribution(webStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});

// Original MyStack with just the function
const myStack = new cdk.Stack(app, 'MyStack');
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

Without CDK refactoring, these changes would cause AWS CloudFormation to create new resources and delete the old ones, because the logical IDs would change:

With CDK refactoring, the CDK CLI detects these path changes and uses AWS CloudFormation’s refactoring capabilities to preserve the underlying resources. When you run cdk refactor, the CLI shows you the changes it will make:

$ cdk refactor

The following resources were moved or renamed:

┌───────────────────────────────┬───────────────────────────────┬───────────────────────────────────┐
│ Resource Type                 │ Old Construct Path            │ New Construct Path                │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::S3::Bucket               │ MyStack/Bucket/Resource       │ WebStack/WebsiteOrigin/Resource   │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::CloudFront::Distribution │ MyStack/Distribution/Resource │ WebStack/Distribution/Resource    │
└───────────────────────────────┴───────────────────────────────┴───────────────────────────────────┘

Do you wish refactor these resources (y/n)?

When you confirm by entering y, the CDK CLI shows the progress of the refactoring operation:

Refactoring...
✅  Stack refactor complete

After confirming, the CDK CLI runs the refactoring operation, preserving both resources while updating their logical IDs to match your new code structure.

The same mapping is also shown in the output of the cdk diff command, organized by stack:

Stack MyStack
Resources
[-] AWS::S3::Bucket Bucket Bucket1234567 destroy (OR move to WebStack.WebsiteOrigin1234567 via refactoring)
[-] AWS::CloudFront::Distribution Distribution Distribution1234567 destroy (OR move to WebStack.Distribution1234567)
...

Stack WebStack
Resources
[+] AWS::S3::Bucket WebsiteOrigin WebsiteOrigin1234567 (OR move from MyStack.Bucket1234567)
[+] AWS::CloudFront::Distribution Distribution Distribution1234567 (OR move from MyStack.Distribution1234567)
...

Get started with CDK refactoring

To get started with refactoring, complete these prerequisites:

Use override files to resolve ambiguities in refactoring

The CDK CLI automatically computes all resource mappings based on comparing your code to the deployed resources. In most cases, this automatic detection works well, but there are situations where the CLI might encounter ambiguities it can’t resolve on its own. To provide guidance to the CDK CLI, use an override file.

Refactoring stacks across multiple environments

A CDK application can contain multiple stacks that deploy to different environments (AWS accounts and Regions). When preserving resources during refactoring in such applications, the CDK CLI handles environments in a specific way:

This behavior ensures that resources remain within their original AWS account and Region, which is necessary because CloudFormation resources cannot be physically moved across account or Region boundaries.

For example, if your CDK application defines stacks for both development and production environments, the refactoring operation will be performed independently in each environment. Resources can be moved between stacks within the development environment or within the production environment, but not from development to production or vice versa.

Handling resources designed to be replaced

Some CDK constructs rely on CloudFormation’s resource replacement behavior as part of their design. For example, API Gateway’s Deployment and Lambda’s Version constructs are designed to create new resources when their properties change.

When refactoring, do not include any changes that should result in resource replacements. Otherwise, the CDK CLI may detect and preserve these resources. This means that resources that are designed to be replaced must be handled separately from refactoring operations.

To properly manage resources designed to be replaced:

This two-step approach ensures that resources designed to be replaced are properly handled, while still allowing you to benefit from CDK refactoring for other resources.

General considerations and limitations

When preserving resources during CDK refactoring, keep these considerations in mind:

Refactoring with CI/CD pipelines

To use the refactoring feature in CI/CD pipelines, you need to be able to run the CDK CLI as part of your pipeline. The following are some important considerations for integrating refactoring into your CI/CD workflow.

Related resources

For information on options and arguments for the CDK CLI cdk refactor command, see cdk refactor .

To get started with the CDK Toolkit Library’s refactor action, see Perform programmatic actions using the CDK Toolkit Library.