Platform admin Terraform — pre-apply checklist
Use this before every Platform admin Terraform apply that updates home-dashboard-platform Pages env (GitHub Actions Platform admin Terraform, local terraform apply -target=module.platform_admin[0], or full platform stack apply).
Related: Platform admin · Grafana dashboards · Account plans & Stripe · hub.tfvars.example
Why this exists
Platform admin Terraform replaces the entire home-dashboard-platform Pages production env_vars map. Any value missing from the input Terraform sees is removed from Cloudflare — including keys you only set in the dashboard.
Repeat incidents:
- Grafana Workers AI / Cloudflare billing panels empty —
PLATFORM_CF_API_TOKENmissing from the apply input. - Grafana OpenAI panels
NOT_CONFIGURED—PLATFORM_OPENAI_ADMIN_KEYmissing while fixing unrelated Stripe vars. - Grafana GitHub Actions usage
configured: false—platform_github_billing_tokenmissing fromhub.tfvarson a local apply (or the GitHub secret missing on a workflow apply). - Stripe checkout 503 —
STRIPE_*missing during apply.
Two apply paths (do not mix them up)
| Path | What Terraform reads | Where secrets must exist |
|---|---|---|
| GitHub Actions — workflow Platform admin Terraform | generate-hub-tfvars.mjs → hub.generated.tfvars built from GitHub Actions secrets on the runner | Repo Settings → Secrets and variables → Actions. Local hub.tfvars is not used. |
Local laptop — terraform apply -var-file=environments/hub.tfvars | Your local terraform/environments/hub.tfvars (and optional hub.generated.secrets.tfvars.json) | Same values as GitHub must be uncommented and pasted into hub.tfvars. Secrets only in GitHub are invisible to local apply → Terraform drops those Pages keys. |
There is no automatic GitHub → hub.tfvars sync script. For local apply:
- Open GitHub secret in the browser (or
gh secret list— values are not readable via CLI). - Copy each value into the matching commented line in hub.tfvars.example (master GitHub secret → hub.tfvars variable section).
- Save as
terraform/environments/hub.tfvars(gitignored — never commit).
After editing locally, push secrets back to GitHub when needed:
node scripts/sync-hub-tfvars-to-github-secrets.mjs --repo marklovely/home-dashboard --profile provision1. GitHub Actions secrets (repo: home-dashboard)
Confirm these are non-empty before dispatching Platform admin Terraform (the workflow blocks apply if Grafana secrets are empty; Stripe rows can still wipe if unset):
| Secret | hub.tfvars key (local apply) | Pages env |
|---|---|---|
PLATFORM_CF_API_TOKEN | platform_cf_api_token | PLATFORM_CF_API_TOKEN |
PLATFORM_OPENAI_ADMIN_KEY | platform_openai_admin_key | PLATFORM_OPENAI_ADMIN_KEY |
PLATFORM_GITHUB_BILLING_TOKEN (or legacy GH_BILLING_TOKEN) | platform_github_billing_token | PLATFORM_GITHUB_BILLING_TOKEN |
STRIPE_SECRET_KEY | stripe_secret_key | STRIPE_SECRET_KEY |
STRIPE_WEBHOOK_SECRET | stripe_webhook_secret | STRIPE_WEBHOOK_SECRET |
STRIPE_PRICE_ID | stripe_price_id | STRIPE_PRICE_ID |
STRIPE_PRICE_ID_YEARLY | stripe_price_id_yearly | STRIPE_PRICE_ID_YEARLY |
STRIPE_PRICE_ID_FREE | stripe_price_id_free | STRIPE_PRICE_ID_FREE |
MARKETING_MAINTENANCE_MODE (true / 1) | marketing_maintenance_mode | MARKETING_MAINTENANCE_MODE |
MAINTENANCE_BYPASS_SECRET | maintenance_bypass_secret | MAINTENANCE_BYPASS_SECRET |
Full mapping (Turnstile, Resend, account Stripe prices, archive secret, etc.): hub.tfvars.example.
Marketing maintenance: Prefer Platform settings → Maintenance on platform.lovely-home.co.uk (persists in D1). Terraform/CI vars above keep Pages env in sync when you need env-based enablement or a bypass secret; a missing marketing_maintenance_mode line on apply does not turn off maintenance that was enabled via the dashboard (D1 wins once set).
Account plan prices (optional until checkout ships): STRIPE_ACCOUNT_PRICE_* ↔ stripe_account_price_* — see Account plans §2.
2. Local apply parity check
Before terraform apply on a laptop:
- [ ]
platform_cf_api_tokenandplatform_openai_admin_keyare set in hub.tfvars (not only in GitHub). - [ ] Stripe block matches GitHub secrets you rely on in production.
- [ ]
export CLOUDFLARE_API_TOKEN=...for Terraform API (often same token asplatform_cf_api_token, but stored separately).
generate-hub-tfvars.mjs logs warnings when Grafana env vars are empty. Local apply is not blocked — CI is blocked for empty Grafana secrets.
3. Verify scripts (after apply)
From a machine with API access:
bash scripts/verify-platform-ai-usage-pages-env.sh # Grafana AI usage Pages env (token + provider keys)
bash scripts/verify-grafana-platform-api.sh # Infinity auth + live GET /api/platform/ai-usage
bash scripts/verify-platform-stripe-env.sh # Hub signup Stripe + account price slots
bash scripts/verify-platform-billing-env.sh # Billable usage API token scopesFix missing slots in the path you used (GitHub secrets or hub.tfvars), then re-apply — do not rely on manual Pages dashboard edits (next apply overwrites them).
4. Grafana-specific
- Infinity headers (Access service token) are separate from Pages env — see Grafana dashboards.
- After apply, spot-check Lovely Home — AI usage and Cloudflare Billing dashboards; empty Workers AI almost always means
PLATFORM_CF_API_TOKENdropped.
5. When dashboards can wait
If you intentionally omit Grafana secrets for a one-off Access/DNS change, do not run Platform admin Terraform against Pages env — use a narrower target or restore secrets first. Skipping Grafana secrets guarantees panel regression on the next full platform apply.