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 😉 ).

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

+   * Get the CloudFormation SDK client for a stack's environment.
+   * Used by the orphaner to call DescribeStackResources.
+   */
+  public async stackSdk(stackArtifact: cxapi.CloudFormationStackArtifact) {


Do we need this method? We probably should just inline this at the call site.

Done. Removed stackSdk() from Deployments. The orphaner accesses the SDK via deployments.envs.accessStackForReadOnlyStackOperations(stack) directly.

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

   */
-  public async loadResourceIdentifiers(available: ImportableResource[], filename: string): Promise<ImportMap> {
-    const contents = await fs.readJson(filename);
+  public async loadResourceIdentifiers(available: ImportableResource[], filenameOrJson: string): Promise<ImportMap> {


Not a fan of implicitly overloading an argument like this. I'd rather be explicit, like this:

type ResourceIdentifiersSource = | { type: 'file'; fileName: string } | { type: 'direct'; resourceIdentifiers: Record<string, ResourceIdentifierProperties> }; public async loadResourceIdentifiers(available: ImportableResource[], source: ResourceIdentifiersSource): Promise<ImportMap> {

Or honestly, even simpler

public async loadResourceIdentifiersFromFile(available: ImportableResource[], fileName: string): Promise<ImportMap> { const contents = /* load file */; return this.loadResourceIdentifiers(available, contents); } public async loadResourceIdentifiers(available: ImportableResource[], identifiers: Record<string, ResourceIdentifierProperties>): Promise<ImportMap> {

Done. Split into loadResourceIdentifiersFromFile(available, fileName) which loads the file and calls loadResourceIdentifiers(available, identifiers). The CLI layer decides which to call. Also added --resource-mapping-inline as a separate CLI option for passing JSON directly (used by cdk orphan output).

rix0rrr · 2026-04-09T08:15:01Z

  }

+  public async orphan(options: OrphanOptions) {
+    const stacks = await this.selectStacksForDeploy(options.selector, true, true, false);


If the argument is one or more construct paths (which it should be) then the stack selection is implicit. No need for the user to pick the stack.

rix0rrr · 2026-04-09T08:15:30Z

+    }
+
+    const stack = stacks.stackArtifacts[0];
+    await this.ioHost.asIoHelper().defaults.info(chalk.bold(`Orphaning construct '${options.constructPath}' from ${stack.displayName}`));


We should split this into "plan" and "execute" stages:

First determine actually which constructs are going to be orphaned, by evaluating the construct path. And include what resources are going to have their references replaced with literals. It should probably be an error if there are 0. Then we print a proper report of what we're going to do to the user (not a guess at the result of their instruction). We should probably give them a chance to confirm as well.

Only after they confirm do we do the actual work.

I would like to see that in the API in some way. For example:

class Orphaner { constructor(...) { } public async makePlan(...): Promise<OrphanPlan> { // ... } } class OrphanPlan { // The properties below here are purely hypothetical to show the idea! I have not done enough // mental design to think about whether these are the best to expose. public readonly orphanedResoures: OrpanPlanResource[]; public readonly affectedResources: OrpanPlanResource[]; public readonly stacks: OrphanPlanStack[]; public async execute() { // ... } } class Toolkit { public async orphan(...) { // And then something like this const orphaner = new Orphaner(...): const plan = await orphaner.makePlan(...); await showPlanToUser(plan, this.ioHost); const yes = await this.ioHost.confirm(...); if (yes) { await plan.execute(); } } }

Done. Implemented exactly as described:

makePlan(stack, constructPaths) → returns OrphanPlan with stackName, orphanedResources (each with logicalId, resourceType, cdkPath), and an execute() method. Read-only, no deployments.

Toolkit.orphan() shows the plan, then confirms via requestResponse (skippable with --force).

plan.execute() runs the 3 CloudFormation deployments, returns OrphanResult with resourceMapping.

rix0rrr · 2026-04-09T08:15:37Z

+      roleArn: options.roleArn,
+      toolkitStackName: this.toolkitStackName,


Feels like both of these should be constructor arguments.

Done. roleArn and toolkitStackName are on ResourceOrphanerProps (the constructor), not on the orphan() method options.

rix0rrr · 2026-04-09T08:51:26Z

+    const cfn = sdk.cloudFormation();
+
+    // Get physical resource IDs (Ref values) from CloudFormation
+    const describeResult = await cfn.describeStackResources({ StackName: stack.stackName });


Is this paginated?

nice catch, its not (truncates at 100). I used listStackResources which is paginated, instead. This meant I needed permissions on the CLI role, to run integ tests. LMK if thats not correct.

rix0rrr · 2026-04-09T08:52:28Z

+    }
+  }
+
+  private replaceInObject(obj: any, logicalId: string, values: { ref: string; attrs: Record<string, string> }): any {


Doesn't use this so doesn't need to be a method. Could be a helper function.

And in fact should be since it operates on a CFN template.

Done, walkObject, replaceInObject, replaceReferences, removeDependsOn, findResourcesByPath, findBlockingResources, hasAnyCdkPathMetadata, and assertSafeDeployResult are all standalone functions in actions/orphan/private/helpers.ts. None of them are methods on the class.

Kept them scoped to orphan for now since no other code needs them yet, happy to move to a shared location if you'd prefer, or as a follow-up when other commands need similar utilities.

rix0rrr · 2026-04-09T08:52:42Z

+    return result;
+  }
+
+  private removeDependsOn(template: any, logicalId: string): void {


Doesn't use this so doesn't need to be a method. Could be a helper function.

And in fact should be since it operates on a CFN template.

Done, walkObject, replaceInObject, replaceReferences, removeDependsOn, findResourcesByPath, findBlockingResources, hasAnyCdkPathMetadata, and assertSafeDeployResult are all standalone functions in actions/orphan/private/helpers.ts. None of them are methods on the class.

rix0rrr · 2026-04-09T08:52:45Z

+    }
+  }
+
+  private walkObject(obj: any, visitor: (value: any) => void): void {


Doesn't use this so doesn't need to be a method. Could be a helper function.

And in fact should be since it operates on a CFN template.

Done, walkObject, replaceInObject, replaceReferences, removeDependsOn, findResourcesByPath, findBlockingResources, hasAnyCdkPathMetadata, and assertSafeDeployResult are all standalone functions in actions/orphan/private/helpers.ts. None of them are methods on the class.

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:24:13Z

+    // Put an item in the table before orphan
+    const itemFile = path.join(fixture.integTestDir, 'test-item.json');
+    await fs.writeFile(itemFile, JSON.stringify({ PK: { S: 'before-orphan' } }));
+    await fixture.shell([


We are in a programming language, and we have an AWS SDK available to us (or we could without a lot of effort). I would prefer us using @aws-sdk/client-dynamodb directly.

Wasn't sure how to easily import the SDK, but its done now, thanks.

rix0rrr · 2026-04-13T09:26:58Z

+      new GetTemplateCommand({ StackName: stackName }),
+    );
+    const templateBody = yaml.parse(templateAfter.TemplateBody!);
+    expect(templateBody.Resources).not.toHaveProperty('MyTable794EDED1');


This would also silently succeed if the logical ID changed, for some reason. We should also check that the expected resource is present before we start orphaning.

Added expect(templateBodyBefore.Resources).toHaveProperty('MyTable794EDED1') before orphan

rix0rrr · 2026-04-13T09:29:50Z

+
+    // Verify the Lambda still exists and its env vars have been replaced with literals
+    // (Ref -> physical table name, GetAtt -> physical ARN)
+    const lambdaResource = Object.values(templateBody.Resources).find(


This is very hard to read, and if any of these steps fail the output will not be helpful to diagnose what the problem is.

I'd rather use a single structural assertion like:

expect(templateBody).toMatchObject({ Resources: { MyFunction1234: { Properties: { ... } } } });

etc.

Single toMatchObject with expect.objectContaining and expect.stringContaining

rix0rrr · 2026-04-13T09:30:28Z

+      '--region', fixture.aws.region,
+      '--output', 'json',
+    ]);
+    expect(getItemOutput).toContain('before-orphan');


We need to clean up that table otherwise it will leak.

Stick it in a try/finally, I really don't want to leak it even if the test fails.

Test body in try, DeleteTableCommand in finally

rix0rrr · 2026-04-13T09:31:23Z

+   * Construct path prefix(es) to orphan. Each path must be in the format
+   * `StackName/ConstructPath`, e.g. `MyStack/MyTable`.
+   *
+   * The stack is derived from the path — all paths must reference the same stack.


Ah yeah? 😅

Bummer. But acceptable for now I guess.

rix0rrr · 2026-04-13T09:49:09Z

+
+    for (const output of stackDesc.Stacks?.[0]?.Outputs ?? []) {
+      if (!output.OutputKey || !output.OutputValue) continue;
+      const ref = getAttRefs.find(r => r.outputKey === output.OutputKey);


If getAttRefs was a map or an object, we wouldn't need to search a list here.

Doubly-indexing maps is a bit brain breaking but perfectly legit and more concise.

Converted to map lookup

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-13T09:53:05Z

+    } catch {
+      await this.ioHelper.defaults.debug('Could not retrieve resource identifier summaries');


Wait what?

There was an exception, we're not stopping, we're not even logging the except, we're just chugging along as if nothing happened? And whispering that "something might be off" at debug level?

Now warn with the actual error message instead of debug with a generic string. Added unit test.

rix0rrr · 2026-04-13T09:58:15Z

+    const thisStack = p.substring(0, slashIdx);
+    const constructPath = p.substring(slashIdx + 1);


Unfortunately a construct ID !== a stack name.

"Construct ID" is a CDK concept, "Stack Name" is a CloudFormation concept.

Yes, by default the stack name of a Stack is the same as its Construct ID, but not necessarily.

new Stack(this, 'A', { // <-- construct ID, in the path stackName: 'B' // <-- Stack Name in CFN });

The translation of construct path to stack name needs to go through the assembly. To be frank, I don't know the best way offhand (it should probably be somewhere in the manifest), but perhaps the magic black box can come up with an idea.

Done, now matches stack.hierarchicalId instead of using the path segment as a CloudFormation stack name pattern

rix0rrr · 2026-04-13T09:59:20Z

+      await this.ioHost.asIoHelper().defaults.error((e as Error).message);
+      throw e;


Logging and rethrowing is usually an antipattern, leading to duplicated error messages in the output. Is this what we do in other places?

I was following the refactor implementation here:

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

Line 1356 in b96bcce

} catch (e) {

But I'll remove the try catch

mrgrain · 2026-04-13T11:43:38Z

+    try {
+      await this.toolkit.orphan(this.props.cloudExecutable, {
+        constructPaths: options.constructPath,
+        roleArn: options.roleArn,
+        toolkitStackName: options.toolkitStackName,
+        force: options.force,
+      });
+    } catch (e) {
+      await this.ioHost.asIoHelper().defaults.error((e as Error).message);
+      throw e;
+    }


Suggested change

try {

await this.toolkit.orphan(this.props.cloudExecutable, {

constructPaths: options.constructPath,

roleArn: options.roleArn,

toolkitStackName: options.toolkitStackName,

force: options.force,

});

} catch (e) {

await this.ioHost.asIoHelper().defaults.error((e as Error).message);

throw e;

}

await this.toolkit.orphan(this.props.cloudExecutable, {

constructPaths: options.constructPath,

roleArn: options.roleArn,

toolkitStackName: options.toolkitStackName,

force: options.force,

});

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.

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

…sion

…step

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

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

Lee Hannigan added 7 commits April 13, 2026 19:30

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

e4ef113

refactor: use PATH_METADATA_KEY constant instead of string literal

571dbbc

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

e37d0dd

fix: add orphan to cli-arguments test expectations

c331a7c

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

f108a2e

refactor: address round 2 PR feedback

211b87e

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

fix: regenerate yarn.lock with Yarn 4

616d59a

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

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

f576cc1

…sion

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

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

f1cbce0

…step

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

		roleArn: options.roleArn,
		toolkitStackName: this.toolkitStackName,

		} catch {
		await this.ioHelper.defaults.debug('Could not retrieve resource identifier summaries');

		const thisStack = p.substring(0, slashIdx);
		const constructPath = p.substring(slashIdx + 1);

		await this.ioHost.asIoHelper().defaults.error((e as Error).message);
		throw e;

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LeeroyHannigan Apr 9, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LeeroyHannigan Apr 9, 2026 •

edited

Loading

codecov-commenter commented Apr 9, 2026 •

edited

Loading