docs: update Cloudflare tunnel DNS ownership guidance

Author: xnoto

AGENTS.md

@@ -30,6 +30,7 @@ Wave 2: Workloads (CRs that depend on CRDs)
 - `openshift-ingress-operator` - IngressController CR
 - `cert-manager` - cert-manager controller pods
 - `openshift-gitops` - ArgoCD and KSOPS
+- `cloudflare-operator-system` - Cloudflare operator, tunnel deployment, DNS API secret
 
 ## Certificate Management
 
@@ -54,6 +55,16 @@ spec:
 - `ingress.config.openshift.io/cluster` - componentRoutes for console/oauth certs
 - `apiserver.config.openshift.io/cluster` - API server cert
 
+## Cloudflare Tunnel DNS Management
+
+Public `*.makeitwork.cloud` app DNS records are operator-managed from `TunnelBinding` resources.
+
+- Keep `TunnelBinding.tunnelRef.disableDNSUpdates: false` for operator-managed DNS
+- `subjects[].name` must match the real Kubernetes `Service` name in the same namespace
+- cloudflare-operator stores ownership metadata in `_managed.<fqdn>` TXT records
+- Do not delete CNAME records without deleting matching `_managed.<fqdn>` TXT records; stale TXT `DnsId` values cause reconcile failures (`81044`)
+- The old `dns-adoption-job` hook is intentionally not used
+
 ## SOPS/KSOPS Encryption
 
 Secrets encrypted with age. Each directory with secrets has a KSOPS generator file.
@@ -133,6 +144,10 @@ annotations:
 
 6. **OAuth Replace=true causes sync failures** - The `argocd.argoproj.io/sync-options: Replace=true` annotation causes ArgoCD to delete+create resources. OpenShift protects singleton resources like `oauths.config.openshift.io/cluster` from deletion. Use `ServerSideApply=true` instead for these resources.
 
+7. **Cloudflare stale TXT records break DNS reconciliation** - If `_managed.<fqdn>` TXT records point to deleted CNAME IDs, cloudflare-operator attempts update-by-stale-ID and fails with `Record does not exist. (81044)`. Remove stale `_managed.*` TXT records, then reconcile TunnelBindings.
+
+8. **TunnelBinding subject name is service lookup key** - `subjects[].name` is used to read the Kubernetes Service object. If this name does not exist, operator status falls back to `http_status:404`.
+
 ## Useful Commands
 
 ```bash

README.md

@@ -66,6 +66,16 @@ Operators must be installed before workloads to ensure CRDs exist.
 - CRC with monitoring enabled (`crc config set enable-cluster-monitoring true`)
 - `sops-age-keys` secret in `openshift-gitops` namespace (for SOPS decryption)
 
+## Cloudflare DNS Ownership
+
+Public app DNS under `*.makeitwork.cloud` is managed by cloudflare-operator from `TunnelBinding` resources in this repo.
+
+- Keep `TunnelBinding.tunnelRef.disableDNSUpdates: false` for operator-managed DNS
+- Set `subjects[].name` to the real Service name in the same namespace
+- The operator writes `_managed.<fqdn>` TXT records alongside CNAMEs for ownership tracking
+- Do not delete CNAME records without deleting matching `_managed.<fqdn>` TXT records (stale TXT `DnsId` values cause reconcile error `81044`)
+- `operators/cloudflare/dns-adoption-job.yaml` is legacy and is intentionally not referenced from `operators/cloudflare/kustomization.yaml`
+
 ## CI/CD
 
 On push to `main`, GitHub Actions: