refactor(codepipeline): change the API of cross-region replication Buckets. (#2977)

Changed the name and type of the Pipeline.crossRegionScaffold property.
Users are now supposed to pass instances of IBucket instead of just Bucket names.

BREAKING CHANGE: the Pipeline construction property crossRegionReplicationBuckets now takes values of type IBucket instead of string.
* The property Pipeline.crossRegionScaffoldStacks has been renamed to crossRegionSupport,
and its type changed from CrossRegionScaffoldStack to CrossRegionSupport.

Author: skinny85

packages/@aws-cdk/aws-codepipeline-actions/test/test.pipeline.ts

@@ -1,4 +1,4 @@
-import { expect, haveResource, haveResourceLike, not, SynthUtils } from '@aws-cdk/assert';
+import { countResources, expect, haveResource, haveResourceLike, not, SynthUtils } from '@aws-cdk/assert';
 import codebuild = require('@aws-cdk/aws-codebuild');
 import codecommit = require('@aws-cdk/aws-codecommit');
 import codepipeline = require('@aws-cdk/aws-codepipeline');
@@ -567,19 +567,19 @@ export = {
           account: pipelineAccount,
         },
       });
-      const bucket = new s3.Bucket(stack, 'MyBucket');
       const pipeline = new codepipeline.Pipeline(stack, 'MyPipeline', {
         crossRegionReplicationBuckets: {
-          'us-west-1': 'sfo-replication-bucket',
+          'us-west-1': s3.Bucket.fromBucketName(stack, 'ImportedBucket', 'sfo-replication-bucket'),
         },
       });
 
+      const sourceBucket = new s3.Bucket(stack, 'MyBucket');
       const sourceOutput = new codepipeline.Artifact('SourceOutput');
       const sourceAction = new cpactions.S3SourceAction({
         actionName: 'BucketSource',
         bucketKey: '/some/key',
         output: sourceOutput,
-        bucket,
+        bucket: sourceBucket,
       });
       pipeline.addStage({
         stageName: 'Stage1',
@@ -619,19 +619,25 @@ export = {
             "Region": "us-east-1",
             "ArtifactStore": {
               "Type": "S3",
+              "Location": "cdk-cross-region-codepipeline-replication-bucket-685c6feea5fb",
             },
           },
           {
             "Region": "us-west-1",
             "ArtifactStore": {
-              "Location": "sfo-replication-bucket",
               "Type": "S3",
+              "Location": "sfo-replication-bucket",
             },
           },
           {
             "Region": "us-west-2",
             "ArtifactStore": {
               "Type": "S3",
+              "EncryptionKey": {
+                "Type": "KMS",
+                "Id": {
+                },
+              },
             },
           },
         ],
@@ -656,18 +662,90 @@ export = {
               },
             ],
           },
-        ]
+        ],
       }));
 
-      test.equal(pipeline.crossRegionScaffolding[pipelineRegion], undefined);
-      test.equal(pipeline.crossRegionScaffolding['us-west-1'], undefined);
+      test.equal(pipeline.crossRegionSupport[pipelineRegion], undefined);
+      test.equal(pipeline.crossRegionSupport['us-west-1'], undefined);
+
+      const usEast1Support = pipeline.crossRegionSupport['us-east-1'];
+      test.notEqual(usEast1Support, undefined);
+      test.equal(usEast1Support.stack.region, 'us-east-1');
+      test.equal(usEast1Support.stack.account, pipelineAccount);
+      test.ok(usEast1Support.stack.node.id.indexOf('us-east-1') !== -1,
+        `expected '${usEast1Support.stack.node.id}' to contain 'us-east-1'`);
+
+      test.done();
+    },
+
+    'allows specifying only one of artifactBucket and crossRegionReplicationBuckets'(test: Test) {
+      const stack = new Stack();
+
+      test.throws(() => {
+        new codepipeline.Pipeline(stack, 'Pipeline', {
+          artifactBucket: new s3.Bucket(stack, 'Bucket'),
+          crossRegionReplicationBuckets: {
+            // even an empty map should trigger this validation...
+          },
+        });
+      }, /Only one of artifactBucket and crossRegionReplicationBuckets can be specified!/);
+      test.done();
+    },
+
+    'does not create a new artifact Bucket if one was provided in the cross-region Buckets for the Pipeline region'(test: Test) {
+      const pipelineRegion = 'us-west-2';
+
+      const stack = new Stack(undefined, undefined, {
+        env: {
+          region: pipelineRegion,
+        },
+      });
+      const sourceOutput = new codepipeline.Artifact();
+      new codepipeline.Pipeline(stack, 'Pipeline', {
+        crossRegionReplicationBuckets: {
+          [pipelineRegion]: new s3.Bucket(stack, 'Bucket', {
+            bucketName: PhysicalName.of('my-pipeline-bucket'),
+          })
+        },
+        stages: [
+          {
+            stageName: 'Source',
+            actions: [
+              new cpactions.CodeCommitSourceAction({
+                actionName: 'Source',
+                output: sourceOutput,
+                repository: new codecommit.Repository(stack, 'Repo', { repositoryName: 'Repo' }),
+              }),
+            ],
+          },
+          {
+            stageName: 'Build',
+            actions: [
+              new cpactions.CodeBuildAction({
+                actionName: 'Build',
+                input: sourceOutput,
+                project: new codebuild.PipelineProject(stack, 'Project'),
+              }),
+            ],
+          },
+        ],
+      });
+
+      expect(stack).to(countResources('AWS::S3::Bucket', 1));
 
-      const usEast1ScaffoldStack = pipeline.crossRegionScaffolding['us-east-1'];
-      test.notEqual(usEast1ScaffoldStack, undefined);
-      test.equal(usEast1ScaffoldStack.region, 'us-east-1');
-      test.equal(usEast1ScaffoldStack.account, pipelineAccount);
-      test.ok(usEast1ScaffoldStack.node.id.indexOf('us-east-1') !== -1,
-        `expected '${usEast1ScaffoldStack.node.id}' to contain 'us-east-1'`);
+      expect(stack).to(haveResourceLike('AWS::CodePipeline::Pipeline', {
+        "ArtifactStores": [
+          {
+            "Region": pipelineRegion,
+            "ArtifactStore": {
+              "Type": "S3",
+              "Location": {
+                "Ref": "Bucket83908E77",
+              },
+            },
+          },
+        ],
+      }));
 
       test.done();
     },

packages/@aws-cdk/aws-codepipeline/README.md

@@ -100,7 +100,9 @@ It works like this:
 const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
   // ...
   crossRegionReplicationBuckets: {
-    'us-west-1': 'my-us-west-1-replication-bucket',
+    // note that a physical name of the replication Bucket must be known at synthesis time
+    'us-west-1': s3.Bucket.fromBucketName(this, 'UsWest1ReplicationBucket',
+      'my-us-west-1-replication-bucket'),
   },
 });
 
@@ -115,22 +117,20 @@ new codepipeline_actions.CloudFormationCreateUpdateStackAction({
 This way, the `CFN_US_West_1` Action will operate in the `us-west-1` region,
 regardless of which region your Pipeline is in.
 
-If you don't provide a bucket name for a region (other than the Pipeline's region)
-that you're using for an Action with the `crossRegionReplicationBuckets` property,
-there will be a new Stack, named `aws-cdk-codepipeline-cross-region-scaffolding-<region>`,
+If you don't provide a bucket for a region (other than the Pipeline's region)
+that you're using for an Action,
+there will be a new Stack, called `<nameOfYourPipelineStack>-support-<region>`,
 defined for you, containing a replication Bucket.
-Note that you have to make sure to `cdk deploy` all of these automatically created Stacks
-before you can deploy your main Stack (the one containing your Pipeline).
-Use the `cdk ls` command to see all of the Stacks comprising your CDK application.
+This new Stack will depend on your Pipeline Stack,
+so deploying the Pipeline Stack will deploy the support Stack(s) first.
 Example:
 
 ```bash
 $ cdk ls
 MyMainStack
-aws-cdk-codepipeline-cross-region-scaffolding-us-west-1
-$ cdk deploy aws-cdk-codepipeline-cross-region-scaffolding-us-west-1
-# output of cdk deploy here...
+MyMainStack-support-us-west-1
 $ cdk deploy MyMainStack
+# output of cdk deploy here...
 ```
 
 See [the AWS docs here](https://docs.aws.amazon.com/codepipeline/latest/userguide/actions-create-cross-region.html)

packages/@aws-cdk/aws-codepipeline/lib/cross-region-scaffold-stack.ts renamed to packages/@aws-cdk/aws-codepipeline/lib/cross-region-support-stack.ts

@@ -1,12 +1,18 @@
 import s3 = require('@aws-cdk/aws-s3');
 import cdk = require('@aws-cdk/cdk');
 import crypto = require('crypto');
-import { CrossRegionScaffolding } from './pipeline';
 
 /**
- * Construction properties for {@link CrossRegionScaffoldStack}.
+ * Construction properties for {@link CrossRegionSupportStack}.
+ * This interface is private to the aws-codepipeline package.
  */
-export interface CrossRegionScaffoldStackProps {
+export interface CrossRegionSupportStackProps {
+  /**
+   * The name of the Stack the Pipeline itself belongs to.
+   * Used to generate a more friendly name for the support Stack.
+   */
+  readonly pipelineStackName: string;
+
   /**
    * The AWS region this Stack resides in.
    */
@@ -22,14 +28,15 @@ export interface CrossRegionScaffoldStackProps {
 
 /**
  * A Stack containing resources required for the cross-region CodePipeline functionality to work.
+ * This class is private to the aws-codepipeline package.
  */
-export class CrossRegionScaffoldStack extends CrossRegionScaffolding {
+export class CrossRegionSupportStack extends cdk.Stack {
   /**
    * The name of the S3 Bucket used for replicating the Pipeline's artifacts into the region.
    */
-  public readonly replicationBucketName: string;
+  public readonly replicationBucket: s3.IBucket;
 
-  constructor(scope: cdk.Construct, id: string, props: CrossRegionScaffoldStackProps) {
+  constructor(scope: cdk.Construct, id: string, props: CrossRegionSupportStackProps) {
     super(scope, id, {
       stackName: generateStackName(props),
       env: {
@@ -41,15 +48,14 @@ export class CrossRegionScaffoldStack extends CrossRegionScaffolding {
     const replicationBucketName = generateUniqueName('cdk-cross-region-codepipeline-replication-bucket-',
       props.region, props.account, false, 12);
 
-    new s3.Bucket(this, 'CrossRegionCodePipelineReplicationBucket', {
+    this.replicationBucket = new s3.Bucket(this, 'CrossRegionCodePipelineReplicationBucket', {
       bucketName: cdk.PhysicalName.of(replicationBucketName),
     });
-    this.replicationBucketName = replicationBucketName;
   }
 }
 
-function generateStackName(props: CrossRegionScaffoldStackProps): string {
-  return `aws-cdk-codepipeline-cross-region-scaffolding-${props.region}`;
+function generateStackName(props: CrossRegionSupportStackProps): string {
+  return `${props.pipelineStackName}-support-${props.region}`;
 }
 
 function generateUniqueName(baseName: string, region: string, account: string,