feat(gen2-migration): implement decommission command with optimized stateful resource validation (#14325)

chore: implement decommission with optimized stateful resource validation

Co-authored-by: Sai Ray <[email protected]>

Author: sai-ray

packages/amplify-cli/package.json

@@ -84,6 +84,7 @@
     "amplify-nodejs-function-runtime-provider": "2.5.32",
     "amplify-python-function-runtime-provider": "2.4.54",
     "aws-cdk-lib": "~2.189.1",
+    "bottleneck": "2.19.5",
     "chalk": "^4.1.1",
     "ci-info": "^3.8.0",
     "cli-table3": "^0.6.0",

packages/amplify-cli/src/__tests__/commands/gen2-migration/_validations.test.ts

@@ -3,6 +3,22 @@ import { $TSContext, stateManager } from '@aws-amplify/amplify-cli-core';
 import { CloudFormationClient, DescribeChangeSetOutput } from '@aws-sdk/client-cloudformation';
 
 jest.mock('@aws-sdk/client-cloudformation');
+jest.mock('bottleneck', () => {
+  return jest.fn().mockImplementation(() => ({
+    schedule: jest.fn((fn) => fn()),
+  }));
+});
+jest.mock('@aws-amplify/amplify-prompts', () => ({
+  printer: {
+    error: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+  },
+  AmplifySpinner: jest.fn().mockImplementation(() => ({
+    start: jest.fn(),
+    stop: jest.fn(),
+  })),
+}));
 jest.mock('@aws-amplify/amplify-cli-core', () => ({
   ...jest.requireActual('@aws-amplify/amplify-cli-core'),
   stateManager: {
@@ -20,6 +36,19 @@ describe('AmplifyGen2MigrationValidations', () => {
   });
 
   describe('validateStatefulResources', () => {
+    let mockSend: jest.Mock;
+
+    beforeEach(() => {
+      mockSend = jest.fn();
+      (CloudFormationClient as jest.Mock).mockImplementation(() => ({
+        send: mockSend,
+      }));
+    });
+
+    afterEach(() => {
+      jest.clearAllMocks();
+    });
+
     it('should pass when no changes exist', async () => {
       const changeSet: DescribeChangeSetOutput = {};
       await expect(validations.validateStatefulResources(changeSet)).resolves.not.toThrow();
@@ -56,8 +85,8 @@ describe('AmplifyGen2MigrationValidations', () => {
       };
       await expect(validations.validateStatefulResources(changeSet)).rejects.toMatchObject({
         name: 'DestructiveMigrationError',
-        message: 'Stateful resources scheduled for deletion: MyTable (AWS::DynamoDB::Table).',
-        resolution: 'Review the migration plan and ensure data is backed up before proceeding.',
+        message: 'Decommission will delete stateful resources.',
+        resolution: 'Review the resources above and ensure data is backed up before proceeding.',
       });
     });
 
@@ -84,8 +113,8 @@ describe('AmplifyGen2MigrationValidations', () => {
       };
       await expect(validations.validateStatefulResources(changeSet)).rejects.toMatchObject({
         name: 'DestructiveMigrationError',
-        message: 'Stateful resources scheduled for deletion: Bucket1 (AWS::S3::Bucket), UserPool1 (AWS::Cognito::UserPool).',
-        resolution: 'Review the migration plan and ensure data is backed up before proceeding.',
+        message: 'Decommission will delete stateful resources.',
+        resolution: 'Review the resources above and ensure data is backed up before proceeding.',
       });
     });
 
@@ -176,8 +205,8 @@ describe('AmplifyGen2MigrationValidations', () => {
       };
       await expect(validations.validateStatefulResources(changeSet)).rejects.toMatchObject({
         name: 'DestructiveMigrationError',
-        message: 'Stateful resources scheduled for deletion: MyEBSVolume (AWS::EC2::Volume).',
-        resolution: 'Review the migration plan and ensure data is backed up before proceeding.',
+        message: 'Decommission will delete stateful resources.',
+        resolution: 'Review the resources above and ensure data is backed up before proceeding.',
       });
     });
 
@@ -212,9 +241,8 @@ describe('AmplifyGen2MigrationValidations', () => {
       };
       await expect(validations.validateStatefulResources(changeSet)).rejects.toMatchObject({
         name: 'DestructiveMigrationError',
-        message:
-          'Stateful resources scheduled for deletion: Database (AWS::RDS::DBInstance), UsersTable (AWS::DynamoDB::Table), EventStream (AWS::Kinesis::Stream).',
-        resolution: 'Review the migration plan and ensure data is backed up before proceeding.',
+        message: 'Decommission will delete stateful resources.',
+        resolution: 'Review the resources above and ensure data is backed up before proceeding.',
       });
     });
 
@@ -321,34 +349,20 @@ describe('AmplifyGen2MigrationValidations', () => {
       };
       await expect(validations.validateStatefulResources(changeSet)).rejects.toMatchObject({
         name: 'DestructiveMigrationError',
-        message: 'Stateful resources scheduled for deletion: DeletedBucket (AWS::S3::Bucket).',
+        message: 'Decommission will delete stateful resources.',
       });
     });
-  });
-
-  describe('validateStatefulResources - nested stacks', () => {
-    let mockSend: jest.Mock;
-
-    beforeEach(() => {
-      mockSend = jest.fn();
-      (CloudFormationClient as jest.Mock).mockImplementation(() => ({
-        send: mockSend,
-      }));
-    });
-
-    afterEach(() => {
-      jest.clearAllMocks();
-    });
 
     it('should throw when nested stack contains stateful resources', async () => {
       mockSend.mockResolvedValueOnce({
-        StackResources: [
+        StackResourceSummaries: [
           {
             ResourceType: 'AWS::DynamoDB::Table',
             PhysicalResourceId: 'MyTable',
             LogicalResourceId: 'Table',
           },
         ],
+        NextToken: undefined,
       });
 
       const changeSet: DescribeChangeSetOutput = {
@@ -367,20 +381,20 @@ describe('AmplifyGen2MigrationValidations', () => {
 
       await expect(validations.validateStatefulResources(changeSet)).rejects.toMatchObject({
         name: 'DestructiveMigrationError',
-        message:
-          'Stateful resources scheduled for deletion: AuthStack (AWS::CloudFormation::Stack) containing: Table (AWS::DynamoDB::Table).',
+        message: 'Decommission will delete stateful resources.',
       });
     });
 
     it('should pass when nested stack contains only stateless resources', async () => {
       mockSend.mockResolvedValueOnce({
-        StackResources: [
+        StackResourceSummaries: [
           {
             ResourceType: 'AWS::Lambda::Function',
             PhysicalResourceId: 'MyFunction',
             LogicalResourceId: 'Function',
           },
         ],
+        NextToken: undefined,
       });
 
       const changeSet: DescribeChangeSetOutput = {
@@ -402,23 +416,25 @@ describe('AmplifyGen2MigrationValidations', () => {
 
     it('should handle multiple levels of nested stacks', async () => {
       mockSend.mockResolvedValueOnce({
-        StackResources: [
+        StackResourceSummaries: [
           {
             ResourceType: 'AWS::CloudFormation::Stack',
             PhysicalResourceId: 'storage-nested-stack',
             LogicalResourceId: 'StorageNestedStack',
           },
         ],
+        NextToken: undefined,
       });
 
       mockSend.mockResolvedValueOnce({
-        StackResources: [
+        StackResourceSummaries: [
           {
             ResourceType: 'AWS::S3::Bucket',
             PhysicalResourceId: 'my-bucket',
             LogicalResourceId: 'Bucket',
           },
         ],
+        NextToken: undefined,
       });
 
       const changeSet: DescribeChangeSetOutput = {
@@ -460,13 +476,14 @@ describe('AmplifyGen2MigrationValidations', () => {
 
     it('should handle mixed direct and nested stateful resources', async () => {
       mockSend.mockResolvedValueOnce({
-        StackResources: [
+        StackResourceSummaries: [
           {
             ResourceType: 'AWS::Cognito::UserPool',
             PhysicalResourceId: 'user-pool',
             LogicalResourceId: 'UserPool',
           },
         ],
+        NextToken: undefined,
       });
 
       const changeSet: DescribeChangeSetOutput = {
@@ -493,7 +510,7 @@ describe('AmplifyGen2MigrationValidations', () => {
 
       await expect(validations.validateStatefulResources(changeSet)).rejects.toMatchObject({
         name: 'DestructiveMigrationError',
-        message: expect.stringContaining('DirectTable'),
+        message: 'Decommission will delete stateful resources.',
       });
     });
   });

packages/amplify-cli/src/commands/gen2-migration/_validations.ts

@@ -1,16 +1,24 @@
 import { AmplifyDriftDetector } from '../drift';
 import { $TSContext, AmplifyError, stateManager } from '@aws-amplify/amplify-cli-core';
-import { printer } from '@aws-amplify/amplify-prompts';
+import { printer, AmplifySpinner } from '@aws-amplify/amplify-prompts';
 import {
   DescribeChangeSetOutput,
   CloudFormationClient,
   DescribeStacksCommand,
-  DescribeStackResourcesCommand,
+  ListStackResourcesCommand,
 } from '@aws-sdk/client-cloudformation';
 import { STATEFUL_RESOURCES } from './stateful-resources';
+import CLITable from 'cli-table3';
+import Bottleneck from 'bottleneck';
 import execa from 'execa';
 
 export class AmplifyGen2MigrationValidations {
+  private spinner?: AmplifySpinner;
+  private limiter = new Bottleneck({
+    maxConcurrent: 3,
+    minTime: 50,
+  });
+
   constructor(private readonly context: $TSContext) {}
 
   // public async validateDrift(): Promise<void> {
@@ -86,28 +94,52 @@ export class AmplifyGen2MigrationValidations {
   public async validateStatefulResources(changeSet: DescribeChangeSetOutput): Promise<void> {
     if (!changeSet.Changes) return;
 
-    const statefulRemoves: string[] = [];
+    this.spinner = new AmplifySpinner();
+    this.spinner.start('Scanning for stateful resources...');
+
+    const statefulRemoves: Array<{ category: string; resourceType: string; physicalId: string }> = [];
     for (const change of changeSet.Changes) {
       if (change.Type === 'Resource' && change.ResourceChange?.Action === 'Remove' && change.ResourceChange?.ResourceType) {
         if (change.ResourceChange.ResourceType === 'AWS::CloudFormation::Stack' && change.ResourceChange.PhysicalResourceId) {
-          const nestedResources = await this.getStatefulResources(change.ResourceChange.PhysicalResourceId);
-          if (nestedResources.length > 0) {
-            statefulRemoves.push(
-              `${change.ResourceChange.LogicalResourceId} (${change.ResourceChange.ResourceType}) containing: ${nestedResources.join(
-                ', ',
-              )}`,
-            );
-          }
+          const category = this.extractCategory(change.ResourceChange.LogicalResourceId || '');
+          this.spinner.start(`Scanning '${category}'...`);
+          const nestedResources = await this.getStatefulResources(
+            change.ResourceChange.PhysicalResourceId,
+            change.ResourceChange.LogicalResourceId,
+          );
+          statefulRemoves.push(...nestedResources);
         } else if (STATEFUL_RESOURCES.has(change.ResourceChange.ResourceType)) {
-          statefulRemoves.push(`${change.ResourceChange.LogicalResourceId} (${change.ResourceChange.ResourceType})`);
+          const category = this.extractCategory(change.ResourceChange.LogicalResourceId || '');
+          const physicalId = change.ResourceChange.PhysicalResourceId || 'N/A';
+          this.spinner.start(`Scanning '${category}' category: found stateful resource "${physicalId}"`);
+          statefulRemoves.push({
+            category,
+            resourceType: change.ResourceChange.ResourceType,
+            physicalId,
+          });
         }
       }
     }
 
+    this.spinner.stop();
+    this.spinner = undefined;
+
     if (statefulRemoves.length > 0) {
+      const table = new CLITable({
+        head: ['Category', 'Resource Type', 'Physical ID'],
+        style: { head: ['red'] },
+      });
+
+      statefulRemoves.forEach((resource) => {
+        table.push([resource.category, resource.resourceType, resource.physicalId]);
+      });
+
+      printer.error('\nStateful resources scheduled for deletion:\n');
+      printer.info(table.toString());
+
       throw new AmplifyError('DestructiveMigrationError', {
-        message: `Stateful resources scheduled for deletion: ${statefulRemoves.join(', ')}.`,
-        resolution: 'Review the migration plan and ensure data is backed up before proceeding.',
+        message: 'Decommission will delete stateful resources.',
+        resolution: 'Review the resources above and ensure data is backed up before proceeding.',
       });
     }
   }
@@ -116,19 +148,72 @@ export class AmplifyGen2MigrationValidations {
     printer.warn('Not implemented');
   }
 
-  private async getStatefulResources(stackName: string): Promise<string[]> {
-    const statefulResources: string[] = [];
-    const cfn = new CloudFormationClient({});
-    const { StackResources } = await cfn.send(new DescribeStackResourcesCommand({ StackName: stackName }));
-
-    for (const resource of StackResources ?? []) {
-      if (resource.ResourceType === 'AWS::CloudFormation::Stack' && resource.PhysicalResourceId) {
-        const nested = await this.getStatefulResources(resource.PhysicalResourceId);
-        statefulResources.push(...nested);
-      } else if (resource.ResourceType && STATEFUL_RESOURCES.has(resource.ResourceType)) {
-        statefulResources.push(`${resource.LogicalResourceId} (${resource.ResourceType})`);
+  private async getStatefulResources(
+    stackName: string,
+    parentLogicalId?: string,
+  ): Promise<Array<{ category: string; resourceType: string; physicalId: string }>> {
+    const statefulResources: Array<{ category: string; resourceType: string; physicalId: string }> = [];
+    const cfn = new CloudFormationClient({
+      maxAttempts: 5,
+      retryMode: 'adaptive',
+    });
+    const parentCategory = parentLogicalId ? this.extractCategory(parentLogicalId) : undefined;
+
+    let nextToken: string | undefined;
+    const nestedStackTasks: Array<{ physicalId: string; logicalId: string | undefined }> = [];
+
+    do {
+      const response = await cfn.send(new ListStackResourcesCommand({ StackName: stackName, NextToken: nextToken }));
+      nextToken = response.NextToken;
+
+      for (const resource of response.StackResourceSummaries ?? []) {
+        if (resource.ResourceType === 'AWS::CloudFormation::Stack' && resource.PhysicalResourceId) {
+          nestedStackTasks.push({
+            physicalId: resource.PhysicalResourceId,
+            logicalId: resource.LogicalResourceId,
+          });
+        } else if (resource.ResourceType && STATEFUL_RESOURCES.has(resource.ResourceType)) {
+          const category = parentCategory || this.extractCategory(resource.LogicalResourceId || '');
+          const physicalId = resource.PhysicalResourceId || 'N/A';
+          if (this.spinner) {
+            this.spinner.start(`Scanning '${category}' category: found stateful resource "${physicalId}"`);
+          }
+          statefulResources.push({
+            category,
+            resourceType: resource.ResourceType,
+            physicalId,
+          });
+        }
       }
-    }
+    } while (nextToken);
+
+    const nestedResults = await Promise.all(
+      nestedStackTasks.map((task) =>
+        this.limiter.schedule(() => {
+          const category = this.extractCategory(task.logicalId || '');
+          return this.getStatefulResources(task.physicalId, category !== 'other' ? task.logicalId : parentLogicalId);
+        }),
+      ),
+    );
+
+    nestedResults.forEach((nested) => statefulResources.push(...nested));
     return statefulResources;
   }
+
+  private extractCategory(logicalId: string): string {
+    const idLower = logicalId.toLowerCase();
+    if (idLower.includes('auth')) return 'Auth';
+    if (idLower.includes('storage')) return 'Storage';
+    if (idLower.includes('function')) return 'Function';
+    if (idLower.includes('api')) return 'Api';
+    if (idLower.includes('analytics')) return 'Analytics';
+    if (idLower.includes('hosting')) return 'Hosting';
+    if (idLower.includes('notifications')) return 'Notifications';
+    if (idLower.includes('interactions')) return 'Interactions';
+    if (idLower.includes('predictions')) return 'Predictions';
+    if (idLower.includes('deployment') || idLower.includes('infrastructure')) return 'Core Infrastructure';
+    if (idLower.includes('geo')) return 'Geo';
+    if (idLower.includes('custom')) return 'Custom';
+    return 'other';
+  }
 }