Moving house to Cloudflare (and finally writing it all down in Terraform)

My domains, DNS, and this site had previously been spread across a handful of providers and held together by my trusty friend, memory-based chaos. Today I pulled them all into one repo, with Terraform to define the infrastructure and GitLab storing the state and pushing the content. It turned into a coffee-fueled lazy Sunday morning, so here's the narrative while I still remember it. (Potential memory lapses have nothing to do with the Rumchata that may have been in the coffee, I swear!)

The before picture

I own a handful of domains: this one, an infant business site, a placeholder for my family farm, and a couple of others that mostly exist to make it easy to acquire TLS certificates for internal domains from Let's Encrypt. Their DNS records lived in the Cloudflare dashboard, where I had previously set them up by hand or imported from Namecheap. This site was built by a GitHub Action and served from GitHub Pages. Mail went through some mix of Proton and Namecheap forwarding, depending on the domain.

Everything worked, more or less. But if you'd asked me why a particular TXT record existed, the honest answer would have been a shrug.

The goal

Terraform layout

The infrastructure is Terraform with the Cloudflare provider. The repo looks roughly like this:

modules/zone/        zone, zone settings, DNS records, mail records, redirect rules
modules/pages-site/  Pages project, custom domain, apex and www records
domains/<domain>/    one Terraform root per domain, each with its own state
domains/_shared/     provider/version/variable files, symlinked into every domain (If I mess with the code on Windows, I'll get yelled at until I use WSL or enable symlinking...I'm okay with that)
sites/<domain>/      site content
scripts/             a Terraform wrapper and a deploy script
    

The two modules carry all of the actual logic. The zone module is the workhorse: it owns the zone, applies the same baseline settings everywhere (SSL Full (strict), always HTTPS, TLS 1.2 or better), manages whatever records I hand it, and can stamp out the full set of Proton Mail records (MX, SPF, DKIM, DMARC, verification) from two values. The Pages module creates the Pages project, attaches the custom domain, and points the apex and www records at it. A www to apex 301 rides along in the zone's redirect rules.

Each domain then gets its own small Terraform root that just calls those modules. I wanted separate states because a single state for five domains meant every plan touched everything, and a fat-fingered change to one domain could, in theory, wreck another. Now scripts/tf <domain> plan runs Terraform for exactly one domain against exactly one state.

Adopting what already existed

The tricky part of putting existing infrastructure under Terraform is doing it without breaking anything. Every zone and record already existed, so each one was imported into state, and then I tweaked the code until terraform plan reported no changes. Only once the code and reality matched did I start making actual changes. That was tedious, and also the step that's easiest to skip, but it meant the first real apply on each domain did exactly what I expected and nothing more.

The nice side effect: every record is now in code, and has a commit message saying why it's there.

GitLab for state

Terraform needs somewhere to keep its state, and my laptop is *not* an ideal location. GitLab has a built-in Terraform state backend, and I was already using GitLab for the repo, so that was an easy call. Each domain gets its own named state in the project. GitLab keeps a version history of every state and handles locking, so two runs can't stomp on each other.

The backend block in the code is intentionally empty. The wrapper script builds the state address from the domain name at init time, and the credentials (a GitLab access token) come from a local .env file that never gets committed. The wrapper also refuses to run if the one environment variable that could point every domain at the same state is set. I may be paranoid, but that mistake could have made for a lousy afternoon...

The wrapper script

scripts/tf is about fifty lines of bash, and it does three things before Terraform ever runs:

  1. Loads .env. It sources a small helper that reads the repo's .env (if there is one) and exports everything in it. The one twist: anything already set in the environment wins. So on my laptop the values come from .env, while in CI, where there is no .env and the variables come from GitLab, the exact same script just works. And if I want to try something one-off, I can export a variable by hand without editing the file. (It's written for bash 3.2, so it works on macOS's ancient default bash too.)
  2. Picks the domain and its state. The first argument names a directory under domains/, and the state name is derived from it. The script builds the backend addresses from that and hands them to init.
  3. Initializes when it needs to. If the domain hasn't been initialized yet, it runs init first, quietly. Then it passes everything else straight through to Terraform, so scripts/tf <domain> plan is just terraform plan, aimed at the right place.

I find myself writing some version of this script on nearly every Terraform project that grows past a single directory. Once there are multiple environments or stacks, each needing its own backend config, credentials, and a working directory, the commands get long, and the cost of a typo goes up. Typing the wrong state address is how you end up planning production against staging's state. A thin wrapper turns all of that into "which one?" plus whatever operation you actually wanted. It's also a natural place to put guard rails, like refusing to run when a leftover environment variable would point every stack at the same state.

The trick is keeping it thin. Once the wrapper starts making decisions Terraform should be making, it's become its own little framework, and now there are two things to debug.

There are lots of other ways to solve this problem; I like the wrapper technique because A)it works for me and 2)it's easier to tell someone else how to use.

GitLab for deploys

One design decision felt like a no-brainer: Terraform owns the Cloudflare resources, but it never uploads site content. Deploys are a separate script that builds the site (if it has a build step, like this one does with Eleventy) and pushes the output to Pages with Cloudflare's Wrangler CLI.

GitLab CI runs that script. Each site has its own deploy job, and a job only runs when:

  • the push is to main,
  • something under that site's directory (or the deploy tooling) changed, and
  • GitLab's SAST and secret-detection jobs have passed first.

There are two separate Cloudflare API tokens. The one Terraform uses can edit zones and DNS. The one CI uses can deploy to Pages and nothing else, so if it ever leaks, the worst someone can do is deface my CV or modify my mom's oatmeal cookie recipe, not hijack my mail. Both deploy variables are marked protected in GitLab, so only main can see them.

The cutover

Moving this site off GitHub Pages was the "scariest" part, since a botched DNS change means the site is simply gone until I fix it. (TBH, it wasn't very scary...my visitor count numbers in the high teens monthly, so downtime was not exactly something I feared...) The approach was to park the new double-wide next door to the old one first and only then move the house number:

  1. Copy the Eleventy source into the repo (minus the GitHub Actions workflow and CNAME file).
  2. Create just the Pages project with a targeted apply, and deploy the site to it, while DNS still pointed at GitHub.
  3. Check the site at its pages.dev address.
  4. Apply the rest: drop the GitHub records, point the apex and www at Pages, and switch on the www redirect.

Tidying the site while I was in there

  • A real Content-Security-Policy. The font now comes from the site itself instead of Google Fonts, the footer icons are local SVGs instead of hotlinked images, and the one inline script moved into its own file. Since everything the page loads now comes from the site, the security headers can say "this site only" and mean it.
  • The off-by-one-day bug. Post dates were formatted in the build machine's timezone, and since front-matter dates are midnight UTC, every build west of Greenwich showed posts a day early. GitHub's runners happen to use UTC, which had been hiding it. Dates are now formatted in UTC.
  • Local preview that matches production. Eleventy's dev server is ok for writing, but it ignores Cloudflare's _headers and _redirects files. npm run preview now builds the site and serves it with Wrangler, so I can test redirects and headers before pushing.

Mail, briefly

One domain moved from Namecheap forwarding to Proton Mail. Proton won't show you the DKIM records until it has verified you own the domain, so that took two passes: add the verification record, wait for Proton to notice, then swap the old mail records for the full Proton set in one change. Proton's dashboard also took a while to admit the records were correct. When in doubt, ask dig, not the dashboard.

Summing up