Declarative, cluster-independent ownership of devantler-tech Cloudflare infrastructure, written in OpenTofu.
This repository owns resources that must survive a full platform outage or must exist before the platform can bootstrap:
- the Cloudflare zone;
- bootstrap and authoritative DNS records;
- R2 buckets and their lifecycle rules;
- least-privilege service tokens and their policy boundaries; and
- the independent R2 state backend configuration.
The platform repository owns
the in-cluster consumers and tenant boundaries. A tenant can publish and roll
forward within those boundaries without a platform revision update. Changes to
Cloudflare privileges, shared DNS, storage, or other platform boundaries are
reviewed here or in platform, according to where the resource runs.
It is configuration for one organization's account, not a reusable module. You can read it, check it locally and propose changes without any Cloudflare access. Privileged changes use the confirmed main-only bootstrap workflow; these local checks grant no deployment access (see Safety state).
This is the first thing to run, and it needs no credentials, no Cloudflare account and no state backend.
You need:
- OpenTofu 1.12.6
(
versions.tfallows 1.12.x; native recovery proofs use CI's exact runtime); - ShellCheck,
jq, and age (ageandage-keygenonPATH; CI verifies the pinned 1.3.2 release archive before using it); - Bash 5 or newer as
bashonPATH, GNU coreutilstimeout, Go, and curl with AWS V4 signing support; and - network access to
registry.opentofu.organd to GitHub's release downloads, where OpenTofu fetches the pinned Cloudflare provider on the first run.
On macOS, the system Bash 3.2 is insufficient for the native locking test. Install the additional tools with Homebrew and select them for these checks:
brew install bash coreutils
export PATH="$(brew --prefix)/bin:$(brew --prefix coreutils)/libexec/gnubin:$PATH"From the repository root:
scripts/test.shIt lints the shell scripts, runs the destructive-plan and recovery-package
guards against their fixtures, checks formatting, downloads the provider with the backend switched
off (tofu init -backend=false) and validates the configuration against the
provider's schema. On success it exits 0, and the output includes these two
lines:
PASS: destructive OpenTofu plans fail closed
Success! The configuration is valid.
The run creates a .terraform/ directory in the repository, which Git ignores
and which you can delete, and a few cloudflare-plan-*.out files in /tmp.
This check never contacts the Cloudflare API and never reads state. It shows
that the configuration is well-formed and that the guard rejects deletes and
replacements. It does not show what a plan against the live account would
change. Do not set CLOUDFLARE_API_TOKEN or backend credentials to run it.
CI runs the same script on every pull request
and on every push to main, on a GitHub-hosted runner with no production credentials.
CONTRIBUTING.md walks through a first documentation change, the local checks, and what a pull request needs before it can merge.
The configuration is deliberately import-first. The manual state-bootstrap workflow defaults to checking independent encrypted recovery publication. Its apply mode accepts only the frozen, reviewed first proposal and requires a successful custody check from that same main revision.
DNS records are declared in dns.tf, and the zone settings that would
rewrite proxied pages in zone.tf. Both change only through the
manual DNS plan and guarded apply workflow: plan first, then apply the same
reviewed revision. It imports declared records that already exist, never
deletes or replaces anything, and keeps an encrypted state copy from before and
after every apply. Other resources still have no general apply path.
The ownership decision and dependency boundary are recorded in
docs/adr/0001-cluster-independent-cloudflare-owner.md.
Inventory, import, plan against the account, state handling, apply and
recovery are privileged procedures. They need short-lived Cloudflare and state
credentials from the maintainers' private custody and are not part of local
setup or of a first contribution. They are described in
docs/runbooks/bootstrap-and-recovery.md.
The retained pre-migration DNS snapshot lives as authenticated ciphertext in
recovery/. Its recovery key is held independently in iCloud
Keychain. This historical snapshot is neither current desired configuration nor
OpenTofu state; the runbook describes its limits and recovery checks.
The paired package in recovery/state/ retains captured
OpenTofu state and its complete desired configuration. Its manifest binds both
encrypted files to their source and run. Verify authenticated recovery before
using a generation, and refresh it after each reviewed apply. Provider convergence
and remote backend locking have separate acceptance checks in the runbook.
The independently authenticated post-apply generation in
recovery/backend-source/ retains the original
imported lineage after creating the protected state bucket. The original
recovery/state/ generation remains available for the frozen first-apply path.
Neither copy means the authoritative state has moved to R2.
The confirmed state-backend-proof workflow tests native locking and recovery
using synthetic state in an isolated, run-specific prefix. It derives a
15-minute scoped storage session from the existing account token, exports only
encrypted evidence, and never opens the authoritative state key. The recovered
configuration must match the reviewed encrypted generation before any API call.
It first migrates local synthetic state with the native CLI, accepting only an
empty destination; a non-empty destination or unexpected prompt is refused without forcing.
An absent S3 destination is first initialized with a saved, provider-free,
zero-change native plan so the pinned CLI retains imported lineage on its first
write. A successful complete listing is required before trusting the native
workspace census; denied, truncated or ambiguous responses refuse the handoff.
This proof is a prerequisite to the separately guarded real-state migration;
it does not enable general applies.
The separately confirmed state-backend-migrate workflow can then copy the
authenticated frozen state into the empty production backend. It requires a
successful synthetic proof from that exact main revision, refuses overwrites,
and checks recovery on a separate GitHub-hosted runner. It performs no resource
apply. Its encrypted recovery capture must be authenticated independently and
retained in the repository before this migration is accepted or general applies
are introduced; the expiring artifact alone is not permanent custody.
In those procedures the provider reads CLOUDFLARE_API_TOKEN, and the state
backend reads the standard AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
variables. Keep all three out of shell history and plaintext repository files.
Short-lived storage sessions also require AWS_SESSION_TOKEN.
Dependabot proposes updates to the Cloudflare provider and to the GitHub
Actions this repository uses, as configured in .github/dependabot.yml. For
the provider it uses its OpenTofu support, which also refreshes the provider
checksums in .terraform.lock.hcl. Provider versions remain exact pins. A new
third-party release waits seven days before Dependabot proposes it as a version
update; the wait does not apply to Dependabot security updates, which GitHub
offers for the Actions but not for OpenTofu providers. Updates require the
existing CI and review gates and are never auto-merged.
The OpenTofu runtime stays on the reviewed 1.12.x line; no updater changes it.
Every provider proposal must pass scripts/test.sh, including the
destructive-plan guard. Dependency automation has no production credentials or
apply path.