feat(pipelines): expose crossRegionReplicationBuckets

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

@@ -1232,6 +1232,49 @@ and orphan the old bucket. You should manually delete the orphaned bucket
 after you are sure you have redeployed all CDK applications and there are no
 more references to the old asset bucket.
 
+## Considerations around Running at Scale
+
+If you are planning to run pipelines for more than a hundred repos
+deploying across multiple regions, then you will want to consider reusing
+both artifacts buckets and cross-region replication buckets.
+
+In a situation like this, you will want to have a separate CDK app / dedicatd repo which creates
+and managed the buckets which will be shared by the pipelines of all your other apps.
+Note that this app must NOT be using the shared buckets because of chicken & egg issues.
+
+The following code assumes you have created and are managing your buckets in the aforementioned
+separate cdk repo and are just importing them for use in one of your (many) pipelines.
+
+```typescript
+let sharedArtifactBucketArn: string;
+let sharedArtifactKeyArn: string;
+
+let sharedXRegionUsWest2BucketArn: string;
+let sharedXRegionUsWest2KeyArn: string;
+
+const artifactBucket = s3.Bucket.fromBucketAttributes(scope, 'bucketArn', {
+  bucketArn: sharedArtifactBucketArn,
+  encryptionKey: kms.Key.fromKeyArn(scope, 'keyArn', sharedArtifactKeyArn),
+});
+
+const usWest2Bucket = s3.Bucket.fromBucketAttributes(scope, 'us-west-2Bucket', {
+  bucketArn: sharedXRegionUsWest2BucketArn,
+  encryptionKey: kms.Key.fromKeyArn(scope, 'keyArn', sharedXRegionUsWest2KeyArn),
+});
+
+const crossRegionReplicationBuckets: Record<[key: string]: s3.IBucket> = {
+  'us-west-2': usWest2Bucket,
+  // Support for additional regions.
+}
+
+let otherProps: pipelines.CodePipelineProps;
+const pipeline = new pipelines.CodePipeline(this, 'Pipeline', {
+  ...otherProps,
+  // Use shared buckets.
+  artifactBucket,
+  crossRegionReplicationBuckets,
+});
+```
 ## Context Lookups
 
 You might be using CDK constructs that need to look up [runtime

packages/aws-cdk-lib/pipelines/lib/codepipeline/codepipeline.ts

@@ -244,6 +244,19 @@ export interface CodePipelineProps {
    * @default - A new S3 bucket will be created.
    */
   readonly artifactBucket?: s3.IBucket;
+
+  /**
+   * A map of region to S3 bucket name used for cross-region CodePipeline.
+   * For every Action that you specify targeting a different region than the Pipeline itself,
+   * if you don't provide an explicit Bucket for that region using this property,
+   * the construct will automatically create a Stack containing an S3 Bucket in that region.
+   * 
+   * Passed directly through to the {@link cp.Pipeline}.
+   *
+   * @default - None.
+   */
+
+  readonly crossRegionReplicationBuckets?: { [region: string]: s3.IBucket };
 }
 
 /**
@@ -440,6 +453,9 @@ export class CodePipeline extends PipelineBase {
       if (this.props.enableKeyRotation !== undefined) {
         throw new Error('Cannot set \'enableKeyRotation\' if an existing CodePipeline is given using \'codePipeline\'');
       }
+      if (this.props.crossRegionReplicationBuckets !== undefined) {
+        throw new Error('Cannot set \'crossRegionReplicationBuckets\' if an existing CodePipeline is given using \'codePipeline\'');
+      }
       if (this.props.reuseCrossRegionSupportStacks !== undefined) {
         throw new Error('Cannot set \'reuseCrossRegionSupportStacks\' if an existing CodePipeline is given using \'codePipeline\'');
       }
@@ -455,6 +471,7 @@ export class CodePipeline extends PipelineBase {
       this._pipeline = new cp.Pipeline(this, 'Pipeline', {
         pipelineName: this.props.pipelineName,
         crossAccountKeys: this.props.crossAccountKeys ?? false,
+        crossRegionReplicationBuckets: this.props.crossRegionReplicationBuckets,
         reuseCrossRegionSupportStacks: this.props.reuseCrossRegionSupportStacks,
         // This is necessary to make self-mutation work (deployments are guaranteed
         // to happen only after the builds of the latest pipeline definition).

packages/aws-cdk-lib/pipelines/test/codepipeline/codepipeline-existing.test.ts

@@ -46,4 +46,18 @@ describeDeprecated('codepipeline existing', () => {
       });
     }).toThrow("Cannot set 'enableKeyRotation' if an existing CodePipeline is given using 'codePipeline'");
   });
+
+  test('Does not allow setting crossRegionReplicationBuckets if an existing CodePipeline is given', () => {
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'PipelineStack');
+    const existingCodePipeline = new codePipeline.Pipeline(stack, 'CustomCodePipeline');
+
+    expect(() => {
+      new cdkp.CdkPipeline(stack, 'CDKPipeline', {
+        crossRegionReplicationBuckets: {}, // Even the empty set is forbidden.
+        codePipeline: existingCodePipeline,
+        cloudAssemblyArtifact: new codePipeline.Artifact(),
+      });
+    }).toThrow("Cannot set 'crossRegionReplicationBuckets' if an existing CodePipeline is given using 'codePipeline'");
+  });
 });