From 9c5c20e3d1d264d51556a648269efe86043a183b Mon Sep 17 00:00:00 2001 From: xnoto Date: Tue, 25 Aug 2026 10:10:54 -0600 Subject: [PATCH] docs: document 81053 dns race and import fix --- AGENTS.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index d1eae6b..f027ac8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,26 @@ tracked copy. **Pre-commit failures:** If hooks fail unexpectedly, the canonical config may have changed. Re-run `make test` to refresh it and run the checks. +**Cloudflare API error 81053 (`record with that host already exists`) on +`cloudflare_dns_record.cluster_apps[...]`:** The `TunnelBinding` operator in +`kustomize-cluster` creates DNS records as soon as ArgoCD syncs. If a hostname +lands there before this root's apply creates it, the apply fails 81053 and the +plan could not warn about it (the record is not in state). Do not delete the +operator's record — it will be recreated. Import it instead, with +`CLOUDFLARE_API_TOKEN` and `ZONE_ID` extracted from SOPS in the same shell +(never printed): + +```bash +AWS_PROFILE=makeitwork make init +REC_ID=$(curl -fsS -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ + "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?name=" | jq -r '.result[0].id') +AWS_PROFILE=makeitwork tofu import 'cloudflare_dns_record.cluster_apps[""]' "$ZONE_ID/$REC_ID" +``` + +Then re-run the failed apply job. To avoid the race, merge this root's DNS +change before the kustomize-cluster `TunnelBinding` change when adding a new +cluster-app hostname. + ## Related Repositories - `images` - Contains tfroot-runner image and canonical pre-commit config @@ -54,6 +74,9 @@ search suffix list. ## Importing Zone Settings +For DNS records created out-of-band (for example by the `TunnelBinding` +operator), see **Failure Modes** (error 81053) instead. + Cloudflare zone-setting import IDs use `/`. Obtain the zone ID through the approved local secret workflow, then import each managed setting explicitly, for example: