Skip to content

Commit ea7802b

Browse files
peterwoodworthpeterwoodworth
authored
docs(cloudfront): add migration guide to modern distribution api (#18835)
Add guide for migrating from CloudFrontWebDistribution to Distribution ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
1 parent a4387bd commit ea7802b

File tree

1 file changed

+198
-1
lines changed

1 file changed

+198
-1
lines changed

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

+198-1
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ your domain name, and provide one (or more) domain names from the certificate fo
9191

9292
The certificate must be present in the AWS Certificate Manager (ACM) service in the US East (N. Virginia) region; the certificate
9393
may either be created by ACM, or created elsewhere and imported into ACM. When a certificate is used, the distribution will support HTTPS connections
94-
from SNI only and a minimum protocol version of TLSv1.2_2021 if the '@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021' feature flag is set, and TLSv1.2_2019 otherwise.
94+
from SNI only and a minimum protocol version of TLSv1.2_2021 if the `@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021` feature flag is set, and TLSv1.2_2019 otherwise.
9595

9696
```ts
9797
// To use your own domain name in a Distribution, you must associate a certificate
@@ -539,6 +539,203 @@ const distribution = cloudfront.Distribution.fromDistributionAttributes(this, 'I
539539
});
540540
```
541541

542+
## Migrating from the original CloudFrontWebDistribution to the newer Distribution construct
543+
544+
It's possible to migrate a distribution from the original to the modern API.
545+
The changes necessary are the following:
546+
547+
### The Distribution
548+
549+
Replace `new CloudFrontWebDistribution` with `new Distribution`. Some
550+
configuration properties have been changed:
551+
552+
| Old API | New API |
553+
|--------------------------------|------------------------------------------------------------------------------------------------|
554+
| `originConfigs` | `defaultBehavior`; use `additionalBehaviors` if necessary |
555+
| `viewerCertificate` | `certificate`; use `domainNames` for aliases |
556+
| `errorConfigurations` | `errorResponses` |
557+
| `loggingConfig` | `enableLogging`; configure with `logBucket` `logFilePrefix` and `logIncludesCookies` |
558+
| `viewerProtocolPolicy` | removed; set on each behavior instead. default changed from `REDIRECT_TO_HTTPS` to `ALLOW_ALL` |
559+
560+
After switching constructs, you need to maintain the same logical ID for the underlying [CfnDistribution](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-cloudfront.CfnDistribution.html) if you wish to avoid the deletion and recreation of your distribution.
561+
To do this, use [escape hatches](https://docs.aws.amazon.com/cdk/v2/guide/cfn_layer.html) to override the logical ID created by the new Distribution construct with the logical ID created by the old construct.
562+
563+
Example:
564+
565+
```ts
566+
declare const sourceBucket: s3.Bucket;
567+
568+
const myDistribution = new cloudfront.Distribution(this, 'MyCfWebDistribution', {
569+
defaultBehavior: {
570+
origin: new origins.S3Origin(sourceBucket),
571+
},
572+
});
573+
const cfnDistribution = myDistribution.node.defaultChild as cloudfront.CfnDistribution;
574+
cfnDistribution.overrideLogicalId('MyDistributionCFDistribution3H55TI9Q');
575+
```
576+
577+
### Behaviors
578+
579+
The modern API makes use of the [CloudFront Origins](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront_origins-readme.html) module to easily configure your origin. Replace your origin configuration with the relevant CloudFront Origins class. For example, here's a behavior with an S3 origin:
580+
581+
```ts
582+
declare const sourceBucket: s3.Bucket;
583+
declare const oai: cloudfront.OriginAccessIdentity;
584+
585+
new cloudfront.CloudFrontWebDistribution(this, 'MyCfWebDistribution', {
586+
originConfigs: [
587+
{
588+
s3OriginSource: {
589+
s3BucketSource: sourceBucket,
590+
originAccessIdentity: oai,
591+
},
592+
behaviors : [ {isDefaultBehavior: true}],
593+
},
594+
],
595+
});
596+
```
597+
598+
Becomes:
599+
600+
```ts
601+
declare const sourceBucket: s3.Bucket;
602+
603+
const distribution = new cloudfront.Distribution(this, 'MyCfWebDistribution', {
604+
defaultBehavior: {
605+
origin: new origins.S3Origin(sourceBucket) // This class automatically creates an Origin Access Identity
606+
},
607+
});
608+
```
609+
610+
In the original API all behaviors are defined in the `originConfigs` property. The new API is optimized for a single origin and behavior, so the default behavior and additional behaviors will be defined separately.
611+
612+
```ts
613+
declare const sourceBucket: s3.Bucket;
614+
declare const oai: cloudfront.OriginAccessIdentity;
615+
616+
new cloudfront.CloudFrontWebDistribution(this, 'MyCfWebDistribution', {
617+
originConfigs: [
618+
{
619+
s3OriginSource: {
620+
s3BucketSource: sourceBucket,
621+
originAccessIdentity: oai,
622+
},
623+
behaviors: [ {isDefaultBehavior: true}],
624+
},
625+
{
626+
customOriginSource: {
627+
domainName: 'MYALIAS',
628+
},
629+
behaviors: [{ pathPattern: '/somewhere' }]
630+
}
631+
],
632+
});
633+
```
634+
635+
Becomes:
636+
637+
```ts
638+
declare const sourceBucket: s3.Bucket;
639+
640+
const distribution = new cloudfront.Distribution(this, 'MyCfWebDistribution', {
641+
defaultBehavior: {
642+
origin: new origins.S3Origin(sourceBucket) // This class automatically creates an Origin Access Identity
643+
},
644+
additionalBehaviors: {
645+
'/somewhere': {
646+
origin: new origins.HttpOrigin('MYALIAS'),
647+
}
648+
}
649+
});
650+
```
651+
652+
### Certificates
653+
654+
If you are using an ACM certificate, you can pass the certificate directly to the `certificate` prop.
655+
Any aliases used before in the `ViewerCertificate` class should be passed in to the `domainNames` prop in the modern API.
656+
657+
```ts
658+
import * as acm from '@aws-cdk/aws-certificatemanager';
659+
declare const certificate: acm.Certificate;
660+
declare const sourceBucket: s3.Bucket;
661+
662+
const viewerCertificate = cloudfront.ViewerCertificate.fromAcmCertificate(certificate, {
663+
aliases: ['MYALIAS'],
664+
});
665+
666+
new cloudfront.CloudFrontWebDistribution(this, 'MyCfWebDistribution', {
667+
originConfigs: [
668+
{
669+
s3OriginSource: {
670+
s3BucketSource: sourceBucket,
671+
},
672+
behaviors : [ {isDefaultBehavior: true} ],
673+
},
674+
],
675+
viewerCertificate: viewerCertificate,
676+
});
677+
```
678+
679+
Becomes:
680+
681+
```ts
682+
import * as acm from '@aws-cdk/aws-certificatemanager';
683+
declare const certificate: acm.Certificate;
684+
declare const sourceBucket: s3.Bucket;
685+
686+
const distribution = new cloudfront.Distribution(this, 'MyCfWebDistribution', {
687+
defaultBehavior: {
688+
origin: new origins.S3Origin(sourceBucket),
689+
},
690+
domainNames: ['MYALIAS'],
691+
certificate: certificate,
692+
});
693+
```
694+
695+
IAM certificates aren't directly supported by the new API, but can be easily configured through [escape hatches](https://docs.aws.amazon.com/cdk/v2/guide/cfn_layer.html)
696+
697+
```ts
698+
declare const sourceBucket: s3.Bucket;
699+
const viewerCertificate = cloudfront.ViewerCertificate.fromIamCertificate('MYIAMROLEIDENTIFIER', {
700+
aliases: ['MYALIAS'],
701+
});
702+
703+
new cloudfront.CloudFrontWebDistribution(this, 'MyCfWebDistribution', {
704+
originConfigs: [
705+
{
706+
s3OriginSource: {
707+
s3BucketSource: sourceBucket,
708+
},
709+
behaviors : [ {isDefaultBehavior: true} ],
710+
},
711+
],
712+
viewerCertificate: viewerCertificate,
713+
});
714+
```
715+
716+
Becomes:
717+
718+
```ts
719+
declare const sourceBucket: s3.Bucket;
720+
const distribution = new cloudfront.Distribution(this, 'MyCfWebDistribution', {
721+
defaultBehavior: {
722+
origin: new origins.S3Origin(sourceBucket),
723+
},
724+
domainNames: ['MYALIAS'],
725+
});
726+
727+
const cfnDistribution = distribution.node.defaultChild as cloudfront.CfnDistribution;
728+
729+
cfnDistribution.addPropertyOverride('ViewerCertificate.IamCertificateId', 'MYIAMROLEIDENTIFIER');
730+
cfnDistribution.addPropertyOverride('ViewerCertificate.SslSupportMethod', 'sni-only');
731+
```
732+
733+
### Other changes
734+
735+
A number of default settings have changed on the new API when creating a new distribution, behavior, and origin.
736+
After making the major changes needed for the migration, run `cdk diff` to see what settings have changed.
737+
If no changes are desired during migration, you will at the least be able to use [escape hatches](https://docs.aws.amazon.com/cdk/v2/guide/cfn_layer.html) to override what the CDK synthesizes, if you can't change the properties directly.
738+
542739
## CloudFrontWebDistribution API
543740

544741
> The `CloudFrontWebDistribution` construct is the original construct written for working with CloudFront distributions.

0 commit comments

Comments
 (0)