Sometimes AWS resources are orphaned. This means the CloudFormation stack is destroyed but the resource is retained. This can happen either because the CloudFormation template specified this wish in the DeletionPolicy or after receiving an error from CloudFormation during the destruction and you decided to delete the stack anyway awknowledging that the resource in question will be retained.

It is entirely possible to work with the orphaned resource because you can always refer to it using its Arn. In CDK you use the from... static methods for doing that. But this will not give you back the control over the properties of the orphaned resource.

Orphaned resources become troublesome to deal with in practice though. One example is that, when the maturity level of you organisation rises, you get confronted with a new rule saying that all your S3 buckets should have certain security measures in place like enforcing SSL access or KMS encryption. Now if also click-ops (managing resources using the AWS console) is banished by your Security Officer, you need a way to regain control over the orphaned buckets via code.

CloudFormation has this feature for a while already, but for CDK project you have to use an experimental feature. Here are the steps you have to take to adopt an ophaned resource:

1. Decide which application / stack should become the new parent for your resource
2. Create the resource in that stack using CDK code (the exact properties do not matter for now)
3. Synth your project and lookup the logical id of the resource in the generated stack in CDK.OUT
4. Create mapping.json in which you link the logical id to the physical id of the existing resource
5. Run cdk import -m mapping.json
6. Lookup the stack in the console and perform a drift detection
7. Now adjust the code in you CDK project so the resource will match the drift
8. Run cdk deploy

It is very important to understand that when running step 5 nothing other than the resource addition may have changed in your stack! If more things changed you will get an error message.

You can also work without the mapping.json file, but the cdk import process becomes interactive then, making it unsuitable for in a CI/CD pipeline. The json file should look like this:

{
    "LogIdOfTheResourceYouLookedUp": {
        "BucketName": "my-existing-bucket-name"
    }
}

I only tested this with a bucket, the actual link to the physical id property might differ per resource type.

In a CI/CD pipeline automation you might choose do an cdk import step in stead of a cdk deploy whenever the mapping.json is around. Another thing to note is that this currently only works if you either have a project with one stack or you specify that stack you want to perform the cdk import with. I imagine you could create a stackname-mapping.json and have your pipeline perform the stack selecting.

Joris Conijn already wrote a nice article about migrating resources between CDK stacks without using the experimental feature here.

The experimental cdk feature is described here. The rfc is still open so you might be able to track or influence how it will stabilize.