AWS CDK CloudFront Construct Library

Common errors

• ModuleNotFoundError: No module named 'aws_cdk.aws_cloudfront'

  cause The Python package `aws-cdk.aws-cloudfront` is not installed in your environment, or the import path is incorrect.
  fix Ensure the package is installed using pip: `pip install aws-cdk.aws-cloudfront`. Also check that you are using the correct `from aws_cdk import aws_cloudfront as cloudfront` import pattern.

• AttributeError: 'module' object has no attribute 'Distribution'

  cause This usually means you imported the module incorrectly, or the symbol 'Distribution' is not directly accessible from the imported object. For example, `import aws_cdk.aws_cloudfront` does not expose `Distribution` directly as `aws_cdk.aws_cloudfront.Distribution` without aliasing.
  fix Use the standard import pattern: `from aws_cdk import aws_cloudfront as cloudfront` and then `cloudfront.Distribution(...)`. Alternatively, `from aws_cdk.aws_cloudfront import Distribution` and use `Distribution(...)` directly.

• Access Denied errors when CloudFront tries to access an S3 bucket.

  cause The CloudFront Origin Access Identity (OAI) does not have sufficient permissions to read objects from your S3 bucket, or the S3 bucket policy is incorrectly configured.
  fix Ensure you have called `bucket.grant_read(oai)` on your S3 bucket object, and verify that the bucket policy explicitly allows `s3:GetObject` actions for the OAI's ARN.

Warnings

• breaking Migration from AWS CDK v1 to v2 involves significant breaking changes. Package names often change (e.g., `aws_cdk.aws_cloudfront` might become `aws_cdk.aws_cloudfront_alpha` or `aws_cdk.aws_cloudfront` in v2, depending on stability). Construct patterns and parameter names also differ. Projects built with v1 are not directly compatible with v2.
  Fix: Refer to the official AWS CDK v2 migration guide. This package is for CDK v1; for v2, use `aws-cdk-lib` and its submodules (e.g., `aws_cdk_lib.aws_cloudfront`).
• gotcha CDK v1 primarily uses Origin Access Identity (OAI) for secure CloudFront access to S3. AWS now recommends Origin Access Control (OAC) as a more secure and flexible alternative, which is the standard in CDK v2. While OAI works for v1, be aware of this shift for future migrations or greenfield v2 projects.
  Fix: For CDK v1, continue using `cloudfront.OriginAccessIdentity`. For CDK v2, prioritize `aws_cloudfront.CfnOriginAccessControl` or higher-level constructs that integrate OAC.
• gotcha Incorrect configuration of CloudFront Cache Policies and Origin Request Policies can lead to unexpected caching behavior, missing headers/cookies/query strings at the origin, or security vulnerabilities (e.g., caching sensitive data).
  Fix: Carefully review the default and custom Cache/Origin Request Policies. Test your CloudFront distribution thoroughly for desired caching behavior and ensure all necessary request attributes (headers, cookies, query strings) are forwarded to the origin when required, but not cached unnecessarily.

Install

• pip install aws-cdk.core aws-cdk.aws-s3 aws-cdk.aws-cloudfront aws-cdk.aws-cloudfront-origins Install core CDK and CloudFront constructs

Imports

• core

  from aws_cdk import core as cdk

• aws_s3

  from aws_cdk import aws_s3 as s3

• aws_cloudfront
  wrong:

  import aws_cdk.aws_cloudfront

  correct:

  from aws_cdk import aws_cloudfront as cloudfront

  Commonly imported as 'cloudfront' for brevity and consistency.
• aws_cloudfront_origins
  wrong:

  from aws_cdk.aws_cloudfront import origins

  correct:

  from aws_cdk import aws_cloudfront_origins as origins

  The origins library is a separate package from the core cloudfront constructs.
• Distribution

  from aws_cdk.aws_cloudfront import Distribution

• OriginAccessIdentity

  from aws_cdk.aws_cloudfront import OriginAccessIdentity

Quickstart

This quickstart demonstrates how to create a basic AWS CloudFront distribution in CDK v1. It configures an S3 bucket as the origin and uses an Origin Access Identity (OAI) for secure access. The distribution is set to redirect HTTP requests to HTTPS and specifies `index.html` as the default root object. Remember to configure your AWS credentials and `CDK_DEFAULT_ACCOUNT`/`CDK_DEFAULT_REGION` environment variables.

import os
from aws_cdk import (
    core as cdk,
    aws_s3 as s3,
    aws_cloudfront as cloudfront,
    aws_cloudfront_origins as origins,
)

class CloudFrontDistroStack(cdk.Stack):
    def __init__(self, scope: cdk.App, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Create an S3 bucket to serve as the origin for CloudFront
        bucket = s3.Bucket(
            self, "WebsiteBucket",
            versioned=False,
            removal_policy=cdk.RemovalPolicy.DESTROY,
            auto_delete_objects=True # Be cautious with auto_delete_objects in production
        )

        # Create an Origin Access Identity (OAI) for CloudFront to securely access S3
        # In AWS CDK v2, Origin Access Control (OAC) is the recommended alternative.
        oai = cloudfront.OriginAccessIdentity(
            self, "OAI",
            comment="Allows CloudFront to access S3 bucket"
        )
        # Grant the OAI read permissions to the S3 bucket
        bucket.grant_read(oai)

        # Create a CloudFront Distribution
        cloudfront.Distribution(
            self, "MyDistribution",
            default_behavior=cloudfront.BehaviorOptions(
                origin=origins.S3Origin(bucket, origin_access_identity=oai),
                viewer_protocol_policy=cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS
            ),
            default_root_object="index.html" # Assumes an index.html file in your S3 bucket
        )

app = cdk.App()
CloudFrontDistroStack(app, "MyCloudFrontDistroStack",
                      env=cdk.Environment(
                          account=os.environ.get('CDK_DEFAULT_ACCOUNT'),
                          region=os.environ.get('CDK_DEFAULT_REGION')
                      )
)
app.synth()