How to import existing resources into AWS CDK Stacks

NOTE: The CDK team has recently added a feature that automates the manual process described in this post. I have included a walkthrough at the end of the post that demonstrates the automated workflow using the cdk import command.

Introduction

Many customers have provisioned resources through the AWS Management Console or different Infrastructure as Code (IaC) tools, and then started using AWS Cloud Development Kit (AWS CDK) in a later stage. After introducing AWS CDK into the architecture, you might want to import some of the existing resources to avoid losing data or impacting availability.

In this post, I will show you how to import existing AWS Resources into an AWS CDK Stack.

The AWS CDK is a framework for defining cloud infrastructure through code and provisioning it with AWS CloudFormation stacks. With the AWS CDK, developers can easily provision and manage cloud resources, define complex architectures, and automate infrastructure deployments, all while leveraging the full power of modern software development practices like version control, code reuse, and automated testing. AWS CDK accelerates cloud development using common programming languages such as TypeScript, JavaScript, Python, Java, C#/.Net, and Go.

AWS CDK stacks are a collection of AWS resources that can be programmatically created, updated, or deleted. CDK constructs are the building blocks of CDK applications, representing a blueprint to define cloud architectures.

Solution Overview

The AWS CDK Toolkit (the CLI command cdk), is the primary tool for interacting with your AWS CDK app. I will show you the commands that you will encounter when implementing this solution. When you create a CDK stack, you can deploy it using the cdk deploy command, which also synthesizes the application. The cdk synthesize (synth) command synthesizes and prints the CloudFormation template for one or more specified stacks.

To import existing AWS resources into a CDK stack, you need to create the CDK stack and add the resource you want to import, then generate a CloudFormation template representing this stack. Next, you need to import this resource into the CloudFormation stack using the AWS CloudFormation Console, by uploading the newly generated CloudFormation template. Finally, you need to deploy the CDK stack that includes your resource.

Walkthrough

The walkthrough consists of three main steps:

Step 1: Update the CDK stack with the resource you want to import

Step 2: Import the existing resource into the CloudFormation stack

Step 3: Import the existing resource into the CDK stack

Prerequisites

• aws-cdk v2 is installed on your system, in order to be able to use the AWS CDK CLI.
• A CDK stack deployed in your AWS Account.

You can skip the following and move to the Step 1 section if you already have an existing CDK stack that you want to import your resources into.

Let’s create a CDK stack into which you will import your existing resources. We need to specify at least 1 resource in order to create it. For this example, you will create a CDK stack with an Amazon Simple Storage Service (Amazon S3) bucket.

After you’ve successfully installed and configured AWS CDK:

1. Open your IDE and a new terminal window. Create a new folder hello-cdk by running these two commands:

   mkdir hello-cdk && cd hello-cdk
   cdk init app --language typescript
   

   The cdk init command creates a number of files and folders inside the hello-cdk directory to help you organize the source code for your AWS CDK app. Take a moment to explore. The structure of a basic app is all there; you’ll fill in the details when implementing this solution.

   At this point, your app doesn’t do anything because the stack it contains doesn’t define any resources. Let’s add an Amazon S3 bucket.

2. In lib/hello-cdk-stack.ts replace the code with the following code snippet:

   import * as cdk from 'aws-cdk-lib';
   import { aws_s3 as s3 } from 'aws-cdk-lib';
   
   export class HelloCdkStack extends cdk.Stack {
     constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
       super(scope, id, props);
   
       new s3.Bucket(this, 'MyExampleBucket');
     }
   }

   NOTE: Amazon S3 provides a number of security features to consider as you develop and implement your own security policies. I recommend you go through the security best practices for Amazon S3 for more details on how to enhance the security of your S3 Bucket.

3. Now, you can deploy the stack using the cdk deploy command.
   This command will first create a CloudFormation template in cdk.out/HelloCDKStack.template.json, and then deploy it in your AWS account.
4. Navigate to the AWS CloudFormation Console and see the stack being created. It might take some time depending on the number and type of resources.
5. After the stack gets created, you can explore the Resources tab for created resources

Step 1: Update the CDK stack with the resource you want to import

After you’ve created the stack, you need to update the CDK stack with the resources you would like to import. For this example, we will be importing an existing S3 bucket.

If you don’t have an existing S3 bucket that you want to import, you can create it using the S3 Console, AWS SDK or AWS CLI.

1. Go to your IDE and open the terminal. Open lib/hello-cdk-stack.ts file and add the following code snippet:

   new s3.Bucket(this, 'ImportBucket', {
   	removalPolicy: cdk.RemovalPolicy.RETAIN
   });
   

   Resources to import must have a DeletionPolicy attribute specified in the template. We will set the removalPolicy attribute to RETAIN to avoid resource deletion if you delete the CDK stack.

2. In the terminal, run cdk synth command to obtain our CloudFormation template. This command will synthesize the CloudFormation template, but it will not deploy it to your AWS account. The template will be saved in cdk.out/HelloCdkStack.template.json.

Step 2: Import the existing resource into CloudFormation stack

1. Open the CloudFormation Console, and choose your stack.
2. In the right-upper corner, choose Stack actions -> Import resources into stack.
3. On the Identify Resources page, choose Next.
4. On Specify template page, you will be asked to specify a new template that includes the resource you want to import. Choose Upload a template file and specify the template that was created by cdk synth command in cdk.out/HelloCdkStack.template.json. CloudFormation will now use that template which includes the resource you want to import.
5. Choose Next.
6. On the Identify resources page, you will be asked to identify the resources to import. For BucketName, choose the name of the S3 bucket you want to import.
7. Choose Next.
8. On the Specify stack details page, you will be asked to specify the stack parameters. For BootstrapVersion parameter, leave the default as it is.
9. Choose Next.
10. On the Review page, you will be able to see what changes have been made to the CloudFormation template, and which resources have been imported.
11. Review the changes and choose Import resources.
12. You can see in the Events tab that the bucket is being imported. Go to the Resources tab, and see the imported bucket.

Step 3: Import the existing resource into CDK stack

The last step is to import the existing resource into your CDK stack. Go back to the terminal and run cdk deploy. You will get the message that no changes have been found in the stack, this is because the CloudFormation template has been updated in the previous step.

Congratulations! You’ve just imported your resources into CDK stack and now you can continue deploying and managing your infrastructure with more flexibility and control.

Import existing resources using cdk import command

The cdk import command works just like cdk deploy but for newly added constructs in the stack. Instead of creating new AWS resources, it will import corresponding existing resources, which effectively automates the manual actions demonstrated in this post. The manual workflow can be used when you need more control over the steps of import operation, or when for some reason you can’t use the automated workflow (for example you want to import resources into a nested stack, which is not yet supported using cdk import).

Walkthrough

Step 1: Update the CDK stack with the resource you want to import

Step 2: Evaluate the current status

Step 3: Import the resources using cdk import command

Prerequisites

Please go to Prerequisites section at the beginning of the of the blog post.

Step 1: Update the CDK stack with the resource you want to import

After you’ve created the stack, you need to update the CDK stack with the resources you would like to import. For this example, we will be importing an existing S3 bucket.

If you don’t have an existing S3 bucket that you want to import, you can create it using the S3 Console, AWS SDK or AWS CLI.

Go to your IDE and open the terminal. Open lib/hello-cdk-stack.ts file and add the following code snippet:

new s3.Bucket(this, 'ImportBucket', {
     removalPolicy: cdk.RemovalPolicy.RETAIN
});

Resources to import must have a DeletionPolicy attribute specified in the template. We will set the removalPolicy attribute to RETAIN to avoid resource deletion if you delete the CDK stack.

You must also make sure to exactly model the state that the resource currently has. For the example of the Bucket, be sure to include KMS keys, life cycle policies, and anything else that’s relevant about the bucket. If you do not, subsequent update operations may not do what you expect.

Step 2: Evaluate the current status

Open the terminal and run cdk diff command to make sure there are no pending changes to the CDK stack you want to import resources into. The only changes allowed in an “import” operation are the addition of new resources which you want to import.

Step 3: Import the resources using cdk import command

1. Run the cdk import command – if there are multiple stacks in the CDK app, pass a specific stack name as an argument.
2. After running the command, you will be asked to provide the name of the bucket you want to import. After submitting you should see the below result.
3. Navigate to the AWS CloudFormation Console and choose your stack. You can see in the Events tab that the bucket has been imported.
4. Go to the Resources tab, and see the imported bucket.
   
   Congratulations! You’ve just imported your resources into CDK stack using the cdk import command.

Cleanup

Destroy the AWS CDK stack and Buckets

1. When you’re done with the resources you created, you can destroy your CDK stack by running the following commands in your terminal:

   cd ~/hello-cdk
   cdk destroy HelloCdkStack

2. When asked to confirm the deletion of the stack, enter yes.

NOTE: The S3 buckets you’ve imported won’t get deleted because of the removal policy. If no longer needed, delete the S3 bucket/s.

Conclusion

In this post, I showed you a solution to import existing AWS resources into CDK stacks. As the demand for IaC and DevOps solutions continues to grow, an increasing number of customers are turning to AWS CDK as their preferred IaC solution due to its powerful capabilities and ease of use as you can write infrastructure code using familiar programming languages.

AWS is continuously improving CDK by adding new features and capabilities, in collaboration with the open source community. Here you can find a repository to propose and track major upcoming changes to AWS CDK, jsii, and other related projects. It also is a great place to learn about the current and future state of the libraries and to discover projects for contribution. Keep an eye on that repository and provide any feedback you have to the team.