# Domains

Every instance gets a subdomain on `dishonkadoh.com`, provisioned and
verified automatically via Cloudflare — administrators don't touch DNS by
hand under normal operation, but this page covers what's happening under
the hood, since it's the piece most likely to need debugging.

## How a domain gets created

`saas.provisioner` talks to the Cloudflare API (`CF_DNS_API_TOKEN`,
`CLOUDFLARE_ZONE_ID`) at the DNS-configuration step of provisioning:

- **Kubernetes backend** — creates/updates a **CNAME** record pointing at
  the ALB's auto-generated hostname (`create_cloudflare_dns_record`). Since
  a fresh Ingress means a brand-new ALB each time, this is re-synced on
  every reprovision, not just first creation.
- **Docker backend** — creates an **A** (or CNAME, if
  `DOCKER_HOST_PUBLIC_ADDRESS` isn't a bare IP) record pointing straight at
  the Docker host's public address, since there's a single known host
  rather than a load balancer to wait on.

Both paths immediately re-query Cloudflare afterward
(`verify_cloudflare_dns_record*`) and raise if the record doesn't actually
point where it should — provisioning fails loudly here rather than leaving
a half-configured domain.

## Routing once DNS resolves

- **Kubernetes** — an ALB Ingress (`alb.ingress.kubernetes.io/*`
  annotations) terminates TLS using a fixed ACM certificate ARN, with
  `ssl-redirect: 443` and a `/` health check expecting `200`–`399`.
- **Docker** — Traefik labels on the container itself do the routing:
  `Host(`<subdomain>.dishonkadoh.com`)` on the `websecure` entrypoint, TLS
  via the configured cert resolver (`DOCKER_TRAEFIK_CERTRESOLVER`,
  defaulting to `letsencrypt`). There's no separate ingress object to
  create on this backend — the container *is* the routing config.

## Troubleshooting a domain that won't resolve

- Confirm `CF_DNS_API_TOKEN` and `CLOUDFLARE_ZONE_ID` are set — both raise
  immediately if missing.
- On Kubernetes, DNS creation waits on the ALB controller to hand back a
  hostname (`_k8s_wait_alb_hostname`, 120s timeout) — if that times out,
  the Ingress itself likely isn't reconciling; check the ALB controller
  logs before suspecting Cloudflare.
- A record that exists but points at the wrong target is updated in place,
  not duplicated — if verification still fails after that, the most likely
  cause is DNS propagation delay rather than a misconfigured record.