Skip to content

About

Declarative, cluster-independent Cloudflare infrastructure for devantler-tech

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

cloudflare

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).

Check the configuration locally

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.tf allows 1.12.x; native recovery proofs use CI's exact runtime);
  • ShellCheck, jq, and age (age and age-keygen on PATH; CI verifies the pinned 1.3.2 release archive before using it);
  • Bash 5 or newer as bash on PATH, GNU coreutils timeout, Go, and curl with AWS V4 signing support; and
  • network access to registry.opentofu.org and 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.sh

It 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

CONTRIBUTING.md walks through a first documentation change, the local checks, and what a pull request needs before it can merge.

Safety state

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.

Operating the live resources (maintainers)

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.

Dependency updates

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.

About

Declarative, cluster-independent Cloudflare infrastructure for devantler-tech

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages