feat(cloudfront): import existing CloudFrontWebDistributions (#10007)

Existing distributions can already been imported with the new (experimental)
`Distribution` construct, but the functionality had never been backported to
the stable construct. This makes it slightly more discoverable for users who
are using the `CloudFrontWebDistribution` construct.

Note: Opted in the README to only update the Distribution section, as it felt
redundant to have the same README section twice for the two different classes.

fixes #5607


----

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

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

@@ -82,7 +82,7 @@ new cloudfront.Distribution(this, 'myDist', {
 });
 ```
 
-## From an HTTP endpoint
+#### From an HTTP endpoint
 
 Origins can also be created from any other HTTP endpoint, given the domain name, and optionally, other origin properties.
 
@@ -246,6 +246,18 @@ new cloudfront.Distribution(this, 'myDist', {
 });
 ```
 
+### Importing Distributions
+
+Existing distributions can be imported as well; note that like most imported constructs, an imported distribution cannot be modified.
+However, it can be used as a reference for other higher-level constructs.
+
+```ts
+const distribution = cloudfront.Distribution.fromDistributionAttributes(scope, 'ImportedDist', {
+  domainName: 'd111111abcdef8.cloudfront.net',
+  distributionId: '012345ABCDEF',
+});
+```
+
 ## CloudFrontWebDistribution API - Stable
 
 ![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)
@@ -305,7 +317,7 @@ Example:
 
 [create a distrubution with an iam certificate example](test/example.iam-cert-alias.lit.ts)
 
-#### Restrictions
+### Restrictions
 
 CloudFront supports adding restrictions to your distribution.
 

packages/@aws-cdk/aws-cloudfront/lib/web_distribution.ts

@@ -628,6 +628,27 @@ interface BehaviorWithOrigin extends Behavior {
   readonly targetOriginId: string;
 }
 
+/**
+ * Attributes used to import a Distribution.
+ *
+ * @experimental
+ */
+export interface CloudFrontWebDistributionAttributes {
+  /**
+   * The generated domain name of the Distribution, such as d111111abcdef8.cloudfront.net.
+   *
+   * @attribute
+   */
+  readonly domainName: string;
+
+  /**
+   * The distribution ID for this distribution.
+   *
+   * @attribute
+   */
+  readonly distributionId: string;
+}
+
 /**
  * Amazon CloudFront is a global content delivery network (CDN) service that securely delivers data, videos,
  * applications, and APIs to your viewers with low latency and high transfer speeds.
@@ -659,6 +680,25 @@ interface BehaviorWithOrigin extends Behavior {
  * @resource AWS::CloudFront::Distribution
  */
 export class CloudFrontWebDistribution extends cdk.Resource implements IDistribution {
+
+  /**
+   * Creates a construct that represents an external (imported) distribution.
+   */
+  public static fromDistributionAttributes(scope: cdk.Construct, id: string, attrs: CloudFrontWebDistributionAttributes): IDistribution {
+    return new class extends cdk.Resource implements IDistribution {
+      public readonly domainName: string;
+      public readonly distributionDomainName: string;
+      public readonly distributionId: string;
+
+      constructor() {
+        super(scope, id);
+        this.domainName = attrs.domainName;
+        this.distributionDomainName = attrs.domainName;
+        this.distributionId = attrs.distributionId;
+      }
+    }();
+  }
+
   /**
    * The logging bucket for this CloudFront distribution.
    * If logging is not enabled for this distribution - this property will be undefined.

packages/@aws-cdk/aws-cloudfront/test/web_distribution.test.ts

@@ -1288,4 +1288,17 @@ nodeunitShim({
       },
     },
   },
+
+  'existing distributions can be imported'(test: Test) {
+    const stack = new cdk.Stack();
+    const dist = CloudFrontWebDistribution.fromDistributionAttributes(stack, 'ImportedDist', {
+      domainName: 'd111111abcdef8.cloudfront.net',
+      distributionId: '012345ABCDEF',
+    });
+
+    test.equals(dist.distributionDomainName, 'd111111abcdef8.cloudfront.net');
+    test.equals(dist.distributionId, '012345ABCDEF');
+
+    test.done();
+  },
 });