@aws-cdk/aws-cloudfront

Amazon CloudFront Construct Library

---

Features	Stability
CFN Resources
Higher level constructs for Distribution
Higher level constructs for CloudFrontWebDistribution

CFN Resources: All classes with the Cfn prefix in this module (CFN Resources) are always stable and safe to use.

Developer Preview: Higher level constructs in this module that are marked as developer preview have completed their phase of active development and are looking for adoption and feedback. While the same caveats around non-backward compatible as Experimental constructs apply, they will undergo fewer breaking changes. Just as with Experimental constructs, these are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes.

Stable: Higher level constructs in this module that are marked stable will not undergo any breaking changes. They will strictly follow the Semantic Versioning model.

---

Amazon CloudFront is a web service that speeds up distribution of your static and dynamic web content, such as .html, .css, .js, and image files, to your users. CloudFront delivers your content through a worldwide network of data centers called edge locations. When a user requests content that you're serving with CloudFront, the user is routed to the edge location that provides the lowest latency, so that content is delivered with the best possible performance.

Distribution API - Developer Preview

The Distribution API is currently being built to replace the existing CloudFrontWebDistribution API. The Distribution API is optimized for the most common use cases of CloudFront distributions (e.g., single origin and behavior, few customizations) while still providing the ability for more advanced use cases. The API focuses on simplicity for the common use cases, and convenience methods for creating the behaviors and origins necessary for more complex use cases.

Creating a distribution

CloudFront distributions deliver your content from one or more origins; an origin is the location where you store the original version of your content. Origins can be created from S3 buckets or a custom origin (HTTP server). Constructs to define origins are in the @aws-cdk/aws-cloudfront-origins module.

Each distribution has a default behavior which applies to all requests to that distribution, and routes requests to a primary origin. Additional behaviors may be specified for an origin with a given URL path pattern. Behaviors allow routing with multiple origins, controlling which HTTP methods to support, whether to require users to use HTTPS, and what query strings or cookies to forward to your origin, among other settings.

From an S3 Bucket

An S3 bucket can be added as an origin. If the bucket is configured as a website endpoint, the distribution can use S3 redirects and S3 custom error documents.

import * as cloudfront from '@aws-cdk/aws-cloudfront';
import * as origins from '@aws-cdk/aws-cloudfront-origins';

// Creates a distribution for a S3 bucket.
const myBucket = new s3.Bucket(this, 'myBucket');
new cloudfront.Distribution(this, 'myDist', {
  defaultBehavior: { origin: new origins.S3Origin(myBucket) },
});

The above will treat the bucket differently based on if IBucket.isWebsite is set or not. If the bucket is configured as a website, the bucket is treated as an HTTP origin, and the built-in S3 redirects and error pages can be used. Otherwise, the bucket is handled as a bucket origin and CloudFront's redirect and error handling will be used. In the latter case, the Origin wil create an origin access identity and grant it access to the underlying bucket. This can be used in conjunction with a bucket that is not public to require that your users access your content using CloudFront URLs and not S3 URLs directly.

ELBv2 Load Balancer

An Elastic Load Balancing (ELB) v2 load balancer may be used as an origin. In order for a load balancer to serve as an origin, it must be publicly accessible (internetFacing is true). Both Application and Network load balancers are supported.

import * as ec2 from '@aws-cdk/aws-ec2';
import * as elbv2 from '@aws-cdk/aws-elasticloadbalancingv2';

const vpc = new ec2.Vpc(...);
// Create an application load balancer in a VPC. 'internetFacing' must be 'true'
// for CloudFront to access the load balancer and use it as an origin.
const lb = new elbv2.ApplicationLoadBalancer(this, 'LB', {
  vpc,
  internetFacing: true
});
new cloudfront.Distribution(this, 'myDist', {
  defaultBehavior: { origin: new origins.LoadBalancerV2Origin(lb) },
});

From an HTTP endpoint

Origins can also be created from any other HTTP endpoint, given the domain name, and optionally, other origin properties.

new cloudfront.Distribution(this, 'myDist', {
  defaultBehavior: { origin: new origins.HttpOrigin('www.example.com') },
});

Domain Names and Certificates

When you create a distribution, CloudFront assigns a domain name for the distribution, for example: d111111abcdef8.cloudfront.net; this value can be retrieved from distribution.distributionDomainName. CloudFront distributions use a default certificate (*.cloudfront.net) to support HTTPS by default. If you want to use your own domain name, such as www.example.com, you must associate a certificate with your distribution that contains your domain name, and provide one (or more) domain names from the certificate for the distribution.

The certificate must be present in the AWS Certificate Manager (ACM) service in the US East (N. Virginia) region; the certificate may either be created by ACM, or created elsewhere and imported into ACM. When a certificate is used, the distribution will support HTTPS connections from SNI only and a minimum protocol version of TLSv1.2_2019.

const myCertificate = new acm.DnsValidatedCertificate(this, 'mySiteCert', {
  domainName: 'www.example.com',
  hostedZone,
});
new cloudfront.Distribution(this, 'myDist', {
  defaultBehavior: { origin: new origins.S3Origin(myBucket) },
  domainNames: ['www.example.com'],
  certificate: myCertificate,
});

Multiple Behaviors & Origins

Each distribution has a default behavior which applies to all requests to that distribution; additional behaviors may be specified for a given URL path pattern. Behaviors allow routing with multiple origins, controlling which HTTP methods to support, whether to require users to use HTTPS, and what query strings or cookies to forward to your origin, among others.

The properties of the default behavior can be adjusted as part of the distribution creation. The following example shows configuring the HTTP methods and viewer protocol policy of the cache.

const myWebDistribution = new cloudfront.Distribution(this, 'myDist', {
  defaultBehavior: {
    origin: new origins.S3Origin(myBucket),
    allowedMethods: AllowedMethods.ALLOW_ALL,
    viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
  }
});

Additional behaviors can be specified at creation, or added after the initial creation. Each additional behavior is associated with an origin, and enable customization for a specific set of resources based on a URL path pattern. For example, we can add a behavior to myWebDistribution to override the default viewer protocol policy for all of the images.

myWebDistribution.addBehavior('/images/*.jpg', new origins.S3Origin(myBucket), {
  viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
});

These behaviors can also be specified at distribution creation time.

const bucketOrigin = new origins.S3Origin(myBucket);
new cloudfront.Distribution(this, 'myDist', {
  defaultBehavior: {
    origin: bucketOrigin,
    allowedMethods: AllowedMethods.ALLOW_ALL,
    viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
  },
  additionalBehaviors: {
    '/images/*.jpg': {
      origin: bucketOrigin,
      viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
    },
  },
});

Customizing Cache Keys and TTLs with Cache Policies

You can use a cache policy to improve your cache hit ratio by controlling the values (URL query strings, HTTP headers, and cookies) that are included in the cache key, and/or adjusting how long items remain in the cache via the time-to-live (TTL) settings. CloudFront provides some predefined cache policies, known as managed policies, for common use cases. You can use these managed policies, or you can create your own cache policy that’s specific to your needs. See https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/controlling-the-cache-key.html for more details.

// Using an existing cache policy
new cloudfront.Distribution(this, 'myDistManagedPolicy', {
  defaultBehavior: {
    origin: bucketOrigin,
    cachePolicy: cloudfront.CachePolicy.CACHING_OPTIMIZED,
  },
});

// Creating a custom cache policy  -- all parameters optional
const myCachePolicy = new cloudfront.CachePolicy(this, 'myCachePolicy', {
  cachePolicyName: 'MyPolicy',
  comment: 'A default policy',
  defaultTtl: Duration.days(2),
  minTtl: Duration.minutes(1),
  maxTtl: Duration.days(10),
  cookieBehavior: cloudfront.CacheCookieBehavior.all(),
  headerBehavior: cloudfront.CacheHeaderBehavior.allowList('X-CustomHeader'),
  queryStringBehavior: cloudfront.CacheQueryStringBehavior.denyList('username'),
  enableAcceptEncodingGzip: true,
  enableAcceptEncodingBrotli: true,
});
new cloudfront.Distribution(this, 'myDistCustomPolicy', {
  defaultBehavior: {
    origin: bucketOrigin,
    cachePolicy: myCachePolicy,
  },
});

Customizing Origin Requests with Origin Request Policies

When CloudFront makes a request to an origin, the URL path, request body (if present), and a few standard headers are included. Other information from the viewer request, such as URL query strings, HTTP headers, and cookies, is not included in the origin request by default. You can use an origin request policy to control the information that’s included in an origin request. CloudFront provides some predefined origin request policies, known as managed policies, for common use cases. You can use these managed policies, or you can create your own origin request policy that’s specific to your needs. See https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/controlling-origin-requests.html for more details.

// Using an existing origin request policy
new cloudfront.Distribution(this, 'myDistManagedPolicy', {
  defaultBehavior: {
    origin: bucketOrigin,
    originRequestPolicy: cloudfront.OriginRequestPolicy.CORS_S3_ORIGIN,
  },
});
// Creating a custom origin request policy -- all parameters optional
const myOriginRequestPolicy = new cloudfront.OriginRequestPolicy(stack, 'OriginRequestPolicy', {
  originRequestPolicyName: 'MyPolicy',
  comment: 'A default policy',
  cookieBehavior: cloudfront.OriginRequestCookieBehavior.none(),
  headerBehavior: cloudfront.OriginRequestHeaderBehavior.all('CloudFront-Is-Android-Viewer'),
  queryStringBehavior: cloudfront.OriginRequestQueryStringBehavior.allowList('username'),
});
new cloudfront.Distribution(this, 'myDistCustomPolicy', {
  defaultBehavior: {
    origin: bucketOrigin,
    cachePolicy: myCachePolicy,
    originRequestPolicy: myOriginRequestPolicy,
  },
});

Lambda@Edge

Lambda@Edge is an extension of AWS Lambda, a compute service that lets you execute functions that customize the content that CloudFront delivers. You can author Node.js or Python functions in the US East (N. Virginia) region, and then execute them in AWS locations globally that are closer to the viewer, without provisioning or managing servers. Lambda@Edge functions are associated with a specific behavior and event type. Lambda@Edge can be used rewrite URLs, alter responses based on headers or cookies, or authorize requests based on headers or authorization tokens.

The following shows a Lambda@Edge function added to the default behavior and triggered on every request:

const myFunc = new cloudfront.experimental.EdgeFunction(this, 'MyFunction', {
  runtime: lambda.Runtime.NODEJS_10_X,
  handler: 'index.handler',
  code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
});
new cloudfront.Distribution(this, 'myDist', {
  defaultBehavior: {
    origin: new origins.S3Origin(myBucket),
    edgeLambdas: [
      {
        functionVersion: myFunc.currentVersion,
        eventType: cloudfront.LambdaEdgeEventType.VIEWER_REQUEST,
      }
    ],
  },
});

Note: Lambda@Edge functions must be created in the us-east-1 region, regardless of the region of the CloudFront distribution and stack. To make it easier to request functions for Lambda@Edge, the EdgeFunction construct can be used. The EdgeFunction construct will automatically request a function in us-east-1, regardless of the region of the current stack. EdgeFunction has the same interface as Function and can be created and used interchangably.

If the stack is in us-east-1, a "normal" lambda.Function can be used instead of an EdgeFunction.

const myFunc = new lambda.Function(this, 'MyFunction', {
  runtime: lambda.Runtime.NODEJS_10_X,
  handler: 'index.handler',
  code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
});

Lambda@Edge functions can also be associated with additional behaviors, either at or after Distribution creation time.

// assigning at Distribution creation
const myOrigin = new origins.S3Origin(myBucket);
new cloudfront.Distribution(this, 'myDist', {
  defaultBehavior: { origin: myOrigin },
  additionalBehaviors: {
    'images/*': {
      origin: myOrigin,
      edgeLambdas: [
        {
          functionVersion: myFunc.currentVersion,
          eventType: cloudfront.LambdaEdgeEventType.ORIGIN_REQUEST,
          includeBody: true, // Optional - defaults to false
        },
      ],
    },
  },
});

// assigning after creation
myDistribution.addBehavior('images/*', myOrigin, {
  edgeLambdas: [
    {
      functionVersion: myFunc.currentVersion,
      eventType: cloudfront.LambdaEdgeEventType.VIEWER_RESPONSE,
    },
  ],
});

Adding an existing Lambda@Edge function created in a different stack to a CloudFront distribution.

const functionVersion = lambda.Version.fromVersionArn(this, 'Version', 'arn:aws:lambda:us-east-1:123456789012:function:functionName:1');

new cloudfront.Distribution(this, 'distro', {
  defaultBehavior: {
    origin: new origins.S3Origin(s3Bucket),
    edgeLambdas: [
       {
         functionVersion,
         eventType: cloudfront.LambdaEdgeEventType.VIEWER_REQUEST
       },
    ],
  },
});

Logging

You can configure CloudFront to create log files that contain detailed information about every user request that CloudFront receives. The logs can go to either an existing bucket, or a bucket will be created for you.

// Simplest form - creates a new bucket and logs to it.
new cloudfront.Distribution(this, 'myDist', {
  defaultBehavior: { origin: new origins.HttpOrigin('www.example.com') },
  enableLogging: true,
});

// You can optionally log to a specific bucket, configure whether cookies are logged, and give the log files a prefix.
new cloudfront.Distribution(this, 'myDist', {
  defaultBehavior: { origin: new origins.HttpOrigin('www.example.com') },
  enableLogging: true, // Optional, this is implied if loggingBucket is specified
  loggingBucket: new s3.Bucket(this, 'LoggingBucket'),
  loggingFilePrefix: 'distribution-access-logs/',
  loggingIncludesCookies: true,
});

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.

const distribution = cloudfront.Distribution.fromDistributionAttributes(scope, 'ImportedDist', {
  domainName: 'd111111abcdef8.cloudfront.net',
  distributionId: '012345ABCDEF',
});

CloudFrontWebDistribution API - Stable

A CloudFront construct - for setting up the AWS CDN with ease!

Example usage:

const sourceBucket = new Bucket(this, 'Bucket');

const distribution = new CloudFrontWebDistribution(this, 'MyDistribution', {
    originConfigs: [
        {
            s3OriginSource: {
                s3BucketSource: sourceBucket
            },
            behaviors : [ {isDefaultBehavior: true}]
        }
    ]
 });

Viewer certificate

By default, CloudFront Web Distributions will answer HTTPS requests with CloudFront's default certificate, only containing the distribution domainName (e.g. d111111abcdef8.cloudfront.net). You can customize the viewer certificate property to provide a custom certificate and/or list of domain name aliases to fit your needs.

See Using Alternate Domain Names and HTTPS in the CloudFront User Guide.

Default certificate

You can customize the default certificate aliases. This is intended to be used in combination with CNAME records in your DNS zone.

Example:

create a distrubution with an default certificiate example

ACM certificate

You can change the default certificate by one stored AWS Certificate Manager, or ACM. Those certificate can either be generated by AWS, or purchased by another CA imported into ACM.

For more information, see the aws-certificatemanager module documentation or Importing Certificates into AWS Certificate Manager in the AWS Certificate Manager User Guide.

Example:

create a distrubution with an acm certificate example

IAM certificate

You can also import a certificate into the IAM certificate store.

See Importing an SSL/TLS Certificate in the CloudFront User Guide.

Example:

create a distrubution with an iam certificate example

Restrictions

CloudFront supports adding restrictions to your distribution.

See Restricting the Geographic Distribution of Your Content in the CloudFront User Guide.

Example:

new cloudfront.CloudFrontWebDistribution(stack, 'MyDistribution', {
   //...
    geoRestriction: GeoRestriction.whitelist('US', 'UK')
});

Connection behaviors between CloudFront and your origin

CloudFront provides you even more control over the connection behaviors between CloudFront and your origin. You can now configure the number of connection attempts CloudFront will make to your origin and the origin connection timeout for each attempt.

See Origin Connection Attempts

See Origin Connection Timeout

Example usage:

const distribution = new CloudFrontWebDistribution(this, 'MyDistribution', {
    originConfigs: [
        {
            ...,
            connectionAttempts: 3,
            connectionTimeout: cdk.Duration.seconds(10),
        }
    ]
});

Origin Fallback

In case the origin source is not available and answers with one of the specified status code the failover origin source will be used.

new CloudFrontWebDistribution(stack, 'ADistribution', {
  originConfigs: [
    {
      s3OriginSource: {
        s3BucketSource: s3.Bucket.fromBucketName(stack, 'aBucket', 'myoriginbucket'),
        originPath: '/',
        originHeaders: {
          'myHeader': '42',
        },
      },
      failoverS3OriginSource: {
        s3BucketSource: s3.Bucket.fromBucketName(stack, 'aBucketFallback', 'myoriginbucketfallback'),
        originPath: '/somwhere',
        originHeaders: {
          'myHeader2': '21',
        },
      },
      failoverCriteriaStatusCodes: [FailoverStatusCode.INTERNAL_SERVER_ERROR],
      behaviors: [
        {
          isDefaultBehavior: true,
        },
      ],
    },
  ],
});

Changelog

1.77.0 (2020-12-07)

⚠ BREAKING CHANGES TO EXPERIMENTAL FEATURES

• apigatewayv2: The VpcLink.fromVpcLinkId() API has been replaced with VpcLink.fromVpcLinkAttributes().
• secretsmanager: (feature flag) Secret.secretName for owned secrets will now return only the secret name (without suffix) and not the full resource name. This is enabled through the @aws-cdk/secretsmanager:parseOwnedSecretName flag.
• lambda-nodejs: bundling customization options like minify or sourceMap are now gathered under a new bundling prop.
• lambda-nodejs: bundlingEnvironment is now bundling.environment
• lambda-nodejs: bundlingDockerImage is now bundling.dockerImage

Features

• apigatewayv2: private integration with imported services (#11661) (6bf0da0), closes #11603
• cfn-include: preserve properties of resources that are not in the current CFN schema (#11822) (45677ca), closes #9717
• cfn-include: the cloudformation-include module is now Generally Available (stable) (#11882) (11df56b)
• cfnspec: cloudformation spec v21.0.0 (#11694) (d1d9fc4)
• cli: support WebIdentityCredentials (as used by EKS) (#11559) (5cfbe6c), closes #11543
• cloudfront: Lambda@Edge construct (#10500) (3b30123), closes #9833 #1575 #9862
• codepipeline-actions: support executeBatchBuild on CodeBuildAction (#11741) (3dcd1a8), closes #11662
• cognito: user pool client - token validity (#11752) (78b3c39), closes #11689
• ecr: authorization token retrieval grants (#11783) (c072981)
• ecs-patterns: allow to select vpc subnets for LB fargate service (#11823) (869c884), closes #8621
• lambda-nodejs: command hooks (#11583) (0608670), closes #11468
• lambda-python: support poetry packaging for PythonFunction (#11850) (c5c258a), closes #11753

Bug Fixes

• codebuild: Project lacks permissions for SSM ParameterStore environment variables (#11770) (3c5c2f4), closes #11769
• codepipeline-actions: incorrect IAM statement in StepFunctionInvokeAction (#11728) (ece9b23), closes #11397 #11688
• core: custom resource providers cannot be used in CDK Pipelines (#11807) (48b3fa9), closes #11760
• core: floating list tokens synthesize to template (#11899) (60875a5), closes #11750
• core: init templates not initialized when running the CLI from source (#11731) (2e067d7), closes #11665
• core: regression: source directory is fingerprinted even if bundling is skipped (#11440) (3cbc7fa), closes #11008 /github.com/aws/aws-cdk/pull/11008/files#diff-62eef996be8abeb157518522c3cbf84a33dd4751c103304df87b04eb6d7bbab6L160 #11008 40aws-cdk/core/lib/asset-staging.ts#L159-L160 #11459 #11460
• ec2: instance not replaced when changing asset in UserData (#11780) (17bde5a), closes #11704
• eks: addManifest can accept any but only works if a map is passed (#11768) (f85c08c), closes #11483
• events: match values in event pattern array are not deduplicated (#11744) (a07b987)
• iam: OIDC provider cannot be imported from parameter (#11789) (cacb1d7), closes #11705
• kinesis: Unable to use retention periods longer than 7 days (#11798) (80e5d90)
• lambda-nodejs: automatic entry finding with compilerOptions.outDir (#11729) (1000cf9)
• lambda-nodejs: maximum call stack size exceeded or converting circular structure to JSON (#11698) (4401725), closes #11693 #11726 #11762
• lambda-nodejs: yarn cannot find a writable cache (#11656) (b16a8d3)
• redshift: multi-node redshift cluster not allowing parameter (#11677) (13c05be), closes #11610
• secretsmanager: secretName for owned secrets includes suffix (under feature flag) (#11736) (f6b4334), closes #11202 #11727
• sqs: queueUrl property has incorrect region and account for imported queue (#11651) (7b8b665)
• stepfunctions-tasks: instance type cannot be provided to SageMakerCreateEndpointConfig as input path (#11749) (5fb0ea6), closes #11605