Custom-domain TLS verification

After Terraform applies a cloudflare_pages_domain (e.g. docs.nowyourlink.com via PR #65), Cloudflare provisions a managed TLS certificate. The window between “domain attached” and “cert active + serving” is typically 1–10 minutes but can extend. This runbook is the checklist when a custom-domain change does not serve correctly.

Prerequisites. This runbook assumes PR #65 (Cloudflare Pages Terraform) has merged — that PR introduces the cloudflare_pages_domain.docs resource and the docs_pages_domain_status output the verify step uses. Before #65 merges, the step-1 command will error with Warning: No outputs found; use the resource fallback below.

Verify

1. Check the Terraform output. From infra/terraform/:

   terraform output docs_pages_domain_status

   Expected: active. Anything else means cert provisioning has not finished — see status meanings below.

   Resource fallback (before PR #65 merges)

   If terraform output reports no matching output, the named output hasn’t been added yet. Query the resource directly:

   terraform state show 'cloudflare_pages_domain.docs' | grep -E '^\s*status\s*='

   Same expected value (active). If the resource itself isn’t in state yet, neither the project nor the domain has been provisioned — re-check terraform plan and the apply log.

2. Check the CNAME resolves. From any machine:

   dig +short docs.nowyourlink.com

   Expected: a Cloudflare anycast IP (resolves via the proxied apex). If you see nowyourlink-docs.pages.dev instead of an IP, the apex zone is not proxying — check the cloudflare_dns_record.docs proxied = true setting.

3. Check the cert. From any machine:

   curl -sI https://docs.nowyourlink.com | head -3
   echo | openssl s_client -connect docs.nowyourlink.com:443 \
     -servername docs.nowyourlink.com 2>/dev/null \
     | openssl x509 -noout -issuer -subject -dates

   Expected: HTTP 200 + a lets_encrypt or google issuer per the certificate_authority set on cloudflare_pages_domain.

Status meanings

status value	What it means	What to do
initializing	Domain just attached; CF has not started cert issuance	Wait 2 min; re-check
pending	Cert issuance in progress	Wait up to 10 min; re-check
active	Cert issued and serving	Done
deactivated	Domain manually deactivated in the CF dashboard	Re-activate via Terraform reapply, or in dashboard
blocked	Cert issuance refused by CF (likely a CAA record or zone-level policy)	See troubleshoot
error	Issuance failed	Check terraform refresh and verification_data.error_message in the resource state

Troubleshoot

If status is blocked or error after 30 minutes:

1. CAA records. A CAA record on the apex zone that doesn’t authorise letsencrypt.org or pki.goog will block issuance. Check with dig CAA nowyourlink.com +short. Either remove the CAA or add an entry for the cert authority.
2. Validation method. cloudflare_pages_domain.docs.validation_data.method returns http or txt. For txt, ensure a temporary TXT record at _cf-pages-verify.docs.nowyourlink.com exists (CF normally writes it itself when the zone is on the same account — confirm with dig TXT _cf-pages-verify.docs.nowyourlink.com).
3. Zone mismatch. The custom hostname’s apex zone must be on the same Cloudflare account as the Pages project. Cross-account custom hostnames need extra setup.
4. proxied toggle. If cloudflare_dns_record.docs.proxied = false slipped through, the edge can’t terminate TLS — flip it back to true and re-apply.

Escalate

After two terraform refresh/wait cycles (~30 min total) with no active:

• Open a Cloudflare support ticket with: the Pages project name (nowyourlink-docs), the custom hostname, verification_data.error_message, and the timestamps of the most recent terraform apply.
• Notify #oncall-infra so anyone tracking the rollout knows TLS is the blocker.

See also

• Deploy — full path-to-prod context
• Incident response — if the docs site is user-visible-down for > 5 min
• PR #65 — the Pages project + custom-hostname Terraform that triggers this checklist on first apply
• Spec 11 §7 — Docs Site CF Pages deployment