CDN Configuration Templating: Jinja2, HCL, and Go Templates for Edge Configs

Back in 2019 I watched a junior engineer spend two full days hand-editing 180 Varnish VCL files for a seasonal cache rule change, only to miss a single semicolon on one PoP that took down image delivery for 40 minutes. We've all been there — copying and pasting edge configs until they drift apart, and then praying your find-and-replace didn't miss anything. That's the moment I stopped treating CDN configuration as static files and started treating it as generated artifacts, and it completely changed how our team ships edge logic.

Why Raw Config Files Don't Scale at the Edge

When you're running five or ten edge locations, you can get away with maintaining a handful of Nginx or VCL files by hand. At fifty or a hundred PoPs with different origins, cache policies, and TLS requirements per customer, that approach collapses fast. I learned this the hard way on a multi-tenant CDN we ran for a media customer around 2017 — we had 22 variants of what was supposed to be the "same" caching config, each slightly different because someone hot-fixed one file in production and never backported it. Configuration templating solves that by separating your data from your structure, so you maintain one template and feed it different variables per environment, region, or tenant.

The core idea behind configuration templating is simple: you don't write the final CDN config, you write a blueprint that generates it. Your variables — origins, TTLs, header rules, WAF flags — live in YAML, JSON, or even a database, and the engine renders them into the exact VCL, Nginx, or JSON edge dictionary your provider expects. If you've been automating deployments with CDN Automation with Ansible Playbooks: Configuration Management at Edge Scale, you've already seen half the picture — templating is what makes those playbooks deterministic instead of fragile. It also enforces consistency with standards like those documented in the HTTP Working Group Specifications, because you can validate generated Cache-Control and CDN-Cache-Control headers in one place.

Here's what a typical Jinja2 template looks like for generating Nginx-based edge cache configs. We use this pattern for customers who need per-route TTLs and stale-while-revalidate support without duplicating blocks:

{# edge-cache.conf.j2 - Jinja2 template for Nginx CDN edge #}
{% for route in routes %}
location {{ route.path }} {
    proxy_pass {{ route.origin }};
    proxy_cache cdn_cache;
    proxy_cache_valid {{ route.cache_status }} {{ route.ttl }};
    proxy_cache_use_stale error timeout updating http_500 http_502;
    add_header X-Cache-Status $upstream_cache_status;
    add_header Cache-Control "{{ route.cache_control }}";
    {% if route.stale_while_revalidate %}
    add_header Surrogate-Control "max-age={{ route.ttl }}, stale-while-revalidate={{ route.swr }}";
    {% endif %}
    {% for header in route.extra_headers %}
    proxy_set_header {{ header.name }} "{{ header.value }}";
    {% endfor %}
}
{% endfor %}
# Rendered with: jinja2 edge-cache.conf.j2 vars/production.yaml > /etc/nginx/conf.d/edge.conf

HCL and Go Templates: Templating Where Your Infrastructure Lives

Jinja2 is fantastic when you're coming from Python and Ansible, but it isn't the only option I've relied on. If your CDN infrastructure is defined in Terraform, HCL templates are a much more natural fit. I remember migrating a Fastly and CloudFront setup where the team was rendering configs with Jinja2 and then feeding them into Terraform via local files — it worked, but debugging was miserable because errors showed up only at apply time. Switching to Terraform's templatefile() function and HCL-native string interpolation gave us immediate validation, type checking, and plan-time diffs. You didn't have to context-switch between Python and Terraform mental models, and that alone cut our review time in half.

Go templates are the other heavyweight you'll run into, especially if you work with Fastly Compute@Edge, Cloudflare Workers, or Kubernetes-backed CDNs where VCL or edge logic is packaged via Helm or custom operators. They look minimal at first — just {{ .Values.origin }} — but they have powerful logic for loops, conditionals, and custom functions via Sprig. The trade-off is that Go templates can be terse and unforgiving; a missing pipe or wrong whitespace control will fail silently. Per recommendations from web.dev Articles on caching best practices, we've started linting all rendered outputs for correct Cache-Control and CDN-Cache-Control directives before they ever hit the edge, regardless of engine. That extra check has saved us from shipping a 1-year TTL to a no-store API route more than once.

This HCL example generates a Fastly service configuration from a shared variable map. It's how we handle dozens of customer domains without copying service blocks:

# cdn_service.tf - HCL templating with Terraform for CDN config generation
variable "edge_domains" {
  type = map(object({
    origin_address = string
    ttl            = number
    shield         = string
    force_tls      = bool
  }))
}

resource "fastly_service_vcl" "edge" {
  for_each = var.edge_domains
  name     = "cdn-${each.key}"

  domain {
    name    = each.key
    comment = "Managed by templated config"
  }

  backend {
    address           = each.value.origin_address
    name              = "origin-${each.key}"
    shield            = each.value.shield
    connect_timeout   = 1000
    first_byte_timeout = 15000
  }

  # Rendered VCL snippet via templatefile
  vcl {
    name    = "cache-settings"
    content = templatefile("${path.module}/templates/cache.vcl.tftpl", {
      ttl       = each.value.ttl
      force_tls = each.value.force_tls
    })
    main = true
  }

  force_destroy = true
}

Choosing the Right Engine for CDN Config Generation

There's no single best engine — I've used all three in production, often in the same stack. The decision usually comes down to where your source of truth lives and who will maintain the templates. If your team is Python-heavy and you're generating VCL or Nginx configs through CI pipelines, Jinja2's familiarity and rich filters are hard to beat. If you're already deep in Terraform for your edge infrastructure, stay with HCL templates so you get plan-time safety. And if you're packaging edge logic through Go-based tooling like Helm, Caddy, or custom control planes, Go templates keep things consistent without adding another runtime.

One mistake I see intermediate teams make is choosing purely on syntax preference without measuring operational impact. Rendering speed matters when you're generating 2,000 edge dictionaries per deploy, and so does drift detection. For teams evaluating whether to move beyond ad-hoc templating to full code-driven workflows, I've found it helpful to compare approaches like CDN Infrastructure with Pulumi: Type-Safe CDN Configuration in Real Programming Languages against pure templating, and for AWS-centric stacks, CDN Resources in CloudFormation: AWS-Native Infrastructure as Code for Content Delivery is worth a look before you commit to a template-heavy CloudFront design. You don't want to paint yourself into a corner where your templates can't express the failover logic your CDN actually needs.

Putting Templates to Work: A Production-Ready Generation Pipeline

Theory's great, but here's how we've actually wired this up for fleets running 150-400 PoPs. You don't want templating logic living on the edge itself — you want a centralized generator that renders static configs and ships them. Our standard pattern is dead simple: a single source of truth in YAML or JSON (origins, cache rules, WAF exceptions, per-customer headers) + a set of versioned templates + a CI job that renders, validates, and publishes. We keep data strictly separate from presentation, so adding a new customer or origin doesn't mean touching VCL or Nginx syntax — you're just adding 5 lines of YAML.

In practice, you'll render locally or in CI with a small Python or Go binary, then push the output to your config management or artifact store. For example, if you're still managing some legacy edges with CDN Configuration with Chef: Recipe-Based Infrastructure for Content Delivery or transitioning to Terraform, your generated files become the artifacts those tools converge. We typically see generation times drop from 45-60 seconds of brittle Bash sed scripts to 1.1-1.8 seconds for 250+ virtual hosts when moving to proper templating. That speed matters when you're doing 20-30 deploys a day and can't afford a 10-minute config build blocking your pipeline.

The key guardrail is validation *before* you ship. Every render should immediately run `nginx -t`, `varnishd -C`, or `terraform validate` depending on your stack, plus a policy check. Don't trust the template to be clever — trust your tests. We've caught countless whitespace and escaping bugs that would've taken down 18% of cache nodes just by adding a JSON schema check on the input data and a syntax lint on the output.

{# edge-nginx.conf.j2 - Jinja2 for Nginx edge with per-tenant origins #}
{% for tenant in tenants %}
# {{ tenant.name }} - generated {{ generated_at }} - do not edit manually
upstream {{ tenant.id }}_origin {
    {% for origin in tenant.origins %}
    server {{ origin.host }}:{{ origin.port }} max_fails=3 fail_timeout=30s;
    {% endfor %}
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name {{ tenant.domains | join(' ') }};

    location / {
        proxy_pass http://{{ tenant.id }}_origin;
        proxy_cache STATIC;
        proxy_cache_valid 200 302 {{ tenant.ttl | default('1d') }};
        proxy_cache_use_stale error timeout updating http_500 http_502;
        add_header X-Cache-Status $upstream_cache_status always;
        {% if tenant.stale_while_revalidate %}
        proxy_cache_background_update on;
        {% endif %}
    }
}
{% endfor %}

# Render with: jinja2 edge-nginx.conf.j2 inventory.yaml --format=yaml > /etc/nginx/conf.d/edge.conf

Advanced Patterns and Troubleshooting When Templates Break at Scale

Once you're past 100 edge nodes, templates don't fail loudly — they fail weirdly. The most common pain we've debugged isn't logic, it's whitespace and escaping. Go templates are notorious for injecting newlines that break VCL, while Jinja2 will happily eat a trailing slash you actually needed for a regex. Use whitespace control religiously (`{{-` and `-}}` in Go, `trim_blocks` and `lstrip_blocks` in Jinja2) and always test rendered output with real traffic captures, not just eyeballing it. If your hit ratio suddenly drops from 96.4% to 82% after a deploy, you've probably got a bad `Vary` or cache-key template, not an origin issue.

Another pattern that saves us constantly: partials and composition over monoliths. Don't build one 900-line `edge.vcl.j2` monster. Break it into includes — `cache-key.vcl.j2`, `waf-rules.vcl.j2`, `logging.vcl.j2` — and compose them. HCL handles this natively with modules, and both Jinja2 (`{% include %}`) and Go templates (`{{ template "partials/cache" . }}`) do too. This is also where integration with declarative systems pays off. Teams running CDN Puppet Management for Edge Nodes: Declarative Configuration at Scale often use Hiera data to feed templates, letting Puppet ensure the rendered file is there while the template itself stays portable. And don't try to enforce business rules inside the template — offload that to policy. We've moved all our "customer X can't have TTL < 60s" checks to CDN Policy as Code with OPA and Sentinel: Enforcing Rules Automatically so templates stay dumb and fast.

When things do go wrong, don't `diff` the template — `diff` the rendered output. Keep the last 10 known-good rendered configs as artifacts in S3 or Artifactory. If a deploy causes 5xx spikes in under 60 seconds, your rollback shouldn't be "re-render old template," it should be "re-push last known-good artifact." We've cut mean-time-to-recovery from 14 minutes to under 90 seconds with that one change.

Frequently Asked Questions