feat(cli): support optimistic stabilization strategy(--exit-on-config-complete)

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/cli.integtest.ts

@@ -488,6 +488,17 @@ integTest('deploy with notification ARN', withDefaultFixture(async (fixture) =>
   }
 }));
 
+integTest('deploy with optimistic stabilization', withDefaultFixture(async (fixture) => {
+  await fixture.cdkDeploy('test-optimistic', {
+    options: ['--optimistic'],
+  });
+  // verify that the stack we deployed has our notification ARN
+  const describeResponse = await fixture.aws.cloudFormation('describeStacks', {
+    StackName: fixture.fullStackName('test-optimistic'),
+  });
+  expect(describeResponse.Stacks?.[0].DetailedStatus).toEqual('CONFIGURATION_COMPLETE');
+}));
+
 // NOTE: this doesn't currently work with modern-style synthesis, as the bootstrap
 // role by default will not have permission to iam:PassRole the created role.
 integTest('deploy with role', withDefaultFixture(async (fixture) => {

packages/aws-cdk/README.md

@@ -464,6 +464,20 @@ and might have breaking changes in the future.
 
 > *: `Fn::GetAtt` is only partially supported. Refer to [this implementation](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk/lib/api/evaluate-cloudformation-template.ts#L477-L492) for supported resources and attributes.
 
+#### Optimistic Stabilization
+
+You can pass the `--optimistic` flag to the `deploy` command:
+
+```console
+$ cdk deploy --optimistic [StackNames]
+```
+
+This will perform a deployment with optimistic stabilization strategy by watching the `CONFIGURATION_COMPLETE`
+detailed status and immediately return success when detected. This speeds up the stack deployment
+by ignoring the stack-level eventual consistency checks. Read [this](https://aws.amazon.com/blogs/devops/how-we-sped-up-aws-cloudformation-deployments-with-optimistic-stabilization/) for more details.
+
+The `--optimistic` flag is supported by `cdk deploy` and `cdk destroy`.
+
 ### `cdk watch`
 
 The `watch` command is similar to `deploy`,

packages/aws-cdk/lib/api/deploy-stack.ts

@@ -198,6 +198,13 @@ export interface DeployStackOptions {
    * @default true To remain backward compatible.
    */
   readonly assetParallelism?: boolean;
+
+  /**
+   * Whether to enable optimistic stabilization.
+   *
+   * @default false
+   */
+  readonly optimistic?: boolean;
 }
 
 export type DeploymentMethod =
@@ -338,6 +345,7 @@ class FullCloudFormationDeployment {
   private readonly update: boolean;
   private readonly verb: string;
   private readonly uuid: string;
+  private readonly optimistic: boolean;
 
   constructor(
     private readonly options: DeployStackOptions,
@@ -352,6 +360,7 @@ class FullCloudFormationDeployment {
     this.update = cloudFormationStack.exists && cloudFormationStack.stackStatus.name !== 'REVIEW_IN_PROGRESS';
     this.verb = this.update ? 'update' : 'create';
     this.uuid = uuid.v4();
+    this.optimistic = options.optimistic ?? false;
   }
 
   public async performDeployment(): Promise<DeployStackResult> {
@@ -513,7 +522,7 @@ class FullCloudFormationDeployment {
 
     let finalState = this.cloudFormationStack;
     try {
-      const successStack = await waitForStackDeploy(this.cfn, this.stackName);
+      const successStack = await waitForStackDeploy(this.cfn, this.stackName, this.optimistic);
 
       // This shouldn't really happen, but catch it anyway. You never know.
       if (!successStack) { throw new Error('Stack deploy failed (the stack disappeared while we were deploying it)'); }
@@ -569,6 +578,7 @@ export interface DestroyStackOptions {
   deployName?: string;
   quiet?: boolean;
   ci?: boolean;
+  optimistic?: boolean;
 }
 
 export async function destroyStack(options: DestroyStackOptions) {
@@ -585,7 +595,7 @@ export async function destroyStack(options: DestroyStackOptions) {
 
   try {
     await cfn.deleteStack({ StackName: deployName, RoleARN: options.roleArn }).promise();
-    const destroyedStack = await waitForStackDelete(cfn, deployName);
+    const destroyedStack = await waitForStackDelete(cfn, deployName, options.optimistic);
     if (destroyedStack && destroyedStack.stackStatus.name !== 'DELETE_COMPLETE') {
       throw new Error(`Failed to destroy ${deployName}: ${destroyedStack.stackStatus}`);
     }

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

@@ -206,6 +206,13 @@ export interface DeployStackOptions {
    * @default false
    */
   ignoreNoStacks?: boolean;
+
+  /**
+   * Whether to enable optimistic stabilization.
+   *
+   * @default false
+   */
+  optimistic?: boolean;
 }
 
 interface AssetOptions {
@@ -260,6 +267,7 @@ export interface DestroyStackOptions {
   quiet?: boolean;
   force?: boolean;
   ci?: boolean;
+  optimistic?: boolean;
 }
 
 export interface StackExistsOptions {
@@ -413,6 +421,7 @@ export class Deployments {
       resourcesToImport: options.resourcesToImport,
       overrideTemplate: options.overrideTemplate,
       assetParallelism: options.assetParallelism,
+      optimistic: options.optimistic,
     });
   }
 
@@ -426,6 +435,7 @@ export class Deployments {
       deployName: options.deployName,
       quiet: options.quiet,
       ci: options.ci,
+      optimistic: options.optimistic,
     });
   }
 

packages/aws-cdk/lib/api/util/cloudformation.ts

@@ -1,7 +1,7 @@
 import { SSMPARAM_NO_INVALIDATE } from '@aws-cdk/cx-api';
 import * as cxapi from '@aws-cdk/cx-api';
 import { CloudFormation } from 'aws-sdk';
-import { StackStatus } from './cloudformation/stack-status';
+import { StackStatus, StackDetailedStatus } from './cloudformation/stack-status';
 import { makeBodyParameterAndUpload, TemplateBodyParameter } from './template-body-parameter';
 import { debug } from '../../logging';
 import { deserializeStructure } from '../../serialize';
@@ -133,6 +133,16 @@ export class CloudFormationStack {
     return StackStatus.fromStackDescription(this.stack!);
   }
 
+  /**
+   * The stack's detailed status
+   */
+  public get stackDetailedStatus(): StackDetailedStatus {
+    if (!this.exists) {
+      return new StackDetailedStatus('NOT_FOUND', 'Stack not found during lookup');
+    }
+    return StackDetailedStatus.fromStackDescription(this.stack!);
+  }
+
   /**
    * The stack's current tags
    *
@@ -435,14 +445,16 @@ export function changeSetHasNoChanges(description: CloudFormation.DescribeChange
  *
  * @param cfn        a CloudFormation client
  * @param stackName      the name of the stack to wait for after a delete
+ * @param optimistic  optimistic stabilization support
  *
  * @returns     the CloudFormation description of the stabilized stack after the delete attempt
  */
 export async function waitForStackDelete(
   cfn: CloudFormation,
-  stackName: string): Promise<CloudFormationStack | undefined> {
+  stackName: string,
+  optimistic?: boolean): Promise<CloudFormationStack | undefined> {
 
-  const stack = await stabilizeStack(cfn, stackName);
+  const stack = await stabilizeStack(cfn, stackName, optimistic);
   if (!stack) { return undefined; }
 
   const status = stack.stackStatus;
@@ -462,20 +474,27 @@ export async function waitForStackDelete(
  *
  * @param cfn        a CloudFormation client
  * @param stackName      the name of the stack to wait for after an update
+ * @param optimistic  optimistic stabilization support
  *
  * @returns     the CloudFormation description of the stabilized stack after the update attempt
  */
 export async function waitForStackDeploy(
   cfn: CloudFormation,
-  stackName: string): Promise<CloudFormationStack | undefined> {
+  stackName: string,
+  optimistic?: boolean): Promise<CloudFormationStack | undefined> {
 
-  const stack = await stabilizeStack(cfn, stackName);
+  const stack = await stabilizeStack(cfn, stackName, optimistic);
   if (!stack) { return undefined; }
 
   const status = stack.stackStatus;
+  const detailedStatus = stack.stackDetailedStatus;
 
   if (status.isCreationFailure) {
     throw new Error(`The stack named ${stackName} failed creation, it may need to be manually deleted from the AWS console: ${status}`);
+  } else if (detailedStatus.isConfigurationComplete) {
+    // Optimistic stabilization. Considering this in a stable status.
+    // When this happens, status.isDeploySuccess would be false but we consider it a successful deployment.
+    return stack;
   } else if (!status.isDeploySuccess) {
     throw new Error(`The stack named ${stackName} failed to deploy: ${status}`);
   }
@@ -486,7 +505,7 @@ export async function waitForStackDeploy(
 /**
  * Wait for a stack to become stable (no longer _IN_PROGRESS), returning it
  */
-export async function stabilizeStack(cfn: CloudFormation, stackName: string) {
+export async function stabilizeStack(cfn: CloudFormation, stackName: string, optimistic?: boolean) {
   debug('Waiting for stack %s to finish creating or updating...', stackName);
   return waitFor(async () => {
     const stack = await CloudFormationStack.lookup(cfn, stackName);
@@ -495,7 +514,13 @@ export async function stabilizeStack(cfn: CloudFormation, stackName: string) {
       return null;
     }
     const status = stack.stackStatus;
+    const detailedStatus = stack.stackDetailedStatus;
     if (status.isInProgress) {
+      // stack in optimistic stabilization status
+      if (optimistic && detailedStatus.isConfigurationComplete) {
+        debug('Stack %s in CONFIGURATION_COMPLETE detailed status. Considering this in a stable status (%s)', stackName, status);
+        return stack;
+      }
       debug('Stack %s has an ongoing operation in progress and is not stable (%s)', stackName, status);
       return undefined;
     } else if (status.isReviewInProgress) {

packages/aws-cdk/lib/api/util/cloudformation/stack-status.ts

@@ -50,3 +50,28 @@ export class StackStatus {
     return this.name + (this.reason ? ` (${this.reason})` : '');
   }
 }
+
+/**
+ * A utility class to inspect CloudFormation stack detailed statuses.
+ *
+ * @see https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-stacks.html
+ */
+export class StackDetailedStatus {
+  public static fromStackDescription(description: AWS.CloudFormation.Stack) {
+    return new StackDetailedStatus(description.DetailedStatus, description.StackStatusReason);
+  }
+
+  constructor(public readonly name?: string, public readonly reason?: string) {}
+
+  get isConfigurationComplete(): boolean {
+    return this.name === 'CONFIGURATION_COMPLETE';
+  }
+
+  get isValidationFailed(): boolean {
+    return this.name === 'VALIDATION_FAILED';
+  }
+
+  public toString(): string {
+    return this.name + (this.reason ? ` (${this.reason})` : '');
+  }
+}

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

@@ -356,6 +356,7 @@ export class CdkToolkit {
           extraUserAgent: options.extraUserAgent,
           assetParallelism: options.assetParallelism,
           ignoreNoStacks: options.ignoreNoStacks,
+          optimistic: options.optimistic,
         });
 
         const message = result.noOp
@@ -1345,6 +1346,13 @@ export interface DeployOptions extends CfnDeployOptions, WatchOptions {
    * @default false
    */
   readonly ignoreNoStacks?: boolean;
+
+  /**
+   * Whether to enable the optimistic stabilization.
+   *
+   * @default false
+   */
+  readonly optimistic?: boolean;
 }
 
 export interface ImportOptions extends CfnDeployOptions {

packages/aws-cdk/lib/cli.ts

@@ -174,7 +174,8 @@ async function parseCommandLineArguments(args: string[]) {
       .option('concurrency', { type: 'number', desc: 'Maximum number of simultaneous deployments (dependency permitting) to execute.', default: 1, requiresArg: true })
       .option('asset-parallelism', { type: 'boolean', desc: 'Whether to build/publish assets in parallel' })
       .option('asset-prebuild', { type: 'boolean', desc: 'Whether to build all assets before deploying the first stack (useful for failing Docker builds)', default: true })
-      .option('ignore-no-stacks', { type: 'boolean', desc: 'Whether to deploy if the app contains no stacks', default: false }),
+      .option('ignore-no-stacks', { type: 'boolean', desc: 'Whether to deploy if the app contains no stacks', default: false })
+      .option('optimistic', { type: 'boolean', desc: 'Whether to deploy with optimistic stabilization', default: false }),
     )
     .command('import [STACK]', 'Import existing resource(s) into the given STACK', (yargs: Argv) => yargs
       .option('execute', { type: 'boolean', desc: 'Whether to execute ChangeSet (--no-execute will NOT execute the ChangeSet)', default: true })
@@ -255,7 +256,8 @@ async function parseCommandLineArguments(args: string[]) {
     .command('destroy [STACKS..]', 'Destroy the stack(s) named STACKS', (yargs: Argv) => yargs
       .option('all', { type: 'boolean', default: false, desc: 'Destroy all available stacks' })
       .option('exclusively', { type: 'boolean', alias: 'e', desc: 'Only destroy requested stacks, don\'t include dependees' })
-      .option('force', { type: 'boolean', alias: 'f', desc: 'Do not ask for confirmation before destroying the stacks' }))
+      .option('force', { type: 'boolean', alias: 'f', desc: 'Do not ask for confirmation before destroying the stacks' })
+      .option('optimistic', { type: 'boolean', desc: 'Whether to destroy with optimistic stabilization', default: false }))
     .command('diff [STACKS..]', 'Compares the specified stack with the deployed stack or a local template file, and returns with status 1 if any difference is found', (yargs: Argv) => yargs
       .option('exclusively', { type: 'boolean', alias: 'e', desc: 'Only diff requested stacks, don\'t include dependencies' })
       .option('context-lines', { type: 'number', desc: 'Number of context lines to include in arbitrary JSON diff rendering', default: 3, requiresArg: true })
@@ -604,6 +606,7 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
           assetParallelism: configuration.settings.get(['assetParallelism']),
           assetBuildTime: configuration.settings.get(['assetPrebuild']) ? AssetBuildTime.ALL_BEFORE_DEPLOY : AssetBuildTime.JUST_IN_TIME,
           ignoreNoStacks: args.ignoreNoStacks,
+          optimistic: args.optimistic,
         });
 
       case 'import':

packages/aws-cdk/lib/settings.ts

@@ -293,6 +293,7 @@ export class Settings {
       assetParallelism: argv['asset-parallelism'],
       assetPrebuild: argv['asset-prebuild'],
       ignoreNoStacks: argv['ignore-no-stacks'],
+      optimistic: argv.optimistic,
     });
   }