feat: add ignore-stacks and skip-unauthorized-stacks options to gc command

Author: gandhya

packages/@aws-cdk/toolkit-lib/lib/api/garbage-collection/garbage-collector.ts

@@ -178,6 +178,18 @@ interface GarbageCollectorProps {
    * @default true
    */
   readonly confirm?: boolean;
+
+  /**
+   *
+   * @default []
+   */
+  readonly ignoreStacks?: string[];
+
+  /**
+   *
+   * @default false
+   */
+  readonly skipUnauthorizedStacks?: boolean;
 }
 
 /**
@@ -219,7 +231,7 @@ export class GarbageCollector {
     const activeAssets = new ActiveAssetCache();
 
     // Grab stack templates first
-    await refreshStacks(cfn, this.ioHelper, activeAssets, qualifier);
+    await refreshStacks(cfn, this.ioHelper, activeAssets, qualifier, this.props.ignoreStacks, this.props.skipUnauthorizedStacks);
     // Start the background refresh
     const backgroundStackRefresh = new BackgroundStackRefresh({
       cfn,

packages/@aws-cdk/toolkit-lib/lib/api/garbage-collection/stack-refresh.ts

@@ -1,4 +1,5 @@
 import type { ParameterDeclaration } from '@aws-sdk/client-cloudformation';
+import { minimatch } from 'minimatch';
 import { ToolkitError } from '../../toolkit/toolkit-error';
 import type { ICloudFormationClient } from '../aws-auth/private';
 import type { IoHelper } from '../io/private';
@@ -36,7 +37,13 @@ async function paginateSdkCall(cb: (nextToken?: string) => Promise<string | unde
  * - stacks in DELETE_COMPLETE or DELETE_IN_PROGRESS stage
  * - stacks that are using a different bootstrap qualifier
  */
-async function fetchAllStackTemplates(cfn: ICloudFormationClient, ioHelper: IoHelper, qualifier?: string) {
+async function fetchAllStackTemplates(
+  cfn: ICloudFormationClient,
+  ioHelper: IoHelper,
+  qualifier?: string,
+  ignoreStacks?: string[],
+  skipUnauthorizedStacks?: boolean,
+) {
   const stackNames: string[] = [];
   await paginateSdkCall(async (nextToken) => {
     const stacks = await cfn.listStacks({ NextToken: nextToken });
@@ -56,25 +63,41 @@ async function fetchAllStackTemplates(cfn: ICloudFormationClient, ioHelper: IoHe
 
   const templates: string[] = [];
   for (const stack of stackNames) {
-    let summary;
-    summary = await cfn.getTemplateSummary({
-      StackName: stack,
-    });
-
-    if (bootstrapFilter(summary.Parameters, qualifier)) {
-      // This stack is definitely bootstrapped to a different qualifier so we can safely ignore it
-      continue;
-    } else {
-      const template = await cfn.getTemplate({
+    // Skip stacks matching user-inputted ignore patterns
+    if (ignoreStacks && ignoreStacks.length>0) {
+      const shouldSkip = ignoreStacks.some(pattern => minimatch(stack, pattern));
+      if (shouldSkip) {
+        await ioHelper.defaults.debug(`Skipping stack ${stack}`);
+        continue;
+      }
+    }
+    try {
+      let summary;
+      summary = await cfn.getTemplateSummary({
         StackName: stack,
       });
 
-      templates.push((template.TemplateBody ?? '') + JSON.stringify(summary?.Parameters));
+      if (bootstrapFilter(summary.Parameters, qualifier)) {
+        // This stack is definitely bootstrapped to a different qualifier so we can safely ignore it
+        continue;
+      } else {
+        const template = await cfn.getTemplate({
+          StackName: stack,
+        });
+
+        templates.push((template.TemplateBody ?? '') + JSON.stringify(summary?.Parameters));
+      }
+    } catch (error: any) {
+      // Skip stacks with access denied errors whenever the flag is enabled
+      if ((error.name == 'AccessDenied') && skipUnauthorizedStacks) {
+        await ioHelper.defaults.warn(`Skipping unauthorized stack: ${stack}`);
+        continue;
+      }
+      // To account for non-access related errors
+      throw error;
     }
   }
-
   await ioHelper.defaults.debug('Done parsing through stacks');
-
   return templates;
 }
 
@@ -97,9 +120,16 @@ function bootstrapFilter(parameters?: ParameterDeclaration[], qualifier?: string
           splitBootstrapVersion[2] != qualifier);
 }
 
-export async function refreshStacks(cfn: ICloudFormationClient, ioHelper: IoHelper, activeAssets: ActiveAssetCache, qualifier?: string) {
+export async function refreshStacks(
+  cfn: ICloudFormationClient,
+  ioHelper: IoHelper,
+  activeAssets: ActiveAssetCache,
+  qualifier?: string,
+  ignoreStacks?: string[],
+  skipUnauthorizedStacks?: boolean,
+) {
   try {
-    const stacks = await fetchAllStackTemplates(cfn, ioHelper, qualifier);
+    const stacks = await fetchAllStackTemplates(cfn, ioHelper, qualifier, ignoreStacks, skipUnauthorizedStacks);
     for (const stack of stacks) {
       activeAssets.rememberStack(stack);
     }

packages/@aws-cdk/toolkit-lib/test/api/garbage-collection/garbage-collection.test.ts

@@ -27,6 +27,7 @@ import {
   BackgroundStackRefresh,
   ProgressPrinter,
 } from '../../../lib/api/garbage-collection';
+import { refreshStacks } from '../../../lib/api/garbage-collection/stack-refresh';
 import { mockBootstrapStack, mockCloudFormationClient, mockECRClient, mockS3Client, MockSdk, MockSdkProvider } from '../../_helpers/mock-sdk';
 import { TestIoHost } from '../../_helpers/test-io-host';
 
@@ -1048,3 +1049,50 @@ function yearsInTheFuture(years: number): Date {
   d.setFullYear(d.getFullYear() + years);
   return d;
 }
+
+describe('Skip & Ignore Stacks', () => {
+  const mockIoHelper = { defaults: { debug: jest.fn(), warn: jest.fn() } };
+  test('skips stacks matching ignore patterns by the user', async () => {
+    // One stack matches the ignore pattern and one does not
+    const mockCfn = {
+      listStacks: jest.fn().mockResolvedValue({
+        StackSummaries: [
+          { StackName: 'StackSet-DGApp-123', StackStatus: 'CREATE_COMPLETE', CreationTime: new Date() }, // Will be filtered out
+          { StackName: 'DGAppStack2', StackStatus: 'CREATE_COMPLETE', CreationTime: new Date() }, // Will be processed
+        ],
+      }),
+      getTemplateSummary: jest.fn().mockResolvedValue({ Parameters: [] }),
+      getTemplate: jest.fn().mockResolvedValue({ TemplateBody: '{}' }),
+    };
+
+    const mockActiveAssets = { rememberStack: jest.fn() };
+
+    // Apply ignore pattern 'StackSet-*'
+    await refreshStacks(mockCfn as any, mockIoHelper as any, mockActiveAssets as any, undefined, ['StackSet-*']);
+
+    // Make sure only the non-matched stack is processed
+    expect(mockCfn.getTemplateSummary).toHaveBeenCalledTimes(1);
+    expect(mockCfn.getTemplateSummary).toHaveBeenCalledWith({ StackName: 'DGAppStack2' });
+  });
+
+  test('skips unauthorized stacks when the flag is true', async () => {
+    // Mock stack which throws an AccessDenied error
+    const mockCfn = {
+      listStacks: jest.fn().mockResolvedValue({
+        StackSummaries: [
+          { StackName: 'UnauthorizedStack', StackStatus: 'CREATE_COMPLETE', CreationTime: new Date() },
+        ],
+      }),
+      getTemplateSummary: jest.fn().mockRejectedValue({ name: 'AccessDenied' }),
+    };
+
+    const mockActiveAssets = { rememberStack: jest.fn() };
+
+    await expect(
+      refreshStacks(mockCfn as any, mockIoHelper as any, mockActiveAssets as any, undefined, [], true),
+    ).resolves.not.toThrow();
+
+    expect(mockCfn.getTemplateSummary).toHaveBeenCalledWith({ StackName: 'UnauthorizedStack' });
+    expect(mockIoHelper.defaults.warn).toHaveBeenCalledWith('Skipping unauthorized stack: UnauthorizedStack');
+  });
+});

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

@@ -1918,6 +1918,18 @@ export interface GarbageCollectionOptions {
    * @default false
    */
   readonly confirm?: boolean;
+
+  /**
+   *
+   * @default []
+   */
+  readonly ignoreStacks?: string[];
+
+  /**
+   *
+   * @default false
+   */
+  readonly skipUnauthorizedStacks?: boolean;
 }
 export interface MigrateOptions {
   /**

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

@@ -487,6 +487,8 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
           createdBufferDays: args['created-buffer-days'],
           bootstrapStackName: args.toolkitStackName ?? args.bootstrapStackName,
           confirm: args.confirm,
+          ignoreStacks: args['ignore-stacks'],
+          skipUnauthorizedStacks: args['skip-unauthorized-stacks'],
         });
 
       case 'flags':