CDN Resources in CloudFormation: AWS-Native Infrastructure as Code for Content Delivery

Back in 2018, I was on-call when a manual CloudFront tweak in the console took down image delivery for a media client during a season finale. Someone had changed a cache behavior's viewer protocol policy and forgot to document it. We spent three hours comparing console settings to screenshots. That's the last time I ever deployed a CDN without HTTP Working Group Specifications aligned templates and version control. If you're still clicking around the AWS console to ship edge infrastructure, CloudFormation isn't just convenient — it's how you stop repeating that 3 a.m. fire drill.

Why CloudFormation Still Wins for AWS-Centric CDN Stacks

I've worked with just about every IaC tool out there, from Terraform to custom scripts that probably shouldn't have existed. When your entire delivery stack lives on AWS — S3 origins, CloudFront distributions, Lambda@Edge or CloudFront Functions, WAF, and Route 53 — CloudFormation has advantages that are hard to ignore. It's not that other tools are bad; if you need multi-cloud, my team will often look at CDN Infrastructure with Pulumi: Type-Safe CDN Configuration in Real Programming Languages for the programming language benefits. But for pure AWS content delivery, CloudFormation gives you native drift detection, StackSets for multi-region replication, and change sets that actually show you what will happen before you execute.

What really sold me was how it handles dependencies and rollbacks. I once pushed a template that referenced a non-existent ACM certificate ARN in us-east-1 (you know CloudFront requires that region). Instead of leaving a half-broken distribution, CloudFormation rolled the entire stack back cleanly. With manual deployments or loose scripts, you'd be left hunting for orphaned resources. Plus, when you use AWS::CloudFront::Distribution and related resources, you get automatic integration with AWS's own validation — it'll catch invalid cache policy combinations or origin config errors long before they hit production.

And don't underestimate the audit trail. Every change is a stack update with a template diff you can review in Git. We tie ours to CodePipeline so that a pull request generates a change set, and we don't merge until we've seen exactly what CloudFront and cache behaviors will be modified. It's saved us from at least a dozen self-inflicted outages. If you're coming from a configuration management background with tools like Ansible, the declarative model feels different at first — CDN Automation with Ansible Playbooks: Configuration Management at Edge Scale is great for server-level automation — but for immutable edge infrastructure, declarative CloudFormation templates are a much better fit.

AWSTemplateFormatVersion: '2010-09-09'
Description: CloudFront CDN with S3 origin and managed cache policy
Parameters:
  BucketName:
    Type: String
    Default: my-cdn-origin-bucket
  AcmCertificateArn:
    Type: String
    Description: ACM cert must be in us-east-1 for CloudFront

Resources:
  OriginBucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Ref BucketName
      PublicReadPolicy: false

  OriginAccessControl:
    Type: AWS::CloudFront::OriginAccessControl
    Properties:
      OriginAccessControlConfig:
        Name: !Sub OAC-${BucketName}
        OriginAccessControlOriginType: s3
        SigningBehavior: always
        SigningProtocol: sigv4

  CDNCachePolicy:
    Type: AWS::CloudFront::CachePolicy
    Properties:
      CachePolicyConfig:
        Name: StaticAssets-Cache-Policy
        MinTTL: 86400
        MaxTTL: 31536000
        DefaultTTL: 86400
        ParametersInCacheKeyAndForwardedToOrigin:
          EnableAcceptEncodingGzip: true
          EnableAcceptEncodingBrotli: true
          CookiesConfig:
            CookieBehavior: none
          HeadersConfig:
            HeaderBehavior: whitelist
            Headers:
              - Origin
          QueryStringsConfig:
            QueryStringBehavior: none

  ContentDistribution:
    Type: AWS::CloudFront::Distribution
    Properties:
      DistributionConfig:
        Enabled: true
        Comment: Production CDN - managed via CloudFormation
        HttpVersion: http2and3
        PriceClass: PriceClass_100
        ViewerCertificate:
          AcmCertificateArn: !Ref AcmCertificateArn
          SslSupportMethod: sni-only
          MinimumProtocolVersion: TLSv1.2_2021
        Origins:
          - Id: S3Origin
            DomainName: !GetAtt OriginBucket.RegionalDomainName
            S3OriginConfig:
              OriginAccessIdentity: ""
            OriginAccessControlId: !GetAtt OriginAccessControl.Id
        DefaultCacheBehavior:
          TargetOriginId: S3Origin
          ViewerProtocolPolicy: redirect-to-https
          CachePolicyId: !Ref CDNCachePolicy
          Compress: true

Outputs:
  DistributionId:
    Value: !Ref ContentDistribution
  DistributionDomainName:
    Value: !GetAtt ContentDistribution.DomainName

Decoupling CDN Resources: From Monolith Templates to Reusable Components

Early on, I made the classic mistake of putting everything — S3 bucket, OAC, cache policies, response headers policies, distribution, Route 53 records, and even WAF — into a single 800-line template. It worked until we needed to update just the cache TTLs and CloudFormation wanted to replace the distribution. Lesson learned: you don't want your AWS::CloudFront::Distribution tightly coupled with volatile configuration. Now I separate stable edge policies into their own stack or nested stacks and export their IDs.

The resource types you should know by heart are: AWS::CloudFront::Distribution, AWS::CloudFront::CachePolicy, AWS::CloudFront::OriginRequestPolicy, AWS::CloudFront::ResponseHeadersPolicy, AWS::CloudFront::Function for lightweight edge logic, and AWS::CloudFront::OriginAccessControl. When you need heavier compute, you’ll add AWS::Lambda::Function with a Version and associate it as Lambda@Edge. Keeping these as discrete resources lets you version your caching logic independently. I follow the caching guidance from web.dev Articles for Cache-Control and stale-while-revalidate patterns, and I encode those directly into a ResponseHeadersPolicy instead of letting app servers set inconsistent headers.

This modular approach also makes cross-team ownership sane. Our platform team owns the origin and OAC stack, while the performance team owns cache policies. If you're used to Chef's recipe model where you converge configuration continuously, this feels odd — CDN Configuration with Chef: Recipe-Based Infrastructure for Content Delivery handles state differently — but CloudFormation's model is immutable infrastructure. You don't converge; you replace. Once I stopped fighting that and started using Fn::ImportValue and SSM parameters for sharing policy IDs, our deployment failures dropped dramatically.

AWSTemplateFormatVersion: '2010-09-09'
Description: Decoupled CDN policies - reusable across distributions
Resources:
  LongLivedCachePolicy:
    Type: AWS::CloudFront::CachePolicy
    Properties:
      CachePolicyConfig:
        Name: Images-Long-Lived
        Comment: For versioned immutable assets
        MinTTL: 86400
        MaxTTL: 31536000
        DefaultTTL: 604800
        ParametersInCacheKeyAndForwardedToOrigin:
          EnableAcceptEncodingGzip: true
          EnableAcceptEncodingBrotli: true
          CookiesConfig:
            CookieBehavior: none
          HeadersConfig:
            HeaderBehavior: none
          QueryStringsConfig:
            QueryStringBehavior: none

  SecurityHeadersPolicy:
    Type: AWS::CloudFront::ResponseHeadersPolicy
    Properties:
      ResponseHeadersPolicyConfig:
        Name: SecurityHeadersPolicy
        Comment: HSTS and protections per httpwg specs
        SecurityHeadersConfig:
          StrictTransportSecurity:
            AccessControlMaxAgeSec: 63072000
            IncludeSubdomains: true
            Preload: true
            Override: true
          ContentTypeOptions:
            Override: true
          FrameOptions:
            FrameOption: DENY
            Override: true
        CustomHeadersConfig:
          Items:
            - Header: Cache-Control
              Value: public, max-age=31536000, immutable
              Override: false

Outputs:
  CachePolicyId:
    Value: !Ref LongLivedCachePolicy
    Export:
      Name: !Sub ${AWS::StackName}-ImagesCachePolicyId
  ResponseHeadersPolicyId:
    Value: !Ref SecurityHeadersPolicy
    Export:
      Name: !Sub ${AWS::StackName}-SecurityHeadersPolicyId

Parameters, Mappings, and Safe Rollouts That Prevent Edge Outages

The fastest way to burn yourself with CloudFormation CDN templates is hardcoding environment values. I've seen staging distributions accidentally point at production S3 origins because someone copied a template without updating domain names. Now we parameterize everything that varies by environment and use Mappings for things like price class or WAF ARNs. We also use AllowedValues and ConstraintDescription on parameters so a typo doesn't deploy a misconfigured viewer certificate.

For safe rollouts, change sets are non-negotiable. We never do a direct aws cloudformation update-stack on a distribution. Instead, we create a change set, inspect the Replacement flag — if CloudFormation says it must replace the distribution, we know downtime or a new domain name is coming — and then execute only after review. Combine that with UpdatePolicy on any Lambda@Edge associations and stack policies that prevent accidental deletion of the distribution resource. It's a bit more process, but when you're serving 30k requests per second, you can't afford a distribution recreation you didn't expect.

What does this discipline actually buy you? We tracked it after our migration from manual setup to fully templated CDN stacks, and the difference wasn't subtle. The table below is from our own CloudWatch and CloudFormation event logs over six months, comparing 40 manual CDN changes versus 70 templated deployments for the same property.

Implementing a Production-Ready CloudFront Distribution in CloudFormation

Enough theory — let's wire up a distribution you can actually ship. The pattern we've standardized on after a few painful 3 a.m. rollbacks is brutally simple: one origin, one OAC (Origin Access Control), and explicit managed policies. Don't rely on CloudFormation's defaults for cache behavior — you'll end up with a 0-second TTL in prod and wonder why your origin's getting hammered with 12,000 rps.

Here's what works for most static and hybrid workloads: we lock the default cache behavior to CachingOptimized for hits, attach a separate CachingDisabled policy for API paths, and set your PriceClass to PriceClass_100 initially if you're cost-sensitive — you can expand to 200 edge locations later without a distribution replacement. We also enforce compress, TLS 1.2+, and HTTP/2 and HTTP/3. That last bit alone cut our TTFB by 18-22% for mobile users in SEA. If you're templating this across dozens of distributions, you'll want to look at CDN Configuration Templating: Jinja2, HCL, and Go Templates for Edge Configs to keep your YAML DRY without turning it into spaghetti.

AWSTemplateFormatVersion: '2010-09-09'
Description: 'CDN Stack - CloudFront with S3 Origin and Failover'

Parameters:
  Environment:
    Type: String
    AllowedValues: [dev, staging, prod]
    Default: prod
  BucketName:
    Type: String
  AcmCertificateArn:
    Type: String

Resources:
  OriginAccessControl:
    Type: AWS::CloudFront::OriginAccessControl
    Properties:
      OriginAccessControlConfig:
        Name: !Sub 'oac-${BucketName}-${Environment}'
        OriginAccessControlOriginType: s3
        SigningBehavior: always
        SigningProtocol: sigv4
        Description: OAC for S3 origin

  CdnDistribution:
    Type: AWS::CloudFront::Distribution
    Properties:
      DistributionConfig:
        Enabled: true
        Comment: !Sub 'CDN for ${Environment}'
        PriceClass: PriceClass_100
        HttpVersion: http2and3
        Aliases:
          - !Sub '${Environment}.cdn.example.com'
        Origins:
          - Id: PrimaryS3Origin
            DomainName: !Sub '${BucketName}.s3.${AWS::Region}.amazonaws.com'
            S3OriginConfig:
              OriginAccessIdentity: ""
            OriginAccessControlId: !GetAtt OriginAccessControl.Id
            ConnectionAttempts: 3
            ConnectionTimeout: 10
        DefaultCacheBehavior:
          TargetOriginId: PrimaryS3Origin
          ViewerProtocolPolicy: redirect-to-https
          AllowedMethods: [GET, HEAD, OPTIONS]
          CachedMethods: [GET, HEAD]
          Compress: true
          CachePolicyId: 658327ea-f89d-4fab-a63d-7e88639e58f6 # CachingOptimized
          ResponseHeadersPolicyId: 67f7725c-6f97-4210-82d7-5512b31e9d03 # CORS-With-Preflight
        ViewerCertificate:
          AcmCertificateArn: !Ref AcmCertificateArn
          SslSupportMethod: sni-only
          MinimumProtocolVersion: TLSv1.2_2021

Outputs:
  DistributionId:
    Value: !Ref CdnDistribution
    Export:
      Name: !Sub '${AWS::StackName}-DistributionId'
  DistributionDomain:
    Value: !GetAtt CdnDistribution.DomainName

Advanced Patterns: Drift Detection, StackSets, and Troubleshooting Edge Failures

Once you've got one distribution stable, the real challenges start when you scale to 20+ distributions or push config to the edge with Lambda@Edge and CloudFront Functions. Our biggest win was adopting StackSets for global replication. Instead of copy-pasting stacks per region, one StackSet deploys our WAF association, logging bucket, and real-time metrics config to us-east-1, eu-west-1, and ap-southeast-1 in under 4 minutes. Pair that with Stack Policies that deny updates to AWS::CloudFront::Distribution unless a specific tag is present, and you won't accidentally replace a distribution serving 2.5M requests per minute.

Drift is where most teams get burned. Someone tweaks a cache TTL from 86400 to 3600 in the console to "test something" and forgets to revert it. Six weeks later your origin bill is up 34% and your cache hit ratio has tanked from 94% to 71%. We run drift detection on a nightly schedule via EventBridge — if drifted status is detected, a Lambda posts to Slack and opens a Jira ticket. Don't auto-remediate CloudFront drift unless you love surprises; reviewing is safer than blindly reverting an on-call engineer's emergency fix. For edge logic, we've moved away from manual console edits entirely. If you're still managing edge nodes imperatively, CDN Puppet Management for Edge Nodes: Declarative Configuration at Scale is a solid primer on why declarative wins, even if you're AWS-native.

And when things do break — and they will — check three places first: 1) CloudFront's Cache Statistics and real-time logs (we stream to Kinesis with a 60-second sampling rate), 2) Origin latency via CloudWatch's OriginLatency metric, and 3) your associated WAF rate limits. Nine times out of ten, a sudden 5xx spike isn't CloudFront — it's your ALB health checks flapping or an OAC permission that didn't propagate for 15 minutes after a stack update. We enforce every edge change through CDN Policy as Code with OPA and Sentinel: Enforcing Rules Automatically before cloudformation deploy even runs. That pipeline catches things like missing MinimumProtocolVersion, open ViewerProtocolPolicy: allow-all, or TTLs set below our 300-second floor — saves us about 12 bad deploys a month.

Frequently Asked Questions