feat(pipelines): Add feature to display all changesets for stage before manual approval step + added postPrepare Step

.vscode/launch.json

@@ -4,6 +4,7 @@
   // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
+
     {
       // Has convenient settings for attaching to a NodeJS process for debugging purposes
       // that are NOT the default and otherwise every developers has to configure for

packages/@aws-cdk-testing/framework-integ/test/pipelines/test/integ.newpipeline.ts

@@ -57,4 +57,4 @@ const app = new App({
   },
 });
 new PipelineStack(app, 'PipelineStack');
-app.synth();
+app.synth();

packages/@aws-cdk-testing/framework-integ/test/pipelines/test/integ.newpipeline_with_allPrepareNodesFirst.ts

@@ -0,0 +1,75 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+/// !cdk-integ PipelineStack pragma:set-context:@aws-cdk/core:newStyleStackSynthesis=true
+import { App, Stack, StackProps, Stage, StageProps } from 'aws-cdk-lib';
+import * as sqs from 'aws-cdk-lib/aws-sqs';
+import * as pipelines from 'aws-cdk-lib/pipelines';
+import { Construct } from 'constructs';
+
+class PipelineStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const pipeline = new pipelines.CodePipeline(this, 'Pipeline', {
+      synth: new pipelines.ShellStep('Synth', {
+        input: pipelines.CodePipelineSource.gitHub(
+          'rix0rrr/cdk-pipelines-demo',
+          'main',
+        ),
+        commands: ['npm ci', 'npm run build', 'npx cdk synth'],
+      }),
+      allPrepareNodesFirst: true,
+    });
+
+    pipeline.addStage(new AppStage(this, 'Beta'), {
+    });
+
+    const group = pipeline.addWave('Wave1');
+    group.addStage(new AppStage(this, 'Prod1'));
+    group.addStage(new AppStage(this, 'Prod2'));
+
+    const group2 = pipeline.addWave('Wave2');
+    group2.addStage(new AppStage2(this, 'Prod3'));
+    group2.addStage(new AppStage3(this, 'Prod4'));
+  }
+}
+
+class AppStage extends Stage {
+  constructor(scope: Construct, id: string, props?: StageProps) {
+    super(scope, id, props);
+
+    const stack1 = new Stack(this, 'Stack1');
+    const queue1 = new sqs.Queue(stack1, 'Queue');
+
+    const stack2 = new Stack(this, 'Stack2');
+    new sqs.Queue(stack2, 'OtherQueue', {
+      deadLetterQueue: {
+        queue: queue1,
+        maxReceiveCount: 5,
+      },
+    });
+  }
+}
+
+class AppStage2 extends Stage {
+  constructor(scope: Construct, id: string, props?: StageProps) {
+    super(scope, id, props);
+
+    new Stack(this, 'Stack1');
+  }
+}
+
+class AppStage3 extends Stage {
+  constructor(scope: Construct, id: string, props?: StageProps) {
+    super(scope, id, props);
+
+    new Stack(this, 'Stack2');
+  }
+}
+
+const app = new App({
+  context: {
+    '@aws-cdk/core:newStyleStackSynthesis': '1',
+  },
+});
+new PipelineStack(app, 'PipelineWithAllPrepareNodesFirstStack');
+app.synth();

packages/@aws-cdk-testing/framework-integ/test/pipelines/test/integ.newpipeline_with_postPrepare.ts

@@ -0,0 +1,79 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+/// !cdk-integ PipelineStack pragma:set-context:@aws-cdk/core:newStyleStackSynthesis=true
+import { App, Stack, StackProps, Stage, StageProps } from 'aws-cdk-lib';
+import * as sqs from 'aws-cdk-lib/aws-sqs';
+import * as pipelines from 'aws-cdk-lib/pipelines';
+import { Construct } from 'constructs';
+
+class PipelineStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const pipeline = new pipelines.CodePipeline(this, 'PipelineWithPostPrepare', {
+      synth: new pipelines.ShellStep('Synth', {
+        input: pipelines.CodePipelineSource.gitHub(
+          'rix0rrr/cdk-pipelines-demo',
+          'main',
+        ),
+        commands: ['npm ci', 'npm run build', 'npx cdk synth'],
+      }),
+      allPrepareNodesFirst: true,
+    });
+
+    pipeline.addStage(new AppStage(this, 'Beta'), {
+      postPrepare: [new pipelines.ManualApprovalStep('Approval0')],
+    });
+
+    const group = pipeline.addWave('Wave1', {
+
+      postPrepare: [new pipelines.ManualApprovalStep('Approval1')],
+    });
+    group.addStage(new AppStage(this, 'Prod1'));
+    group.addStage(new AppStage(this, 'Prod2'));
+
+    const group2 = pipeline.addWave('Wave2', { postPrepare: [new pipelines.ManualApprovalStep('Approval2')] });
+    group2.addStage(new AppStage2(this, 'Prod3'));
+    group2.addStage(new AppStage3(this, 'Prod4'));
+  }
+}
+
+class AppStage extends Stage {
+  constructor(scope: Construct, id: string, props?: StageProps) {
+    super(scope, id, props);
+
+    const stack1 = new Stack(this, 'Stack1');
+    const queue1 = new sqs.Queue(stack1, 'Queue');
+
+    const stack2 = new Stack(this, 'Stack2');
+    new sqs.Queue(stack2, 'OtherQueue', {
+      deadLetterQueue: {
+        queue: queue1,
+        maxReceiveCount: 5,
+      },
+    });
+  }
+}
+
+class AppStage2 extends Stage {
+  constructor(scope: Construct, id: string, props?: StageProps) {
+    super(scope, id, props);
+
+    new Stack(this, 'Stack1');
+  }
+}
+
+class AppStage3 extends Stage {
+  constructor(scope: Construct, id: string, props?: StageProps) {
+    super(scope, id, props);
+
+    new Stack(this, 'Stack2');
+  }
+}
+
+const app = new App({
+  context: {
+    '@aws-cdk/core:newStyleStackSynthesis': '1',
+  },
+});
+new PipelineStack(app, 'PipelineWithPostPrepareStack');
+app.synth();

packages/aws-cdk-lib/pipelines/README.md

@@ -1,6 +1,5 @@
 # CDK Pipelines
 
-
 A construct library for painless Continuous Delivery of CDK applications.
 
 CDK Pipelines is an *opinionated construct library*. It is purpose-built to
@@ -162,9 +161,9 @@ has been bootstrapped (see below), and then execute deploying the
 Run the following commands to get the pipeline going:
 
 ```console
-$ git commit -a
-$ git push
-$ cdk deploy PipelineStack
+git commit -a
+git push
+cdk deploy PipelineStack
 ```
 
 Administrative permissions to the account are only necessary up until
@@ -565,6 +564,38 @@ class PipelineStack extends Stack {
 }
 ```
 
+#### Deploying with all change sets at first
+
+Deployment is done by default with `CodePipeline` engine using change sets,
+i.e. to first create a change set and then execute it. This allows you to inject
+steps that inspect the change set and approve or reject it, but failed deployments
+are not retryable and creation of the change set costs time. The change sets tough are
+being sorted within the pipeline by its dependencies. This means that some of the change set
+might not be at the top level of a stage. Therefore there is the possibility to define, that
+every change set is set as the first action (all in parallel)
+
+The creation of change sets at the top level can be switched on by setting `allPrepareNodesFirst: true`.
+`useChangeSets` needs to be activated in order to use this feature.
+
+```ts
+declare const synth: pipelines.ShellStep;
+
+class PipelineStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const pipeline = new pipelines.CodePipeline(this, 'Pipeline', {
+      synth,
+
+      allPrepareNodesFirst: true,
+    });
+  }
+}
+```
+
+It is further possible to add Steps in between the change sets and the deploy nodes (e.g. a manual approval step). This allows inspecting all change sets before deploying the stacks
+in the desired order.
+
 ### Validation
 
 Every `addStage()` and `addWave()` command takes additional options. As part of these options,
@@ -1608,7 +1639,7 @@ $ env CDK_NEW_BOOTSTRAP=1 npx cdk bootstrap \
 ```
 
 - Update all impacted stacks in the pipeline to use this new qualifier.
-See https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html for more info.
+See <https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html> for more info.
 
 ```ts
 new Stack(this, 'MyStack', {

packages/aws-cdk-lib/pipelines/lib/blueprint/stack-deployment.ts

@@ -1,9 +1,9 @@
 import * as path from 'path';
 import * as cxapi from '../../../cx-api';
-import { AssetType } from './asset-type';
-import { Step } from './step';
 import { AssetManifestReader, DockerImageManifestEntry, FileManifestEntry } from '../private/asset-manifest';
 import { isAssetManifest } from '../private/cloud-assembly-internals';
+import { AssetType } from './asset-type';
+import { Step } from './step';
 
 /**
  * Properties for a `StackDeployment`
@@ -91,11 +91,14 @@ export class StackDeployment {
   /**
    * Build a `StackDeployment` from a Stack Artifact in a Cloud Assembly.
    */
-  public static fromArtifact(stackArtifact: cxapi.CloudFormationStackArtifact): StackDeployment {
+  public static fromArtifact(
+    stackArtifact: cxapi.CloudFormationStackArtifact,
+  ): StackDeployment {
     const artRegion = stackArtifact.environment.region;
     const region = artRegion === cxapi.UNKNOWN_REGION ? undefined : artRegion;
     const artAccount = stackArtifact.environment.account;
-    const account = artAccount === cxapi.UNKNOWN_ACCOUNT ? undefined : artAccount;
+    const account =
+      artAccount === cxapi.UNKNOWN_ACCOUNT ? undefined : artAccount;
 
     return new StackDeployment({
       account,
@@ -104,7 +107,10 @@ export class StackDeployment {
       stackArtifactId: stackArtifact.id,
       constructPath: stackArtifact.hierarchicalId,
       stackName: stackArtifact.stackName,
-      absoluteTemplatePath: path.join(stackArtifact.assembly.directory, stackArtifact.templateFile),
+      absoluteTemplatePath: path.join(
+        stackArtifact.assembly.directory,
+        stackArtifact.templateFile,
+      ),
       assumeRoleArn: stackArtifact.assumeRoleArn,
       executionRoleArn: stackArtifact.cloudFormationExecutionRoleArn,
       assets: extractStackAssets(stackArtifact),
@@ -206,6 +212,12 @@ export class StackDeployment {
    */
   public readonly post: Step[] = [];
 
+  /**
+   * Additional steps to run after all of the prepare-nodes in the stage
+   */
+
+  public readonly postPrepare: Step[] = [];
+
   private constructor(props: StackDeploymentProps) {
     this.stackArtifactId = props.stackArtifactId;
     this.constructPath = props.constructPath;
@@ -216,7 +228,9 @@ export class StackDeployment {
     this.executionRoleArn = props.executionRoleArn;
     this.stackName = props.stackName;
     this.absoluteTemplatePath = props.absoluteTemplatePath;
-    this.templateUrl = props.templateS3Uri ? s3UrlFromUri(props.templateS3Uri, props.region) : undefined;
+    this.templateUrl = props.templateS3Uri
+      ? s3UrlFromUri(props.templateS3Uri, props.region)
+      : undefined;
 
     this.assets = new Array<StackAsset>();
 
@@ -242,10 +256,16 @@ export class StackDeployment {
    * @param changeSet steps executed after stack.prepare and before stack.deploy
    * @param post steps executed after stack.deploy
    */
-  public addStackSteps(pre: Step[], changeSet: Step[], post: Step[]) {
+  public addStackSteps(
+    pre: Step[],
+    changeSet: Step[],
+    post: Step[],
+    postPrepare: Step[],
+  ) {
     this.pre.push(...pre);
     this.changeSet.push(...changeSet);
     this.post.push(...post);
+    this.postPrepare.push(...postPrepare);
   }
 }