Site Provisioning and Procedures

Executive Summary

Standing up a Cloudflare-fronted EDS site crosses three systems that each gate the next, and the two slowest steps are ServiceNow requests that nobody on the delivery team can self-serve. The mechanical steps are already documented in eds-site-config and are not repeated here. What this page adds is the part that is not in any repo: who provisions a Cloudflare zone, how to ask for it, what the request needs as its origin, and the ordering constraints that make a first-time deploy fail if taken out of sequence.

The ordering matters because the dependency runs backwards from what you would expect: the zone request needs an origin to point at, so the worker has to exist and be deployed before the DNS zone is requested — not after. That in turn makes the Cloudflare API token a stage-0 prerequisite, since without it the first deploy fails and there is no origin URL to request a zone against.

Where each procedure lives

This site holds reasoning, ordering and cross-system context. The repo that owns a mechanism owns its commands, field names and token scopes. Start here to find the right runbook, then follow it there.

Procedure Where it lives
Spin up a new EDS site family (intake → scaffold PR → merge → deploy) Onboarding Guide, then eds-site-config/docs/onboarding.md
First worker deploy, DNS records, Lock EDS Site, smoke tests eds-site-config/docs/onboarding.md — "after the merge" steps
Request a Cloudflare zone and public DNS record This page — not documented elsewhere
Run a worker locally against a real env eds-site-config/docs/local-wrangler-dev.md
Purge the Cloudflare cache eds-site-config/docs/cache-purge.md
Move repos between GitHub orgs GitHub Org Migration
Repoless config model and site.json fields Repoless Configuration
Environments, hostnames, workers, access layers Environment Access Control
Do not copy procedures into this site
Duplicating a sequence from eds-site-config creates a second copy that drifts silently, and the stale one is indistinguishable from the current one at read time. Link to it and describe only what the link cannot tell you — the order, the prerequisites, and what breaks when a step is skipped.

The provisioning chain

Each stage below blocks the one after it. Stages 2 and 4 are ServiceNow requests with turnaround measured in days, so start them as early as the dependency allows.

0. Create the Cloudflare API token before merging the scaffold PR

This is a prerequisite, not a later step, because merging the scaffold PR is what triggers the first worker deploy — and that deploy is the only thing that can produce the origin URL stage 2 needs. Get it wrong and the chain stalls at its first link.

Two actions, and both are required:

  1. Create the repo secret. <FAMILY>_<ENV>_CLOUDFLARE_API_TOKEN for the per-env-zone topology, or <FAMILY>_CLOUDFLARE_API_TOKEN for a single shared zone. See eds-site-config README § Secrets for the required scopes.
  2. Register it in the workflow env: blocks — deploy-worker.yml ("Resolve Cloudflare API token") and deploy-cloud.yml ("Substitute secrets into staging dir"). Both read from a hardcoded env: block, so a new family's secret is invisible until a matching line is added.
The token is scoped to the account, so it does not need the zone to exist yet

This is the part that looks circular and is not. The token's deploy permission is account-scoped (Workers Scripts), so it can be created and used before any zone exists — which is exactly why a routeless worker can deploy first. Zone-scoped permissions only start mattering in stage 3, when routes bind the worker to a specific zone.

Skipping either action fails the first deploy with Missing Cloudflare token for family=..., and creating the secret without registering it fails the same way.

1. Onboard the family, and let the routeless worker deploy

Follow the Onboarding Guide. When the intake form asks "Are the custom domains ready?", answer no if the zone does not exist yet — which is the normal case for a new site.

That answer is what makes this sequence work. A "no" still scaffolds workers/routing/ and still deploys the worker; it just omits routes, leaves HOST_MAP empty, and records cloudflare.routed: false in env.yaml. The result is a routeless worker: real, deployed, and receiving no traffic.

The routeless worker is the thing that unblocks the zone request

The Cloudflare zone request needs an origin to point at, and the Cloudflare-assigned *.workers.dev URL of the deployed worker is what you give it. So deploy first, request second. Answering "yes" before the zone exists forces hostnames and 32-character zone IDs you cannot supply yet, and the form will not accept blanks.

Confirm the deploy actually ran before moving on — gh run list --workflow deploy-worker.yml --limit 5. A routeless worker deploys successfully and receives no traffic, so "green but no traffic" is the expected state here, not a failure.

2. Request the Cloudflare zone

Submit the Cloudflare request in ServiceNow:

Specify two things:

Field What to give Where it comes from
Domain The hostname to provision, e.g. mysite-dev.pdcoe.dev The env's hosts.live / hosts.preview in env.yaml
Origin Usually the Cloudflare-generated worker URL The *.workers.dev URL of the worker deployed in stage 1

Request every hostname the family needs, live and preview, for every environment. In the per-env-zone topology each hostname is its own zone — rhea runs six (rhea, rhea-preview, rhea-stage, rhea-stage-preview, rhea-dev, rhea-dev-preview, all under pdcoe.dev). A family on a single shared zone with per-env subdomains needs one zone instead. Confirm which topology applies before requesting, because it also determines whether the Cloudflare API token is per-env or family-level (see stage 3).

The completed request gives you the zone ID per hostname, which stage 3 needs.

3. Wire the routes and zone IDs

With zones in hand, convert the routeless worker into a routed one. Three files, and all three must agree:

File Add
workers/routing/wrangler.toml routes entries under [env.<env>], with zone_name matching the hostname
workers/routing/src/index.js The same hostnames in HOST_MAP
envs/<env>/env.yaml live_zone_id, preview_zone_id, and cloudflare.routed: true

The worker answers 404 for any host absent from HOST_MAP, so a route added without its matching HOST_MAP entry serves nothing — and it fails as a 404 rather than an error, which reads like a broken site rather than a missing line.

Never route or map an `*.aem.live` / `*.aem.page` host

Those hostnames belong to Adobe's zone, cannot carry our routes, and would point the worker at itself.

The Cloudflare API token is the other classic first-deploy trap, but by this stage it is already done — see stage 0. If a deploy here fails with Missing Cloudflare token for family=..., the secret exists but was never registered in the workflow's env: block.

4. Lock the site and mint the site token

Optional, and safe to run before the DNS record is published. Origin lock-down is being rolled out per environment rather than applied to every new site — of the environments in eds-site-config today, only rhea-stage carries an access.site block. A newly scaffolded env has access.admin only, so its edge URLs are reachable and nothing is waiting on a token.

Run Lock EDS Site for the envs you intend to lock. In a single run it mints the site token, stores it as the worker's SITE_TOKEN, redeploys the worker, and registers the secretId — then enables access.site.

Run this after stage 3 and before publishing DNS

The workflow has no DNS dependency: it talks to the Admin API and to wrangler, neither of which needs the public record to resolve. It does need the worker to be routed and able to forward the token, which stage 3 provides.

Doing it here means the hostname is already locked and reachable through the worker the first time it resolves publicly, so there is no window where a live hostname answers 401.

Token first, then enforcement

The ordering constraint is token before access.site: the worker sets authorization: token <SITE_TOKEN> only when that secret exists, and omits the header otherwise, so enabling enforcement first would 401 the custom hostnames too. Lock EDS Site performs both steps in that order within one run, which is why it is a single workflow rather than two steps an operator could interleave wrongly.

It also refuses to store the token when src/ does not reference env.SITE_TOKEN, since a worker that could not forward it would be locked out of its own origin.

See Environment Access Control for what the lock does, which environments currently have it, and how the four layers interact.

5. Request the public DNS record

Once the zone exists, the public DNS record is a separate ServiceNow request:

Point each live and preview hostname at Cloudflare, and state in the request that the record must be:

  • Proxied (orange-cloud) — worker routes and Zero Trust cannot intercept traffic on a grey-cloud record
  • SSL/TLS: Full (strict)
`pdcoe.dev` is corporate DNS, not Cloudflare — this cannot be self-served
pdcoe.dev is authoritative on AbbVie corporate DNS (ns1–ns4.abbviedns.com, owner domainadmins@abbvie.com). Delivery-team Cloudflare tokens carry zone (read) only, so neither wrangler nor the Cloudflare API can create a zone or write a record. Both stages 2 and 5 go through ServiceNow every time — budget for the turnaround rather than discovering it on cutover day.

6. Smoke-test

Target Expected Meaning
Custom live + preview hostnames 200 Route, HOST_MAP, DNS and (if locked) token all agree
*.aem.live / *.aem.page edge URLs 401 if stage 4 was run, otherwise 200 A locked origin rejects direct access; an unlocked one is still reachable

On a locked env, 401 at the edge URL is a pass, not a failure — it is the whole point of the lock. On an env that was deliberately not locked, 200 there is also correct, so check which state you expect before reading it as a result.

A 404 on the custom hostname usually means the host is routed but missing from HOST_MAP.

Ordering constraints worth memorising

These are the dependencies that are not obvious from any single repo, and each one has a distinct failure signature:

Constraint Consequence of getting it wrong
Cloudflare token created and registered in the workflow env: blocks, before the scaffold PR merges First deploy fails (Missing Cloudflare token for family=...), so no worker, so no origin URL for the zone request — the whole chain stalls at stage 2
Worker deploys before the zone request No origin to put on the request; it gets bounced
Zone exists before routes and zone IDs are committed No 32-char zone ID to fill in; wrangler deploy cannot bind the route
HOST_MAP entry for every routed host Worker serves 404 — looks like a broken site, not a config gap
SITE_TOKEN reaches the worker before access.site is enforced Custom hostnames 401 alongside the edge URLs. Lock EDS Site does both in this order within one run, which is why it is not two manual steps
Lock EDS Site (if locking) run before the DNS record is published A live hostname answering 401 until the lock completes. The workflow has no DNS dependency, so there is no reason to sequence it after
DNS record proxied, not grey-cloud Worker routes and Zero Trust never see the request
  • Onboarding Guide — the five-phase family onboarding this page sequences around
  • Environment Access Control — hostname-to-origin mapping, the four access layers, token management
  • Repoless Configuration — pointer into eds-site-config, the source of truth for config-as-code
  • GitHub Org Migration — the other cross-system runbook, for moving repos between orgs
On this page
h3
true