feat(cli): change set review on deploy

Author: orien

packages/@aws-cdk/toolkit-lib/lib/actions/deploy/index.ts

@@ -35,6 +35,41 @@ export interface ChangeSetDeployment {
    * @default false
    */
   readonly importExistingResources?: boolean;
+
+  /**
+   * Whether to execute an existing change set instead of creating a new one.
+   * When true, the specified changeSetName must exist and will be executed directly.
+   * When false or undefined, a new change set will be created.
+   *
+   * This is useful for secure change set review workflows where:
+   * 1. A change set is created with `execute: false`
+   * 2. The change set is reviewed by authorized personnel
+   * 3. The same change set is executed using this option to ensure
+   *    the exact changes that were reviewed are deployed
+   *
+   * @example
+   * // Step 1: Create change set for review
+   * deployStack(\{
+   *   deploymentMethod: \{
+   *     method: 'change-set',
+   *     changeSetName: 'my-review-changeset',
+   *     execute: false
+   *   \}
+   * \});
+   *
+   * // Step 2: Execute the reviewed change set
+   * deployStack(\{
+   *   deploymentMethod: \{
+   *     method: 'change-set',
+   *     changeSetName: 'my-review-changeset',
+   *     executeExistingChangeSet: true,
+   *     execute: true
+   *   \}
+   * \});
+   *
+   * @default false
+   */
+  readonly executeExistingChangeSet?: boolean;
 }
 
 /**

packages/@aws-cdk/toolkit-lib/lib/api/deployments/deploy-stack.ts

@@ -430,10 +430,34 @@ class FullCloudFormationDeployment {
     const changeSetName = deploymentMethod.changeSetName ?? 'cdk-deploy-change-set';
     const execute = deploymentMethod.execute ?? true;
     const importExistingResources = deploymentMethod.importExistingResources ?? false;
-    const changeSetDescription = await this.createChangeSet(changeSetName, execute, importExistingResources);
+    const executeExistingChangeSet = deploymentMethod.executeExistingChangeSet ?? false;
+
+    let changeSetDescription: DescribeChangeSetCommandOutput;
+
+    if (executeExistingChangeSet) {
+      // Execute an existing change set instead of creating a new one
+      await this.ioHelper.defaults.info(format('Executing existing change set %s on stack %s', changeSetName, this.stackName));
+      changeSetDescription = await this.cfn.describeChangeSet({
+        StackName: this.stackName,
+        ChangeSetName: changeSetName,
+      });
+
+      // Verify the change set exists and is in a valid state
+      if (!changeSetDescription.ChangeSetId) {
+        throw new ToolkitError(format('Change set %s not found on stack %s', changeSetName, this.stackName));
+      }
+      if (changeSetDescription.Status !== 'CREATE_COMPLETE') {
+        throw new ToolkitError(format('Change set %s is in status %s and cannot be executed', changeSetName, changeSetDescription.Status));
+      }
+    } else {
+      // Create a new change set (existing behavior)
+      changeSetDescription = await this.createChangeSet(changeSetName, execute, importExistingResources);
+    }
+
     await this.updateTerminationProtection();
 
-    if (changeSetHasNoChanges(changeSetDescription)) {
+    // Only check for empty changes when creating a new change set, not when executing an existing one
+    if (!executeExistingChangeSet && changeSetHasNoChanges(changeSetDescription)) {
       await this.ioHelper.defaults.debug(format('No changes are to be performed on %s.', this.stackName));
       if (execute) {
         await this.ioHelper.defaults.debug(format('Deleting empty change set %s', changeSetDescription.ChangeSetId));
@@ -768,6 +792,13 @@ async function canSkipDeploy(
     return false;
   }
 
+  // Executing existing change set, never skip
+  if (deployStackOptions.deploymentMethod?.method === 'change-set' &&
+      deployStackOptions.deploymentMethod.executeExistingChangeSet === true) {
+    await ioHelper.defaults.debug(`${deployName}: executing existing change set, never skip`);
+    return false;
+  }
+
   // No existing stack
   if (!cloudFormationStack.exists) {
     await ioHelper.defaults.debug(`${deployName}: no existing stack`);

packages/@aws-cdk/toolkit-lib/lib/api/deployments/deployments.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'crypto';
 import * as cdk_assets from '@aws-cdk/cdk-assets-lib';
 import type * as cxapi from '@aws-cdk/cx-api';
+import type { DescribeChangeSetCommandOutput } from '@aws-sdk/client-cloudformation';
 import * as chalk from 'chalk';
 import { AssetManifestBuilder } from './asset-manifest-builder';
 import {
@@ -674,6 +675,34 @@ export class Deployments {
     return publisher.isEntryPublished(asset);
   }
 
+  /**
+   * Read change set details for a stack
+   */
+  public async describeChangeSet(
+    stackArtifact: cxapi.CloudFormationStackArtifact,
+    changeSetName: string,
+  ): Promise<DescribeChangeSetCommandOutput> {
+    const env = await this.envs.accessStackForReadOnlyStackOperations(stackArtifact);
+    return env.sdk.cloudFormation().describeChangeSet({
+      StackName: stackArtifact.stackName,
+      ChangeSetName: changeSetName,
+    });
+  }
+
+  /**
+   * Delete a change set for a stack
+   */
+  public async deleteChangeSet(
+    stackArtifact: cxapi.CloudFormationStackArtifact,
+    changeSetName: string,
+  ): Promise<void> {
+    const env = await this.envs.accessStackForMutableStackOperations(stackArtifact);
+    await env.sdk.cloudFormation().deleteChangeSet({
+      StackName: stackArtifact.stackName,
+      ChangeSetName: changeSetName,
+    });
+  }
+
   /**
    * Validate that the bootstrap stack has the right version for this stack
    *

packages/@aws-cdk/toolkit-lib/test/api/deployments/cloudformation-deployments.test.ts

@@ -1,13 +1,15 @@
 import * as cxapi from '@aws-cdk/cx-api';
 import {
   ContinueUpdateRollbackCommand,
+  DeleteChangeSetCommand,
   DescribeStackEventsCommand,
   DescribeStacksCommand,
   ListStackResourcesCommand,
   RollbackStackCommand,
   type StackResourceSummary,
   StackStatus,
   DescribeChangeSetCommand,
+  ChangeAction,
   ChangeSetStatus,
   CreateChangeSetCommand,
 } from '@aws-sdk/client-cloudformation';
@@ -1215,3 +1217,107 @@ function givenStacks(stacks: Record<string, { template: any; stackStatus?: strin
     }
   });
 }
+
+describe('describeChangeSet', () => {
+  it('calls CloudFormation describeChangeSet with correct parameters', async () => {
+    // GIVEN
+    const changeSetName = 'test-changeset';
+    const stackName = 'test-stack';
+    const stack = testStack({ stackName });
+    const mockChangeSetResponse = {
+      ChangeSetId: 'arn:aws:cloudformation:us-east-1:123456789012:changeSet/test-changeset/12345',
+      ChangeSetName: changeSetName,
+      StackId: 'arn:aws:cloudformation:us-east-1:123456789012:stack/test-stack/12345',
+      Status: ChangeSetStatus.CREATE_COMPLETE,
+      Changes: [{
+        Type: 'Resource' as const,
+        ResourceChange: {
+          Action: ChangeAction.Modify,
+          LogicalResourceId: 'TestResource',
+          ResourceType: 'AWS::S3::Bucket',
+        },
+      }],
+    };
+    mockCloudFormationClient.on(DescribeChangeSetCommand).resolves(mockChangeSetResponse);
+
+    // WHEN
+    const result = await deployments.describeChangeSet(stack, changeSetName);
+
+    // THEN
+    expect(result).toEqual(mockChangeSetResponse);
+    expect(mockCloudFormationClient).toHaveReceivedCommandWith(DescribeChangeSetCommand, {
+      StackName: stackName,
+      ChangeSetName: changeSetName,
+    });
+  });
+
+  it('handles CloudFormation errors gracefully', async () => {
+    // GIVEN
+    const changeSetName = 'non-existent-changeset';
+    const stackName = 'test-stack';
+    const stack = testStack({ stackName });
+    const error = new Error('Change set not found');
+    mockCloudFormationClient.on(DescribeChangeSetCommand).rejects(error);
+
+    // WHEN
+    const result = deployments.describeChangeSet(stack, changeSetName);
+
+    // THEN
+    await expect(result).rejects.toThrow('Change set not found');
+  });
+
+  it('returns the change set', async () => {
+    // GIVEN
+    const changeSetName = 'empty-changeset';
+    const stackName = 'test-stack';
+    const stack = testStack({ stackName });
+    const mockChangeSetResponse = {
+      ChangeSetId: 'arn:aws:cloudformation:us-east-1:123456789012:changeSet/empty-changeset/12345',
+      ChangeSetName: changeSetName,
+      StackId: 'arn:aws:cloudformation:us-east-1:123456789012:stack/test-stack/12345',
+      Status: ChangeSetStatus.CREATE_COMPLETE,
+    };
+
+    mockCloudFormationClient.on(DescribeChangeSetCommand).resolves(mockChangeSetResponse);
+
+    // WHEN
+    const result = await deployments.describeChangeSet(stack, changeSetName);
+
+    // THEN
+    expect(result).toEqual(mockChangeSetResponse);
+  });
+});
+
+describe('deleteChangeSet', () => {
+  it('calls CloudFormation deleteChangeSet with correct parameters', async () => {
+    // GIVEN
+    const changeSetName = 'test-changeset';
+    const stackName = 'test-stack';
+    const stack = testStack({ stackName });
+    mockCloudFormationClient.on(DeleteChangeSetCommand).resolves({});
+
+    // WHEN
+    await deployments.deleteChangeSet(stack, changeSetName);
+
+    // THEN
+    expect(mockCloudFormationClient).toHaveReceivedCommandWith(DeleteChangeSetCommand, {
+      StackName: stackName,
+      ChangeSetName: changeSetName,
+    });
+  });
+
+  it('handles CloudFormation errors gracefully', async () => {
+    // GIVEN
+    const changeSetName = 'non-existent-changeset';
+    const stackName = 'test-stack';
+    const stack = testStack({ stackName });
+    const error = new Error('Change set not found');
+    mockCloudFormationClient.on(DeleteChangeSetCommand).rejects(error);
+
+    // WHEN
+    const result = deployments.deleteChangeSet(stack, changeSetName);
+
+    // THEN
+    await expect(result).rejects.toThrow('Change set not found');
+  });
+});