feat(cli): control progress output style with --progress=bar|events (#9623)

Since the new deployment monitoring has been problematic on environments such as CI,
adding a switch called `progress` to allow users to set their deploy output display preference.

Supported values are `bar` and `events`. The default deployment display mode includes the
progress bar.

The workaround of adding `-v` to display the stack event history includes a lot of
undesired output and users have expressed that it includes a lot of noise.

If the key `progress` exists in user settings (`~/.cdk.json`) or project settings (`cdk.json`),
users will not need to specify it on every deploy and can set their desired default once.

closes #8696 

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: shivlaks

packages/aws-cdk/README.md

@@ -227,6 +227,33 @@ Example `outputs.json` after deployment of multiple stacks
 }
 ```
 
+##### Deployment Progress
+
+By default, stack deployment events are displayed as a progress bar with the events for the resource
+currently being deployed.
+
+Set the `--progress` flag to request the complete history which includes all CloudFormation events
+```console
+$ cdk deploy --progress events
+```
+
+Alternatively, the `progress` key can be specified in the project config (`cdk.json`).
+
+The following shows a sample `cdk.json` where the `progress` key is set to *events*.
+When `cdk deploy` is executed, deployment events will include the complete history.
+```
+{
+  "app": "npx ts-node bin/myproject.ts",
+  "context": {
+    "@aws-cdk/core:enableStackNameDuplicates": "true",
+    "aws-cdk:enableDiffNoFail": "true",
+    "@aws-cdk/core:stackRelativeExports": "true"
+  },
+  "progress": "events"
+}
+```
+The `progress` key can also be specified as a user setting (`~/.cdk.json`)
+
 #### `cdk destroy`
 Deletes a stack from it's environment. This will cause the resources in the stack to be destroyed (unless they were
 configured with a `DeletionPolicy` of `Retain`). During the stack destruction, the command will output progress

packages/aws-cdk/bin/cdk.ts

@@ -10,6 +10,7 @@ import { SdkProvider } from '../lib/api/aws-auth';
 import { CloudFormationDeployments } from '../lib/api/cloudformation-deployments';
 import { CloudExecutable } from '../lib/api/cxapp/cloud-executable';
 import { execProgram } from '../lib/api/cxapp/exec';
+import { StackActivityProgress } from '../lib/api/util/cloudformation/stack-activity-monitor';
 import { CdkToolkit } from '../lib/cdk-toolkit';
 import { RequireApproval } from '../lib/diff';
 import { availableInitLanguages, cliInit, printAvailableTemplates } from '../lib/init';
@@ -89,7 +90,8 @@ async function parseCommandLineArguments() {
       .option('force', { alias: 'f', type: 'boolean', desc: 'Always deploy stack even if templates are identical', default: false })
       .option('parameters', { type: 'array', desc: 'Additional parameters passed to CloudFormation at deploy time (STACK:KEY=VALUE)', nargs: 1, requiresArg: true, default: {} })
       .option('outputs-file', { type: 'string', alias: 'O', desc: 'Path to file where stack outputs will be written as JSON', requiresArg: true })
-      .option('previous-parameters', { type: 'boolean', default: true, desc: 'Use previous values for existing parameters (you must specify all parameters on every deployment if this is disabled)' }),
+      .option('previous-parameters', { type: 'boolean', default: true, desc: 'Use previous values for existing parameters (you must specify all parameters on every deployment if this is disabled)' })
+      .option('progress', { type: 'string', choices: [StackActivityProgress.BAR, StackActivityProgress.EVENTS], desc: 'Display mode for stack activity events.' }),
     )
     .command('destroy [STACKS..]', 'Destroy the stack(s) named STACKS', yargs => yargs
       .option('exclusively', { type: 'boolean', alias: 'e', desc: 'Only destroy requested stacks, don\'t include dependees' })
@@ -279,6 +281,7 @@ async function initCommandLine() {
           parameters: parameterMap,
           usePreviousParameters: args['previous-parameters'],
           outputsFile: args.outputsFile,
+          progress: configuration.settings.get(['progress']),
           ci: args.ci,
         });
 

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

@@ -7,6 +7,7 @@ import { Mode, SdkProvider } from './aws-auth';
 import { deployStack, DeployStackResult, destroyStack } from './deploy-stack';
 import { ToolkitInfo } from './toolkit-info';
 import { CloudFormationStack, Template } from './util/cloudformation';
+import { StackActivityProgress } from './util/cloudformation/stack-activity-monitor';
 
 export interface DeployStackOptions {
   /**
@@ -89,6 +90,14 @@ export interface DeployStackOptions {
    */
   usePreviousParameters?: boolean;
 
+  /**
+   * Display mode for stack deployment progress.
+   *
+   * @default - StackActivityProgress.Bar - stack events will be displayed for
+   *   the resource currently being deployed.
+   */
+  progress?: StackActivityProgress;
+
   /**
    * Whether we are on a CI system
    *
@@ -163,6 +172,7 @@ export class CloudFormationDeployments {
       force: options.force,
       parameters: options.parameters,
       usePreviousParameters: options.usePreviousParameters,
+      progress: options.progress,
       ci: options.ci,
     });
   }

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

@@ -11,7 +11,7 @@ import { contentHash } from '../util/content-hash';
 import { ISDK, SdkProvider } from './aws-auth';
 import { ToolkitInfo } from './toolkit-info';
 import { changeSetHasNoChanges, CloudFormationStack, StackParameters, TemplateParameters, waitForChangeSet, waitForStackDeploy, waitForStackDelete } from './util/cloudformation';
-import { StackActivityMonitor } from './util/cloudformation/stack-activity-monitor';
+import { StackActivityMonitor, StackActivityProgress } from './util/cloudformation/stack-activity-monitor';
 
 // We need to map regions to domain suffixes, and the SDK already has a function to do this.
 // It's not part of the public API, but it's also unlikely to go away.
@@ -153,6 +153,14 @@ export interface DeployStackOptions {
    */
   usePreviousParameters?: boolean;
 
+  /**
+   * Display mode for stack deployment progress.
+   *
+   * @default StackActivityProgress.Bar stack events will be displayed for
+   *   the resource currently being deployed.
+   */
+  progress?: StackActivityProgress;
+
   /**
    * Deploy even if the deployed template is identical to the one we are about to deploy.
    * @default false
@@ -267,6 +275,7 @@ export async function deployStack(options: DeployStackOptions): Promise<DeploySt
     // eslint-disable-next-line max-len
     const monitor = options.quiet ? undefined : StackActivityMonitor.withDefaultPrinter(cfn, deployName, stackArtifact, {
       resourcesTotal: (changeSetDescription.Changes ?? []).length,
+      progress: options.progress,
       changeSetCreationTime: changeSetDescription.CreationTime,
     }).start();
     debug('Execution of changeset %s on stack %s has started; waiting for the update to complete...', changeSetName, deployName);

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

@@ -16,6 +16,21 @@ export interface ResourceMetadata {
   constructPath: string;
 }
 
+/**
+ * Supported display modes for stack deployment activity
+ */
+export enum StackActivityProgress {
+  /**
+   * Displays a progress bar with only the events for the resource currently being deployed
+   */
+  BAR = 'bar',
+
+  /**
+   * Displays complete history with all CloudFormation stack events
+   */
+  EVENTS = 'events',
+}
+
 export interface WithDefaultPrinterProps {
   /**
    * Total number of resources to update
@@ -35,6 +50,16 @@ export interface WithDefaultPrinterProps {
    */
   readonly logLevel?: LogLevel;
 
+  /**
+   * Whether to display all stack events or to display only the events for the
+   * resource currently being deployed
+   *
+   * If not set, the stack history with all stack events will be displayed
+   *
+   * @default false
+   */
+  progress?: StackActivityProgress;
+
   /**
    * Whether we are on a CI system
    *
@@ -81,8 +106,9 @@ export class StackActivityMonitor {
     // need an individual check for whether we're running on CI.
     // see: https://discuss.circleci.com/t/circleci-terminal-is-a-tty-but-term-is-not-set/9965
     const fancyOutputAvailable = !isWindows && stream.isTTY && !options.ci;
+    const progress = options.progress ?? StackActivityProgress.BAR;
 
-    const printer = fancyOutputAvailable && !verbose
+    const printer = fancyOutputAvailable && !verbose && (progress === StackActivityProgress.BAR)
       ? new CurrentActivityPrinter(props)
       : new HistoryActivityPrinter(props);
 

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

@@ -12,6 +12,7 @@ import { bootstrapEnvironment2, BootstrappingParameters } from './api/bootstrap'
 import { CloudFormationDeployments } from './api/cloudformation-deployments';
 import { CloudAssembly, DefaultSelection, ExtendedStackSelection, StackCollection } from './api/cxapp/cloud-assembly';
 import { CloudExecutable } from './api/cxapp/cloud-executable';
+import { StackActivityProgress } from './api/util/cloudformation/stack-activity-monitor';
 import { printSecurityDiff, printStackDiff, RequireApproval } from './diff';
 import { data, error, highlight, print, success, warning } from './logging';
 import { deserializeStructure } from './serialize';
@@ -190,6 +191,7 @@ export class CdkToolkit {
           force: options.force,
           parameters: Object.assign({}, parameterMap['*'], parameterMap[stack.stackName]),
           usePreviousParameters: options.usePreviousParameters,
+          progress: options.progress,
           ci: options.ci,
         });
 
@@ -579,6 +581,14 @@ export interface DeployOptions {
    */
   usePreviousParameters?: boolean;
 
+  /**
+   * Display mode for stack deployment progress.
+   *
+   * @default - StackActivityProgress.Bar - stack events will be displayed for
+   *   the resource currently being deployed.
+   */
+  progress?: StackActivityProgress;
+
   /**
    * Path to file where stack outputs will be written after a successful deploy as JSON
    * @default - Outputs are not written to any file

packages/aws-cdk/lib/settings.ts

@@ -204,6 +204,7 @@ export class Settings {
       versionReporting: argv.versionReporting,
       staging: argv.staging,
       output: argv.output,
+      progress: argv.progress,
     });
   }