From ce1c2dd537ccb88feaa01911b4dee4912b3566c5 Mon Sep 17 00:00:00 2001 From: xnoto Date: Wed, 6 May 2026 11:40:41 -0400 Subject: [PATCH] docs: record WARP DNS search-domain limitation Cloudflare's "DNS suffix search lists" feature is in development; no provider/API surface yet. Document the trap (local_domain_fallback doesn't push search domains) and signals to watch for the blocker lifting, so future agents don't redo the research. Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index a108690..5a0b2f9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,3 +35,33 @@ This repo uses the shared `opentofu.yml` workflow from `shared-workflows`. It ru - `images` - Contains tfroot-runner image and canonical pre-commit config - `shared-workflows` - Contains the reusable OpenTofu workflow and canonical pre-commit config + +## Known Limitations + +### WARP cannot push DNS search domains (as of 2026-05) + +Investigated whether the `warp-connector` tunnel + Zero Trust device profile could push `makeitwork.cloud` as an OS-level DNS search domain so `ssh hero` resolves to `hero.makeitwork.cloud` while WARP is connected, and is removed on disconnect. + +**Conclusion: not possible today.** Cloudflare documents the feature as in development: +> "Support for DNS suffix search lists in the Cloudflare One Client is currently in development." +> — https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/route-traffic/#add-a-dns-suffix + +Workaround they recommend is per-device manual config (System Settings → Network → DNS → Search Domains on macOS, equivalents elsewhere). + +#### What does NOT solve it + +`cloudflare_zero_trust_device_default_profile_local_domain_fallback` (and the per-profile variant) only changes **which resolver handles `*.suffix` queries** — it does **not** add the suffix to the OS search list. WARP installs a local DNS proxy that handles whatever the OS sends; if the OS hasn't expanded `hero` → `hero.makeitwork.cloud` (which needs a search domain), WARP never sees the FQDN. Don't add this resource thinking it fixes the shortname problem — it won't. + +(Local Domain Fallback may still be worth adding for unrelated reasons — keeping internal-only hostnames out of Gateway logs, or pointing them at a private resolver — but it's a separate concern.) + +#### Watch for these signals that the blocker has lifted + +Revisit when any of these appear: + +1. The Cloudflare docs page above stops saying "in development" and adds a Dashboard / API / Terraform tab for "DNS suffix search lists" (or similar — Cloudflare may name it "Override search domains" or "Search domain list"). +2. The `cloudflare/cloudflare` Terraform provider gains a new attribute on `cloudflare_zero_trust_device_default_profile` / `..._device_custom_profile` — likely named `dns_search_domains`, `search_domains`, `match_domains`, or similar. Grep the provider changelog: https://github.com/cloudflare/terraform-provider-cloudflare/blob/main/CHANGELOG.md +3. A new top-level Terraform resource appears under `docs/resources/` matching `zero_trust_device_*_search*` or `zero_trust_device_*_dns_suffix*`. +4. The WARP MDM XML schema (https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/deployment/mdm-deployment/parameters/) gains a `search_domains` / `dns_suffix` key — usually the API/Terraform support follows shortly after. +5. Cloudflare changelog / blog announces the feature: https://developers.cloudflare.com/cloudflare-one/changelog/ + +When it lands, the fix is small: add the new attribute (or new resource) to `cf-warp.tf`, scoped to the makeitworkcloud-admins group, with `makeitwork.cloud` in the search list. Verify on a test device that `scutil --dns` (macOS) shows `makeitwork.cloud` in the search domains while WARP is connected and that the entry disappears on disconnect.