refactor(codepipeline): change the API of cross-region replication Bu…

…ckets. (#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.

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 → 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,