cdk orphan - AWS Cloud Development Kit (AWS CDK) v2
UsageArgumentsOptionsExamples
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

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.

cdk orphan

Important

The cdk orphan command is in preview release and is subject to change.

You must provide the --unstable=orphan option when using this command.

Safely detach one or more resources from an AWS CloudFormation stack without deleting them. This is useful when you need to migrate a resource from one construct type to another (for example, migrating a DynamoDB Table to TableV2) without downtime or data loss.

When you change a construct type in your CDK code, CloudFormation interprets this as a resource replacement, which deletes the existing resource and creates a new one. For stateful resources like databases and storage, this causes data loss. The cdk orphan command solves this by detaching the resource from the stack first, so you can re-import it under the new construct type using cdk import.

With cdk orphan, you can:

  • Detach stateful resources from a stack before changing their construct type.

  • Migrate between construct versions (for example, DynamoDB Table to TableV2) without data loss.

  • Change the CloudFormation resource type backing a construct without replacing the physical resource.

The orphan command performs three CloudFormation deployments:

  1. Resolve references: Resolves cross-resource references (Ref, Fn::GetAtt, Fn::Sub) to the orphaned resources, so that other resources in the stack that depend on them continue to work after the orphaned resources are removed.

  2. Decouple: Replaces all cross-resource references with their resolved literal values, sets DeletionPolicy to Retain, and removes DependsOn entries to isolate the resources from the rest of the stack.

  3. Remove: Removes the resources from the CloudFormation template. The physical resources continue to exist in your AWS account.

After orphaning, update your CDK code to use the new construct type and use cdk import to bring the resource back under management.

To orphan a resource and re-import it under a new construct type

  1. Deploy your stack and verify the resource exists.

  2. Run cdk orphan with the construct path of the resource:

    $ cdk orphan MyStack/MyTable --unstable=orphan

  3. The command outputs a resource mapping. Save this for the import step.

  4. Update your CDK code to use the new construct type (for example, change Table to TableV2).

  5. Run cdk import with the resource mapping from the orphan output:

    $ cdk import MyStack --resource-mapping-inline '{"MyTable":{"TableName":"my-table"}}'

  6. After the import completes, cdk import detects drift and prompts you to deploy. Accept the prompt to reconcile the stack.

This feature currently has the following limitations:

  • All construct paths must reference the same stack. Orphaning resources across multiple stacks in a single command is not supported.

  • Wildcard patterns are not supported. Paths are matched as exact prefixes.

  • This command requires version 32 of the bootstrap template, which includes the necessary IAM permissions for the deploy role.

Usage

$ cdk orphan <PATHS> <options>

Arguments

PATHS

One or more construct paths to orphan, in the format StackName/ConstructPath. For example, MyStack/MyTable. Multiple paths can be provided to orphan several resources in a single command.

All paths must reference the same stack.

Type: String

Required: Yes

Options

For a list of global options that work with all CDK CLI commands, see Global options.

--help, -h <BOOLEAN>

Show command reference information for the cdk orphan command.

Examples

Orphan a single resource

$ cdk orphan MyStack/MyTable --unstable=orphan

Orphan multiple resources

$ cdk orphan MyStack/MyTable MyStack/MyBucket --unstable=orphan

Skip confirmation prompt

$ cdk orphan MyStack/MyTable --unstable=orphan --yes