feat: add --skip-unauthorized-stacks and --ignore-stacks support to garbage collection

- Modify bootstrap lookup methods to handle AccessDenied errors
- Add error handling for CloudFormation listStacks and individual stacks
- Add null checks in garbage collection methods to skip S3/ECR when bootstrap access fails

Author: gandhya

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

@@ -178,6 +178,20 @@ interface GarbageCollectorProps {
    * @default true
    */
   readonly confirm?: boolean;
+
+  /**
+   * Stack names to ignore during garbage collection
+   *
+   * @default []
+   */
+  readonly ignoreNonCdkStacks?: string[];
+
+  /**
+   * Skip stacks that return AccessDenied errors
+   *
+   * @default false
+   */
+  readonly skipUnauthorizedStacks?: boolean;
 }
 
 /**
@@ -211,6 +225,13 @@ export class GarbageCollector {
   public async garbageCollect() {
     await this.ioHelper.defaults.debug(`${this.garbageCollectS3Assets} ${this.garbageCollectEcrAssets}`);
 
+    // Display warning if ignoring stacks
+    if (this.props.ignoreNonCdkStacks && this.props.ignoreNonCdkStacks.length > 0) {
+      await this.ioHelper.defaults.warn(
+        'WARNING: Ignoring stacks during garbage collection. Only use this for non-CDK stacks to avoid accidental asset deletion.',
+      );
+    }
+
     // SDKs
     const sdk = (await this.props.sdkProvider.forEnvironment(this.props.resolvedEnvironment, Mode.ForWriting)).sdk;
     const cfn = sdk.cloudFormation();
@@ -224,13 +245,17 @@ export class GarbageCollector {
       ioHelper: this.ioHelper,
       activeAssets,
       qualifier,
+      ignoreNonCdkStacks: this.props.ignoreNonCdkStacks,
+      skipUnauthorizedStacks: this.props.skipUnauthorizedStacks,
     });
     // Start the background refresh
     const backgroundStackRefresh = new BackgroundStackRefresh({
       cfn,
       ioHelper: this.ioHelper,
       activeAssets,
       qualifier,
+      ignoreNonCdkStacks: this.props.ignoreNonCdkStacks,
+      skipUnauthorizedStacks: this.props.skipUnauthorizedStacks,
     });
     backgroundStackRefresh.start();
 
@@ -255,6 +280,8 @@ export class GarbageCollector {
   public async garbageCollectEcr(sdk: SDK, activeAssets: ActiveAssetCache, backgroundStackRefresh: BackgroundStackRefresh) {
     const ecr = sdk.ecr();
     const repo = await this.bootstrapRepositoryName(sdk, this.bootstrapStackName);
+    // Null check to prevent an early error being thrown and invalidate skipUnauthorizedStacks functionality
+    if (!repo) return;
     const numImages = await this.numImagesInRepo(ecr, repo);
     const printer = new ProgressPrinter(this.ioHelper, numImages, 1000);
 
@@ -329,6 +356,8 @@ export class GarbageCollector {
   public async garbageCollectS3(sdk: SDK, activeAssets: ActiveAssetCache, backgroundStackRefresh: BackgroundStackRefresh) {
     const s3 = sdk.s3();
     const bucket = await this.bootstrapBucketName(sdk, this.bootstrapStackName);
+    // Null check to prevent an early error being thrown and invalidate skipUnauthorizedStack functionality
+    if (!bucket) return;
     const numObjects = await this.numObjectsInBucket(s3, bucket);
     const printer = new ProgressPrinter(this.ioHelper, numObjects, 1000);
 
@@ -582,19 +611,46 @@ export class GarbageCollector {
     }
   }
 
-  private async bootstrapBucketName(sdk: SDK, bootstrapStackName: string): Promise<string> {
-    const toolkitInfo = await ToolkitInfo.lookup(this.props.resolvedEnvironment, sdk, this.ioHelper, bootstrapStackName);
-    return toolkitInfo.bucketName;
+  private async bootstrapBucketName(sdk: SDK, bootstrapStackName: string): Promise<string | null> {
+    try {
+      const toolkitInfo = await ToolkitInfo.lookup(this.props.resolvedEnvironment, sdk, this.ioHelper, bootstrapStackName);
+      return toolkitInfo.bucketName;
+    } catch (error: any) {
+      // Conditional error handling to return null if skipUnauthorizedStacks is enabled instead of crashing
+      if (this.props.skipUnauthorizedStacks && error.message?.includes('AccessDenied')) {
+        await this.ioHelper.defaults.warn(`Skipping S3 garbage collection due to insufficient permissions to access bootstrap stack '${bootstrapStackName}'`);
+        return null;
+      }
+      throw error;
+    }
   }
 
-  private async bootstrapRepositoryName(sdk: SDK, bootstrapStackName: string): Promise<string> {
-    const toolkitInfo = await ToolkitInfo.lookup(this.props.resolvedEnvironment, sdk, this.ioHelper, bootstrapStackName);
-    return toolkitInfo.repositoryName;
+  private async bootstrapRepositoryName(sdk: SDK, bootstrapStackName: string): Promise<string | null> {
+    try {
+      const toolkitInfo = await ToolkitInfo.lookup(this.props.resolvedEnvironment, sdk, this.ioHelper, bootstrapStackName);
+      return toolkitInfo.repositoryName;
+    } catch (error: any) {
+      // Conditional error handling to return null if skipUnauthorizedStacks is enabled instead of crashing
+      if (this.props.skipUnauthorizedStacks && error.message?.includes('AccessDenied')) {
+        await this.ioHelper.defaults.warn(`Skipping ECR garbage collection due to insufficient permissions to access bootstrap stack '${bootstrapStackName}'`);
+        return null;
+      }
+      throw error;
+    }
   }
 
   private async bootstrapQualifier(sdk: SDK, bootstrapStackName: string): Promise<string | undefined> {
-    const toolkitInfo = await ToolkitInfo.lookup(this.props.resolvedEnvironment, sdk, this.ioHelper, bootstrapStackName);
-    return toolkitInfo.bootstrapStack.parameters.Qualifier;
+    try {
+      const toolkitInfo = await ToolkitInfo.lookup(this.props.resolvedEnvironment, sdk, this.ioHelper, bootstrapStackName);
+      return toolkitInfo.bootstrapStack.parameters.Qualifier;
+    } catch (error: any) {
+      // Return undefined if skipUnauthorizedStacks is enabled instead of crashing. Maintains the original return type
+      if (this.props.skipUnauthorizedStacks && error.message?.includes('AccessDenied')) {
+        await this.ioHelper.defaults.warn('Skipping bootstrap stack lookup due to AccessDenied error');
+        return undefined;
+      }
+      throw error;
+    }
   }
 
   private async numObjectsInBucket(s3: IS3Client, bucket: string): Promise<number> {

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,40 +37,72 @@ 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,
+  ignoreNonCdkStacks?: string[],
+  skipUnauthorizedStacks?: boolean,
+) {
   const stackNames: string[] = [];
-  await paginateSdkCall(async (nextToken) => {
-    const stacks = await cfn.listStacks({ NextToken: nextToken });
-
-    // We ignore stacks with these statuses because their assets are no longer live
-    const ignoredStatues = ['CREATE_FAILED', 'DELETE_COMPLETE', 'DELETE_IN_PROGRESS', 'DELETE_FAILED', 'REVIEW_IN_PROGRESS'];
-    stackNames.push(
-      ...(stacks.StackSummaries ?? [])
-        .filter((s: any) => !ignoredStatues.includes(s.StackStatus))
-        .map((s: any) => s.StackId ?? s.StackName),
-    );
+  // Handle the error if the user is unable to list stacks due to insufficient permissions
+  try {
+    await paginateSdkCall(async (nextToken) => {
+      const stacks = await cfn.listStacks({ NextToken: nextToken });
+
+      // We ignore stacks with these statuses because their assets are no longer live
+      const ignoredStatues = ['CREATE_FAILED', 'DELETE_COMPLETE', 'DELETE_IN_PROGRESS', 'DELETE_FAILED', 'REVIEW_IN_PROGRESS'];
+      stackNames.push(
+        ...(stacks.StackSummaries ?? [])
+          .filter((s: any) => !ignoredStatues.includes(s.StackStatus))
+          .map((s: any) => s.StackId ?? s.StackName),
+      );
 
-    return stacks.NextToken;
-  });
+      return stacks.NextToken;
+    });
+  } catch (error: any) {
+    if (error.name == 'AccessDenied' && skipUnauthorizedStacks) {
+      await ioHelper.defaults.warn('Skipping all stack processing due to AccessDenied on listStacks');
+      return [];
+    }
+    throw error;
+  }
 
   await ioHelper.defaults.debug(`Parsing through ${stackNames.length} stacks`);
 
   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 ignore patterns
+    if (ignoreNonCdkStacks && ignoreNonCdkStacks.length > 0) {
+      const shouldSkip = ignoreNonCdkStacks.some(pattern => minimatch(stack, pattern));
+      if (shouldSkip) {
+        await ioHelper.defaults.debug(`Skipping stack ${stack}`);
+        continue;
+      }
+    }
+    // Allows users to skip a stack if they can't access it instead of failing
+    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) {
+      if (error.name === 'AccessDenied' && skipUnauthorizedStacks) {
+        await ioHelper.defaults.warn(`Skipping stack ${stack} due to AccessDenied error`);
+        continue;
+      }
+      throw error;
     }
   }
 
@@ -102,11 +135,19 @@ export interface RefreshStacksProps {
   readonly ioHelper: IoHelper;
   readonly activeAssets: ActiveAssetCache;
   readonly qualifier?: string;
+  readonly ignoreNonCdkStacks?: string[];
+  readonly skipUnauthorizedStacks?: boolean;
 }
 
 export async function refreshStacks(props: RefreshStacksProps) {
   try {
-    const stacks = await fetchAllStackTemplates(props.cfn, props.ioHelper, props.qualifier);
+    const stacks = await fetchAllStackTemplates(
+      props.cfn,
+      props.ioHelper,
+      props.qualifier,
+      props.ignoreNonCdkStacks,
+      props.skipUnauthorizedStacks,
+    );
     for (const stack of stacks) {
       props.activeAssets.rememberStack(stack);
     }
@@ -138,6 +179,16 @@ export interface BackgroundStackRefreshProps {
    * Stack bootstrap qualifier
    */
   readonly qualifier?: string;
+
+  /**
+   * Stack names to ignore during garbage collection
+   */
+  readonly ignoreNonCdkStacks?: string[];
+
+  /**
+   * Skip stacks that return AccessDenied errors
+   */
+  readonly skipUnauthorizedStacks?: boolean;
 }
 
 /**
@@ -166,6 +217,8 @@ export class BackgroundStackRefresh {
       ioHelper: this.props.ioHelper,
       activeAssets: this.props.activeAssets,
       qualifier: this.props.qualifier,
+      ignoreNonCdkStacks: this.props.ignoreNonCdkStacks,
+      skipUnauthorizedStacks: this.props.skipUnauthorizedStacks,
     });
     this.justRefreshedStacks();
 

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

@@ -1133,6 +1133,8 @@ export class CdkToolkit {
         action: options.action ?? 'full',
         type: options.type ?? 'all',
         confirm: options.confirm ?? true,
+        ignoreNonCdkStacks: options.ignoreNonCdkStacks,
+        skipUnauthorizedStacks: options.skipUnauthorizedStacks,
       });
       await gc.garbageCollect();
     }
@@ -1918,6 +1920,20 @@ export interface GarbageCollectionOptions {
    * @default false
    */
   readonly confirm?: boolean;
+
+  /**
+   * Stack names to ignore during garbage collection
+   *
+   * @default []
+   */
+  readonly ignoreNonCdkStacks?: string[];
+
+  /**
+   * Skip stacks that return AccessDenied errors
+   *
+   * @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,
+          ignoreNonCdkStacks: arrayFromYargs(args['ignore-non-cdk-stacks']),
+          skipUnauthorizedStacks: args['skip-unauthorized-stacks'],
         });
 
       case 'flags':

packages/aws-cdk/lib/cli/parse-command-line-arguments.ts

@@ -364,6 +364,18 @@ export function parseCommandLineArguments(args: Array<string>): any {
             deprecated: 'use --toolkit-stack-name',
             requiresArg: true,
             conflicts: 'toolkit-stack-name',
+          })
+          .option('ignore-non-cdk-stacks', {
+            type: 'array',
+            desc: 'Stack names to ignore during garbage collection (WARNING: Only use this for non-CDK stacks to avoid accidentally deleting assets)',
+            default: [],
+            nargs: 1,
+            requiresArg: true,
+          })
+          .option('skip-unauthorized-stacks', {
+            default: false,
+            type: 'boolean',
+            desc: 'Skip stacks that return AccessDenied errors',
           }),
     )
     .command('flags [FLAGNAME..]', 'View and toggle feature flags.', (yargs: Argv) =>