Skip to content

CloudfrontDistributionBuilder

Purpose

The CloudfrontDistributionBuilder is a concrete implementation of the AbstractAWSResourceBuilder designed to create comprehensive AWS CloudFront distributions for global content delivery. This builder orchestrates the deployment of a production-ready CDN infrastructure supporting multiple origin types including S3 buckets for static content, Application Load Balancers for dynamic content, and VPC origins for private services. Provides global edge caching with SSL termination, WAF integration, and Route53 DNS management for high-performance web applications.

Dependencies

This builder requires the following AWS resources and permissions:

Required AWS Permissions

  • CloudFront Management: Create and configure CloudFront distributions, origins, and behaviors
  • Origin Access Control: Create and manage OAC for secure S3 bucket access
  • Certificate Manager: Access SSL certificates in us-east-1 region for global distribution
  • Route53 DNS: Create A records and manage DNS routing to CloudFront distributions
  • S3 Operations: Configure bucket policies and access controls for origin buckets
  • Application Load Balancer: Reference existing ALBs as CloudFront origins
  • VPC Integration: Access VPC-based origins through private network connections
  • WAF Integration: Attach Web ACLs to CloudFront distributions for security
  • CloudWatch Logging: Configure access logging to S3 buckets
  • Systems Manager: Store distribution parameters for cross-service integration

Foundation Dependencies

  • SSL Certificates: ACM certificates in us-east-1 region for CloudFront compatibility
  • Route53 Hosted Zones: DNS zones for domain routing and global distribution
  • S3 Buckets: Static content storage with proper bucket policies
  • Application Load Balancers: Dynamic content origins with health check configuration
  • VPC Infrastructure: Private network origins for internal service access
  • WAF Web ACLs: Security policies for threat protection and access control
  • Logging Infrastructure: S3 buckets for CloudFront access log storage
  • Environment Configuration: Account and region mappings for multi-environment deployments
  • Naming Standards: Organizational resource naming conventions following company patterns
  • Tagging Strategy: Consistent tagging for cost allocation, security policies, and operational categorization

Configuration

The builder validates all configuration through the CloudfrontConfig model, which becomes the authoritative source for all CloudFront distribution settings.

CDK Configuration Structure

{
  "ssl_certificate_id": "xyz789-abc123-def456",
  "web_acl_id": "arn:aws:wafv2:us-east-1:123456789012:global/webacl/security-waf/87654321-4321-4321-4321-210987654321",
  "logs_bucket": "cloudfront_logs_bucket_object",
  "origins": {
    "default": {
      "name": "frontend-assets",
      "origin_type": "S3",
      "bucket": "frontend_assets_bucket",
      "path": "/",
      "default_root_object": "index.html"
    },
    "api": {
      "name": "public-api",
      "origin_type": "LOAD_BALANCER",
      "alb": "public_api_alb",
      "path": "/api/*",
      "timeout": 60
    },
    "admin": {
      "name": "admin-portal",
      "origin_type": "VPC_ORIGIN",
      "alb": "private_admin_alb",
      "path": "/admin/*",
      "timeout": 45
    }
  },
  "route53": {
    "hosted_zone_id": "Z2ABCDEFGHIJ123",
    "domain_name": "platform.company.io"
  }
}

Configuration Parameters

Parameter Mandatory Type Default Description
ssl_certificate_id Yes str ACM certificate ID in us-east-1 region for HTTPS termination
web_acl_id No str None WAF Web ACL ARN for security protection
logs_bucket No s3.IBucket None S3 bucket for CloudFront access logs
origins Yes Dict[str, CloudfrontOrigin] Origin configurations with "default" origin required
route53 Yes Dict Route53 configuration with hosted_zone_id and domain_name
activate_additional_metrics No bool False Whether to activate additional metrics for the distribution

Usage

Here’s an example of how to use the CloudfrontDistributionBuilder to build and configure a CloudFront Distribution in a CDK stack:

cloudfront_builder = CloudfrontDistributionBuilder()
distribution = cloudfront_builder.set_application_helper(app_helper) \
                                 .set_route53_config({
                                     "hosted_zone_id": "Z2ABCDEFGHIJ123",
                                     "domain_name": "platform.company.io"
                                 }) \
                                 .set_builder_config({
                                     "ssl_certificate_id": "xyz789-abc123-def456",
                                     "web_acl_id": "arn:aws:wafv2:us-east-1:123456789012:global/webacl/enterprise-waf/67890",
                                     "logs_bucket": cloudfront_logs_bucket,
                                     "origins": {
                                         "default": {
                                             "name": "webapp-static",
                                             "origin_type": "S3",
                                             "bucket": webapp_assets_bucket,
                                             "path": "/",
                                             "default_root_object": "app.html"
                                         },
                                         "api": {
                                             "name": "rest-api",
                                             "origin_type": "LOAD_BALANCER",
                                             "alb": public_api_alb,
                                             "path": "/api/*",
                                             "timeout": 60
                                         },
                                         "admin": {
                                             "name": "admin-interface",
                                             "origin_type": "VPC_ORIGIN",
                                             "alb": private_admin_alb,
                                             "path": "/admin/*",
                                             "timeout": 45
                                         }
                                     }
                                 }) \
                                 .build(scope_from_stack)

Behavior and Features

Automatic Distribution Configuration

Global Edge Caching

  • Price Class All: Global distribution across all CloudFront edge locations
  • Optimized Caching: S3 origins use CACHING_OPTIMIZED policy for static content
  • Dynamic Content: Load balancer and VPC origins use CACHING_DISABLED for real-time data
  • HTTPS Enforcement: Redirect to HTTPS for S3 origins, HTTPS-only for dynamic origins
  • All Methods Support: Full HTTP method support (GET, POST, PUT, DELETE, etc.) for API origins

Multi-Origin Support

  • Default Origin: Required S3 bucket origin serving as fallback for unmatched requests
  • Path-Based Routing: Configure multiple origins with specific path patterns (e.g., /api/, /admin/)
  • Origin Types: Support for S3 buckets, Application Load Balancers, and VPC origins
  • Flexible Timeouts: Configurable read timeout per origin for different service requirements

Security and Access Control

  • Origin Access Control: Secure S3 bucket access preventing direct bucket access
  • WAF Integration: Optional Web ACL attachment for threat protection and access control
  • SSL/TLS Termination: HTTPS termination at edge locations with us-east-1 certificate requirement
  • Viewer Protocol Policy: HTTPS redirect for static content, HTTPS-only for dynamic content

Naming Convention

CloudFront resources follow the pattern: {organization-prefix}-{app-name}-{resource-type}

The builder automatically:

  • Applies organizational naming standards across all resources
  • Generates unique CloudFormation logical IDs for distribution components
  • Creates consistent naming for origins based on configuration names

Origin Configuration Patterns

S3 Origin (Static Content)

  • Origin Access Control: Automatic OAC creation for secure bucket access
  • Cache Optimization: CACHING_OPTIMIZED policy for performance
  • HTTPS Redirect: Automatic redirect from HTTP to HTTPS
  • Default Root Object: Configurable index document (e.g., index.html, app.html)

Load Balancer Origin (Dynamic Content)

  • Caching Disabled: Real-time data delivery without edge caching
  • All Viewer Headers: Forward all viewer headers and query parameters
  • Configurable Timeout: Read timeout settings for different service requirements
  • All HTTP Methods: Support for RESTful API operations

VPC Origin (Private Services)

  • Private Network Access: Secure access to VPC-internal services
  • ALB Integration: Connection through Application Load Balancer in private subnets
  • Enhanced Security: Private network communication without internet exposure
  • Custom Timeouts: Extended timeout support for complex internal operations

DNS and Certificate Management

Route53 Integration

  • Alias A Records: Direct routing to CloudFront distribution domain
  • Global DNS Resolution: Automatic routing to nearest edge location
  • Hosted Zone Reference: Integration with existing DNS infrastructure

SSL Certificate Requirements

  • US-East-1 Requirement: CloudFront requires certificates in us-east-1 region
  • Global Termination: SSL/TLS termination at all edge locations worldwide
  • Certificate Reference: Existing ACM certificate integration by ID

Logging and Monitoring

Access Logging

  • S3 Logging: Optional access log collection in specified S3 bucket
  • Log Prefix: Organized logging with "cloudfront-logs/" prefix
  • Cookie Exclusion: Access logs exclude cookie information for privacy
  • CloudFormation Override: Custom property override for advanced logging configuration

Parameter Store Integration

  • Distribution ID Storage: Store distribution ID for cross-service integration
  • Domain Name Storage: Store CloudFront domain name for application configuration
  • Cross-Stack Reference: Enable other stacks to reference CloudFront resources

Caching and Performance Optimization

Cache Policies

  • Static Content: CACHING_OPTIMIZED for S3 origins with TTL optimization
  • Dynamic Content: CACHING_DISABLED for ALB and VPC origins ensuring real-time data
  • Origin Request Policies: ALL_VIEWER policy forwards all headers and parameters

Origin Request Handling

  • Header Forwarding: Complete header forwarding for dynamic origins
  • Query Parameter Support: Full query string forwarding for API compatibility
  • Method Support: All HTTP methods enabled for comprehensive API integration

WAF Integration

  • Optional Protection: WAF Web ACL attachment for threat protection
  • Global Scope: WAF rules applied at edge locations before origin requests
  • Custom Rules: Support for custom WAF rules and managed rule groups
  • DDoS Protection: Enhanced protection when combined with AWS Shield

Notes

  • The set_usage method from the abstract class should not be used in this builder.
  • CloudFront distributions require SSL certificates in us-east-1 region regardless of application region
  • Default origin configuration is mandatory and must be an S3 bucket
  • VPC origins require existing ALB configuration in private subnets
  • Path patterns are processed in order - more specific patterns should be configured first
  • WAF Web ACL must be in "GLOBAL" scope for CloudFront compatibility
  • Access logging requires S3 bucket with appropriate bucket policies
  • Origin timeouts can be configured from 1 to 180 seconds based on service requirements
  • Distribution domain names are stored in SSM Parameter Store for cross-service integration
  • S3 origins automatically receive Origin Access Control for security
  • Price class is set to PRICE_CLASS_ALL for global distribution coverage