feat(cli): add `cdk orphan` command to detach resources from a stack by rix0rrr · Pull Request #1324 · aws/aws-cdk-cli

rix0rrr · 2026-04-09T08:13:24Z

Adds a new CLI command that safely removes resources from a CloudFormation stack without deleting them, enabling resource type migrations (e.g. DynamoDB Table to GlobalTable).

cdk orphan --path <ConstructPath> will:

Find all resources under the construct path via aws:cdk:path metadata
Resolve {Ref} values via DescribeStackResources
Resolve {Fn::GetAtt} values by injecting temporary stack Outputs
Set DeletionPolicy: Retain on all matched resources
Remove the resources from the stack
Output an inline cdk import command with the resource mapping

Also adds inline JSON support for --resource-mapping in cdk import, and exposes stackSdk() on Deployments for read-only SDK access.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

rix0rrr · 2026-04-09T08:14:03Z

This is actually @LeeroyHannigan's change, I'm just turning it into a PR so I can leave comments more conveniently.

rix0rrr

Great start!

Initial round of comments on this.

This also needs an integ test (and to be frank probably more than 1 😉 ).

codecov-commenter · 2026-04-09T19:11:17Z

Codecov Report

❌ Patch coverage is 71.42857% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.14%. Comparing base (b96bcce) to head (f576cc1).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
packages/aws-cdk/lib/cli/cli.ts	7.14%	13 Missing ⚠️
packages/aws-cdk/lib/cli/cdk-toolkit.ts	79.41%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1324      +/-   ##
==========================================
- Coverage   88.29%   88.14%   -0.15%     
==========================================
  Files          73       74       +1     
  Lines       10386    10494     +108     
  Branches     1413     1428      +15     
==========================================
+ Hits         9170     9250      +80     
- Misses       1189     1216      +27     
- Partials       27       28       +1

Flag	Coverage Δ
suite.unit	`88.14% <71.42%> (-0.15%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

rix0rrr · 2026-04-13T09:52:07Z

+        // Only include the primary resource for each construct path
+        // e.g. for path "MyTable", match "StackName/MyTable/Resource" exactly
+        const cdkPath = resource.Metadata?.[PATH_METADATA_KEY] ?? '';
+        const primaryPaths = constructPaths.map(p => `${stack.stackName}/${p}/Resource`);
+        if (!primaryPaths.includes(cdkPath)) continue;


This smells to me. I can't be bothered to try to understand what this is doing exactly, but it doesn't feel right.

Why the interpolation with stackName? Why only exactly this L1 reosurce? Why includes(cdkPath) instead of startsWith(cdkPath)?

What are we trying to do here?

Removed the path filter entirely. Will need to discuss.

rix0rrr · 2026-04-14T07:37:37Z

                  # `cdk import`
                  - cloudformation:GetTemplateSummary
+                  # `cdk orphan`
+                  - cloudformation:ListStackResources


This needs an update to the bootstrap stack version as well (in 2 places)

Done, thanks

I changed my mind. Can we change this to:

- cloudformation:List* - cloudformation:Describe*

I'm tired of having to add every new read-only permissions one by one :(

rix0rrr · 2026-04-20T12:15:38Z

                  # `cdk import`
                  - cloudformation:GetTemplateSummary
+                  # `cdk orphan`
+                  - cloudformation:ListStackResources


I changed my mind. Can we change this to:

- cloudformation:List* - cloudformation:Describe*

I'm tired of having to add every new read-only permissions one by one :(

rix0rrr · 2026-04-20T12:24:29Z

+
+    // Step 1/3: Resolve GetAtt attribute values via temporary stack outputs
+    await this.ioHelper.defaults.info('Step 1/3: Resolving attribute values...');
+    const resolvedValues = await this.resolveGetAttValues(stack, cfn, logicalIds, currentTemplate, physicalIds);


I just realized there's something missing.

A {Fn::Sub} has implicit interpolation inside its format string. It can look like this:

{ "Fn::Sub": "before ${ImplicitRef} ${ImplicitAtt.AttrName} after" } { "Fn::Sub": [ "before ${ImplicitRef} ${ImplicitAtt.AttrName} or ${Explicit} after", { "Explicit": { "Fn::GetAtt": ["Resource", "Attr"] } } }

For the final case we don't have to do anything (Resource.Attr) because (I assume) it would already be found. But the 2 strings can contain implicit references:

${ImplicitRef} inside format string - resolves the same as { "Ref": "ImplicitRef" } would.

${ImplicitAtt.AttrName} inside format string - resolves the same as { "Fn::GetAtt": ["ImplicitAtt", "AttrName"] } would.

We need to discover these references in the discovery stage, and replace them in the replacement stage (be sure to add tests).

Note: the format string can occur in 2 forms, either inside an array or as a direct argument.

Be sure to add tests on these.

rix0rrr · 2026-04-20T12:32:42Z

+⚠️**CAUTION**⚠️: CDK Orphan is currently experimental and may have 
+breaking changes in the future. Make sure to use the `--unstable=orphan` flag 
+when using this command.


Let's make this sound less scary.

Suggested change

⚠️**CAUTION**⚠️: CDK Orphan is currently experimental and may have

breaking changes in the future. Make sure to use the `--unstable=orphan` flag

when using this command.

> `cdk orphan` is currently experimental, meaning we reserve the right to change

> options and flag names in the future. Pass the `--unstable=orphan` flag when using

> this command and be aware of this when using it in scripts.

Adds a new CLI command that safely removes resources from a CloudFormation stack without deleting them, enabling resource type migrations (e.g. DynamoDB Table to GlobalTable). `cdk orphan --path <ConstructPath>` will: - Find all resources under the construct path via aws:cdk:path metadata - Resolve {Ref} values via DescribeStackResources - Resolve {Fn::GetAtt} values by injecting temporary stack Outputs - Set DeletionPolicy: Retain on all matched resources - Remove the resources from the stack - Output an inline `cdk import` command with the resource mapping Also adds inline JSON support for `--resource-mapping` in `cdk import`, and exposes `stackSdk()` on Deployments for read-only SDK access.

…sion

…step

…List*/Describe*

rix0rrr temporarily deployed to automation April 9, 2026 08:13 — with GitHub Actions Inactive

rix0rrr requested a deployment to integ-approval April 9, 2026 08:13 — with GitHub Actions Waiting

aws-cdk-automation enabled auto-merge April 9, 2026 08:13

github-actions Bot added the p2 label Apr 9, 2026

aws-cdk-automation requested a review from a team April 9, 2026 08:14

rix0rrr commented Apr 9, 2026

View reviewed changes

mrgrain requested changes Apr 9, 2026

View reviewed changes

Comment thread packages/aws-cdk/lib/cli/cdk-toolkit.ts

auto-merge was automatically disabled April 9, 2026 17:48
Head branch was pushed to by a user without write access

LeeroyHannigan requested a deployment to integ-approval April 9, 2026 17:48 — with GitHub Actions Waiting

LeeroyHannigan requested a deployment to integ-approval April 9, 2026 17:59 — with GitHub Actions Waiting

LeeroyHannigan force-pushed the lhnng-orphan-resource branch from 82e0371 to 8ad5411 Compare April 9, 2026 18:12

LeeroyHannigan requested a deployment to integ-approval April 9, 2026 18:13 — with GitHub Actions Waiting

LeeroyHannigan requested a deployment to integ-approval April 9, 2026 18:29 — with GitHub Actions Waiting

LeeroyHannigan requested a deployment to integ-approval April 9, 2026 18:55 — with GitHub Actions Waiting

LeeroyHannigan requested a deployment to integ-approval April 9, 2026 19:20 — with GitHub Actions Waiting

rix0rrr commented Apr 13, 2026

View reviewed changes

mrgrain reviewed Apr 13, 2026

View reviewed changes

Comment thread packages/aws-cdk/lib/cli/cdk-toolkit.ts Outdated

LeeroyHannigan requested a deployment to integ-approval April 13, 2026 16:27 — with GitHub Actions Waiting

LeeroyHannigan force-pushed the lhnng-orphan-resource branch from 1036138 to 211b87e Compare April 13, 2026 19:18

LeeroyHannigan requested a deployment to integ-approval April 13, 2026 19:18 — with GitHub Actions Waiting

LeeroyHannigan requested a deployment to integ-approval April 13, 2026 19:54 — with GitHub Actions Waiting

LeeroyHannigan force-pushed the lhnng-orphan-resource branch from deea40c to 06a93bd Compare April 13, 2026 20:38

LeeroyHannigan requested a deployment to integ-approval April 13, 2026 20:39 — with GitHub Actions Waiting

LeeroyHannigan force-pushed the lhnng-orphan-resource branch from 06a93bd to 616d59a Compare April 13, 2026 21:52

LeeroyHannigan requested a deployment to integ-approval April 13, 2026 21:52 — with GitHub Actions Waiting

rix0rrr commented Apr 14, 2026

View reviewed changes

LeeroyHannigan requested a deployment to integ-approval April 14, 2026 10:01 — with GitHub Actions Waiting

LeeroyHannigan requested a deployment to integ-approval April 14, 2026 18:45 — with GitHub Actions Waiting

rix0rrr commented Apr 20, 2026

View reviewed changes

LeeroyHannigan requested a deployment to integ-approval April 20, 2026 14:10 — with GitHub Actions Waiting

Lee Hannigan added 10 commits April 20, 2026 15:14

feat(cli): address PR feedback for cdk orphan command

c922182

refactor: use PATH_METADATA_KEY constant instead of string literal

d6b06fb

fix: use ToolkitError instead of Error, fix line length lint

13ef11e

fix: add orphan to cli-arguments test expectations

0a24385

fix: apply auto-formatting to cli-config.ts

ff4e967

refactor: address round 2 PR feedback

35da17a

fix: regenerate yarn.lock with Yarn 4

3acbea7

fix: bump bootstrap stack version to 32 for ListStackResources permis…

6093f68

…sion

docs: add cdk orphan section to README and remove post-orphan deploy …

aadaba7

…step

LeeroyHannigan force-pushed the lhnng-orphan-resource branch from e16472f to 921758f Compare April 20, 2026 14:19

LeeroyHannigan requested a deployment to integ-approval April 20, 2026 14:19 — with GitHub Actions Waiting

LeeroyHannigan force-pushed the lhnng-orphan-resource branch from 921758f to e6313a9 Compare April 20, 2026 14:28

LeeroyHannigan requested a deployment to integ-approval April 20, 2026 14:28 — with GitHub Actions Waiting

LeeroyHannigan force-pushed the lhnng-orphan-resource branch from e6313a9 to a5397aa Compare April 20, 2026 16:37

LeeroyHannigan requested a deployment to integ-approval April 20, 2026 16:37 — with GitHub Actions Waiting

feat: handle Fn::Sub implicit refs, broaden bootstrap permissions to …

1909dd4

…List*/Describe*

LeeroyHannigan force-pushed the lhnng-orphan-resource branch from a5397aa to 1909dd4 Compare April 20, 2026 16:47

LeeroyHannigan requested a deployment to integ-approval April 20, 2026 16:47 — with GitHub Actions Waiting

LeeroyHannigan mentioned this pull request Apr 20, 2026

feat(cli): cdk orphan command detaches resources from a stack, allowing resource type upgrades (behind --unstable) #1399

Merged

rix0rrr closed this Apr 21, 2026

Conversation

rix0rrr commented Apr 9, 2026

Uh oh!

rix0rrr commented Apr 9, 2026

Uh oh!

rix0rrr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rix0rrr Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

LeeroyHannigan Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rix0rrr Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

LeeroyHannigan Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

rix0rrr Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

rix0rrr Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

rix0rrr Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rix0rrr Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov-commenter commented Apr 9, 2026 •

edited

Loading

rix0rrr Apr 20, 2026 •

edited

Loading