Cfdef

CloudFront

Manage CloudFront distribution configuration as reviewable Ruby code

Manages: Amazon CloudFront
Language: Ruby
Package: cfdef
CLI: cfdef
Config file: CFfile

The cfdef repository is archived on GitHub with no activity since 2018 and predates newer CloudFront features, so prefer Terraform for new distributions.

CFfile

distribution "EXAMPLEID" do
  origins do
    quantity 1
    items do |*|
      id "S3-example"
      domain_name "example.s3.amazonaws.com"
      origin_path ""
      s3_origin_config do
        origin_access_identity ""
      end
    end
  end
  default_cache_behavior do
    target_origin_id "S3-example"
    viewer_protocol_policy "allow-all"
    min_ttl 0
  end
end

In short

Cfdef is a Ruby command-line tool that manages Amazon CloudFront distributions as code. It exports each distribution's config, including origins and cache behaviors, into one file called a CFfile. You review changes in Git, dry-run them, then apply them idempotently.

What is Cfdef?

Cfdef is a Ruby command-line tool in the codenize-tools family. It manages CloudFront distributions as code. It exports each distribution's full config into one file, then updates CloudFront to match. This follows the codenization pattern: export, review, dry-run, apply.

CloudFront config is deep and unforgiving. A distribution has dozens of nested settings. One wrong cache behavior or forwarding rule can serve stale content or break an app, and it is painful to debug through the console. A CFfile captures the whole thing:

Origins - where CloudFront fetches content, S3 or a custom server.
Cache behaviors - how each path is cached and forwarded.
Aliases and TLS settings - the domain names and certificates.

Now a change to a TTL or an origin policy is a one-line diff with history and a dry-run preview. Cfdef slots in next to Roadworker, which codenizes the Route 53 DNS records that point at your distributions.

Key facts

Manages CloudFront distributions: origins, cache behaviors, aliases, and TLS settings.
The full config for each distribution lives in one Ruby DSL file, the CFfile.
The DSL mirrors the CloudFront API, so exports stay faithful and diffs stay precise.
A dry-run shows nested changes first; the apply is idempotent.
Pairs with Bukelatta for the S3 bucket policies behind S3 origins.
The repo is archived since 2018 and predates cache policies, functions, and OAC.

Illustration: Amazon CloudFront managed as code with Cfdef

Getting started

Install and run Cfdef

Install

Install the cfdef gem (Ruby required).

$ gem install cfdef

Export current state

Pull the live CloudFront configuration into a CFfile.

$ cfdef -e -o CFfile

Dry-run, then apply

Preview the diff, then apply the change for real.

$ cfdef -a --dry-run

Cfdef runs the export, review, apply loop for CloudFront. Start in export mode (the -e flag), adding --split for one file per distribution, and commit the result. That baseline alone is valuable: it is the first complete, readable record of how each distribution is configured.

Changes, such as a new origin, a tighter viewer protocol policy, or a new TTL, are edits to the CFfile in a branch. Run the apply with --dry-run and attach the diff so reviewers see the exact nested settings that will change. After approval, apply for real; the apply is idempotent. Because CloudFront changes propagate globally and are tedious to compare in the console, a scheduled dry-run is an effective drift detector.

Pro tip

Grep an exported CFfile for viewer_protocol_policy "allow-all" and forward-all-cookies settings. It surfaces weak spots across every distribution in one pass.

Capabilities

What Cfdef can do

Full distribution config in the DSL

Origins, cache behaviors, forwarded values, allowed methods, aliases, and TLS settings all appear as nested Ruby blocks. The blocks mirror the CloudFront API structure.

Export existing distributions

Export mode dumps each distribution's live config into the DSL. Long-lived, console-built distributions come under version control without being recreated.

Dry-run diffs of nested config

The dry-run shows what would change before any update call runs. That matters for a service where updates deploy globally and take time to roll out.

Idempotent apply

The apply only updates distributions whose declared config differs from the live state. Repeated runs and CI re-applies are safe.

Split and scoped operation

The --split option exports one file per distribution. The --target-origin regex filters by origin ID, keeping runs focused when an account hosts many distributions.

Brace-style output option

The --use-braces flag switches the exported DSL to brace syntax instead of do blocks. It is a small readability choice for teams that prefer terse Ruby.

In practice

When teams reach for Cfdef

Bring console-built CDN config under review

Most CloudFront distributions were set up by hand years ago. One export captures every origin and cache behavior as text, giving the team a reviewable baseline and turning future changes into pull requests.

Audit cache behaviors and TLS settings

Finding every distribution that still allows allow-all viewer protocol or forwards all cookies is a text search across the CFfile, not a click-through of each distribution's tabs.

Coordinate CDN changes with DNS

Teams often change a distribution and its Route 53 records together. Managing CloudFront with Cfdef and DNS with Roadworker puts both halves in the same pull request, with a dry-run for each.

FAQ

Cfdef questions, answered

What does Cfdef manage?

It manages the configuration of existing CloudFront distributions: origins, cache behaviors, forwarded values, aliases, and related settings, all written in the CFfile DSL. It uses the same export, dry-run, apply model as the other codenize tools.

Why is the DSL so deeply nested?

The CFfile mirrors the CloudFront API itself, including quantity fields and items blocks. That keeps exports faithful and diffs precise, at the cost of some verbosity, the same trade-off the raw API makes.

Does applying a change take effect immediately?

Cfdef submits the update, but CloudFront still needs time to deploy it to edge locations, exactly as with console or API updates. The dry-run, by contrast, is instant and makes no changes.

Is Cfdef still maintained?

No. The repository is archived, with no activity since 2018, and CloudFront has gained many features since, such as cache policies, functions, and OAC. For new work, Terraform's aws_cloudfront_distribution resource is the actively maintained option.