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

packages/@aws-cdk-testing/cli-integ/resources/cdk-apps/app/app.js

@@ -417,6 +417,36 @@ class LambdaHotswapStack extends cdk.Stack {
   }
 }
 
+class DetailedStatusStack extends cdk.Stack{
+  constructor(parent, id, props) {
+    super(parent, id, props);
+
+    const vpc = new ec2.Vpc(this, 'Vpc', {
+      natGateways: 0,
+      maxAzs: 1,
+      subnetConfiguration: [
+        {
+          cidrMask: 24,
+          name: 'Public',
+          subnetType: ec2.SubnetType.PUBLIC,
+        },
+      ],
+    });
+
+    const instance = new ec2.CfnInstance(this, 'Instance', {
+      instanceType: 't3.nano',
+      imageId: new ec2.AmazonLinuxImage().getImage(this).imageId,
+      subnetId: vpc.publicSubnets[0].subnetId,
+    });
+    new ec2.Volume(this, 'Volume', {
+      availabilityZone: instance.attrAvailabilityZone,
+      removalPolicy: cdk.RemovalPolicy.DESTROY,
+      size: cdk.Size.gibibytes(1),
+    });
+
+  }
+}
+
 class EcsHotswapStack extends cdk.Stack {
   constructor(parent, id, props) {
     super(parent, id, props);
@@ -647,6 +677,7 @@ switch (stackSet) {
     new LambdaStack(app, `${stackPrefix}-lambda`);
     new LambdaHotswapStack(app, `${stackPrefix}-lambda-hotswap`);
     new EcsHotswapStack(app, `${stackPrefix}-ecs-hotswap`);
+    new DetailedStatusStack(app, `${stackPrefix}-detailed-status`);
     new DockerStack(app, `${stackPrefix}-docker`);
     new DockerStackWithCustomFile(app, `${stackPrefix}-docker-with-custom-file`);
 

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

@@ -488,6 +488,14 @@ integTest('deploy with notification ARN', withDefaultFixture(async (fixture) =>
   }
 }));
 
+integTest('deploy with optimistic stabilization', withDefaultFixture(async (fixture) => {
+  const deployOutput = await fixture.cdkDeploy('detailed-status', {
+    options: ['--exit-on-config-complete', '--debug'],
+  });
+
+  expect(deployOutput).toContain('in CONFIGURATION_COMPLETE detailed status. Considering this in a stable status');
+}));
+
 // 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,24 @@ 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 `--exit-on-config-complete` flag to the `deploy` command:
+
+```console
+$ cdk deploy --exit-on-config-complete [StackNames]
+```
+
+This approach triggers a deployment and monitors the `CONFIGURATION_COMPLETE` detailed status from AWS CloudFormation.
+It immediately exits with a successful status once the `CONFIGURATION_COMPLETE` status is detected. This can speed up
+the stack deployment process by skipping the stack-level eventual consistency checks, which can be beneficial when you
+have multiple stacks that depend on each other.
+
+For more details on this, you can refer to the blog post at
+[this link](https://aws.amazon.com/blogs/devops/how-we-sped-up-aws-cloudformation-deployments-with-optimistic-stabilization/).
+
+The `--exit-on-config-complete` 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 exit on configuration complete.
+   *
+   * @default false
+   */
+  readonly exitOnConfigComplete?: boolean;
 }
 
 export type DeploymentMethod =
@@ -339,6 +346,7 @@ class FullCloudFormationDeployment {
   private readonly update: boolean;
   private readonly verb: string;
   private readonly uuid: string;
+  private readonly exitOnConfigComplete: boolean;
 
   constructor(
     private readonly options: DeployStackOptions,
@@ -353,6 +361,7 @@ class FullCloudFormationDeployment {
     this.update = cloudFormationStack.exists && cloudFormationStack.stackStatus.name !== 'REVIEW_IN_PROGRESS';
     this.verb = this.update ? 'update' : 'create';
     this.uuid = uuid.v4();
+    this.exitOnConfigComplete = options.exitOnConfigComplete ?? false;
   }
 
   public async performDeployment(): Promise<DeployStackResult> {
@@ -514,7 +523,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.exitOnConfigComplete);
 
       // 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)'); }
@@ -570,6 +579,7 @@ export interface DestroyStackOptions {
   deployName?: string;
   quiet?: boolean;
   ci?: boolean;
+  exitOnConfigComplete?: boolean;
 }
 
 export async function destroyStack(options: DestroyStackOptions) {
@@ -586,7 +596,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.exitOnConfigComplete);
     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 exit on configuration complete.
+   *
+   * @default false
+   */
+  exitOnConfigComplete?: boolean;
 }
 
 interface AssetOptions {
@@ -260,6 +267,7 @@ export interface DestroyStackOptions {
   quiet?: boolean;
   force?: boolean;
   ci?: boolean;
+  exitOnConfigComplete?: boolean;
 }
 
 export interface StackExistsOptions {
@@ -414,6 +422,7 @@ export class Deployments {
       resourcesToImport: options.resourcesToImport,
       overrideTemplate: options.overrideTemplate,
       assetParallelism: options.assetParallelism,
+      exitOnConfigComplete: options.exitOnConfigComplete,
     });
   }
 
@@ -427,6 +436,7 @@ export class Deployments {
       deployName: options.deployName,
       quiet: options.quiet,
       ci: options.ci,
+      exitOnConfigComplete: options.exitOnConfigComplete,
     });
   }
 

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

@@ -3,7 +3,7 @@ import { DescribeChangeSetOutput } from '@aws-cdk/cloudformation-diff';
 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';
@@ -135,6 +135,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
    *
@@ -431,14 +441,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 exitOnConfigComplete  whether to exit on configuration complete
  *
  * @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,
+  exitOnConfigComplete?: boolean): Promise<CloudFormationStack | undefined> {
 
-  const stack = await stabilizeStack(cfn, stackName);
+  const stack = await stabilizeStack(cfn, stackName, exitOnConfigComplete);
   if (!stack) { return undefined; }
 
   const status = stack.stackStatus;
@@ -458,20 +470,27 @@ export async function waitForStackDelete(
  *
  * @param cfn        a CloudFormation client
  * @param stackName      the name of the stack to wait for after an update
+ * @param exitOnConfigComplete  exit on configuration complete
  *
  * @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,
+  exitOnConfigComplete?: boolean): Promise<CloudFormationStack | undefined> {
 
-  const stack = await stabilizeStack(cfn, stackName);
+  const stack = await stabilizeStack(cfn, stackName, exitOnConfigComplete);
   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 (exitOnConfigComplete && detailedStatus.isConfigurationComplete) {
+    // Considering this in a stable status with exitOnConfigComplete is provided.
+    // 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}`);
   }
@@ -482,7 +501,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, exitOnConfigComplete?: boolean) {
   debug('Waiting for stack %s to finish creating or updating...', stackName);
   return waitFor(async () => {
     const stack = await CloudFormationStack.lookup(cfn, stackName);
@@ -491,7 +510,13 @@ export async function stabilizeStack(cfn: CloudFormation, stackName: string) {
       return null;
     }
     const status = stack.stackStatus;
+    const detailedStatus = stack.stackDetailedStatus;
     if (status.isInProgress) {
+      // stack in CONFIGURATION_COMPLETE detailed status
+      if (exitOnConfigComplete && 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

@@ -350,6 +350,7 @@ export class CdkToolkit {
           extraUserAgent: options.extraUserAgent,
           assetParallelism: options.assetParallelism,
           ignoreNoStacks: options.ignoreNoStacks,
+          exitOnConfigComplete: options.exitOnConfigComplete,
         });
 
         const message = result.noOp
@@ -1339,6 +1340,13 @@ export interface DeployOptions extends CfnDeployOptions, WatchOptions {
    * @default false
    */
   readonly ignoreNoStacks?: boolean;
+
+  /**
+   * Whether to exit on configuration complete.
+   *
+   * @default false
+   */
+  readonly exitOnConfigComplete?: 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('exit-on-config-complete', { type: 'boolean', desc: 'Whether to exit on configuration complete', 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('exit-on-config-complete', { type: 'boolean', desc: 'Whether to exit on configuration complete', 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,
+          exitOnConfigComplete: args.exitOnConfigComplete,
         });
 
       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'],
+      exitOnConfigComplete: argv.exitOnConfigComplete,
     });
   }