N
Nanami Docs
Browse docs
Browse docs
Browse docs

Gateway endpoint DNS modes

Configure generic gateway runtime endpoint DNS for manual and Cloudflare-managed deployments.

Section
Browse docs
Path
/deployment/gateway-endpoint-dns-modes

Good for

SaaS and Community operators configuring gateway runtime exposure.

What you get

You can choose a gateway endpoint DNS mode without accidentally proxying WireGuard, GRE, or future runtime protocols through an unsupported HTTP proxy.

Before you start

A gateway-daemon host with a public origin address or operator-managed endpoint · Control-plane and gateway-manager connectivity

Gateway endpoint DNS is a generic runtime endpoint contract owned by control-plane's platform DNS manager. WireGuard, GRE, and future runtime protocols consume the same gateway hostname with protocol-specific ports or transports.

Gateway public IP is operator-provided in this release. Nanami does not auto-detect the public IP because outbound IP detection can be wrong for NAT, load balancers, routers, Kubernetes services, floating IPs, and cloud firewall setups.

Do not put ordinary gateway runtime endpoints behind an HTTP/CDN proxy unless a UDP-capable or protocol-capable gateway product is explicitly configured and validated.

Modes

| Mode | Owner | Provider calls | Use when | | --- | --- | --- | --- | | manual | Operator | No | Endpoint DNS, host, or public IP is configured outside Nanami. This is the default. | | cloudflare | Control-plane | Yes | Nanami should create/update DNS-only Cloudflare records. |

manual is the default. cloudflare is always managed DNS automation and requires Cloudflare credentials.

Environment contract

env
NANAMI_GATEWAY_ENDPOINT_DNS_MODE=manual

CLOUDFLARE_API_TOKEN=
CLOUDFLARE_ZONE_ID=

NANAMI_DNS_BASE_DOMAIN=example.com
NANAMI_DNS_GATEWAY_HOST_TEMPLATE=gateway-daemon-{gateway_id_short}-{env}
NANAMI_DNS_TTL=60
NANAMI_DNS_ALLOW_IPV6=false
NANAMI_DNS_DELETE_ON_GATEWAY_DELETE=false

NANAMI_GATEWAY_PUBLIC_IP=
NANAMI_GATEWAY_PUBLIC_IPV6=
NANAMI_GATEWAY_ENDPOINT_PORT=51820

Cloudflare variables are required only when mode is cloudflare. Manual deployments must boot without Cloudflare credentials. Cloudflare credentials are read only by control-plane. They must not be passed to gateway-daemon, gateway-manager, frontend apps, CLI, docs, or support artifacts. NANAMI_GATEWAY_PUBLIC_IP is the authoritative IPv4 origin for endpoint DNS records. NANAMI_GATEWAY_PUBLIC_IPV6 is used only when NANAMI_DNS_ALLOW_IPV6=true.

Host templates

The default template is flat and free-tier DNS friendly:

env
NANAMI_DNS_GATEWAY_HOST_TEMPLATE=gateway-daemon-{gateway_id_short}-{env}

With NANAMI_DNS_BASE_DOMAIN=example.com, gateway 9dd1cd6b-312f-4cb2-9ec3-60fd78c30758, and environment s-nanami, the runtime hostname is:

txt
gateway-daemon-9dd1cd6b312f-s-nanami.example.com

Advanced deployments may use nested templates:

env
NANAMI_DNS_GATEWAY_HOST_TEMPLATE=gw-{gateway_id_short}.gw.{env}

Template variables:

| Variable | Meaning | | --- | --- | | {gateway_id} | Full gateway worker ID | | {gateway_id_short} | DNS-safe short gateway ID | | {env} | Deployment environment label | | {region} | Gateway region label | | {tenant_id} | Tenant ID, when available | | {network_id} | Network ID, when available |

Generated hostnames and Cloudflare-managed hostnames must stay inside NANAMI_DNS_BASE_DOMAIN. Manual mode uses the same generated hostname; the operator creates the DNS record outside Nanami.

Manual mode

In manual mode, Nanami reports the required DNS record and validates what it can resolve.

txt
Type     A
Name     gateway-daemon-9dd1cd6b312f-s-nanami.example.com
Content  <NANAMI_GATEWAY_PUBLIC_IP>
Proxy    DNS only / not proxied

Runtime surfaces show whether the record is missing, points at the wrong origin, appears proxied, or is ready. If NANAMI_GATEWAY_PUBLIC_IP is missing, the gateway process can register but it is not dataplane-ready.

Use manual mode when DNS is managed outside Nanami or when an external automation system owns records. Nanami still computes the expected hostname from NANAMI_DNS_GATEWAY_HOST_TEMPLATE and NANAMI_DNS_BASE_DOMAIN; NANAMI_GATEWAY_PUBLIC_IP is the record content, not a hostname override.

Cloudflare mode

Cloudflare mode creates or updates DNS-only records from control-plane. The Cloudflare token should be scoped to the target zone and DNS edit permissions only. Do not use broad account tokens.

env
NANAMI_GATEWAY_ENDPOINT_DNS_MODE=cloudflare
CLOUDFLARE_API_TOKEN=<zone-dns-edit-token>
CLOUDFLARE_ZONE_ID=<zone-id>
NANAMI_GATEWAY_PUBLIC_IP=203.0.113.10

Nanami always writes gateway endpoint records with proxying disabled. Control-plane queries the exact record name and still creates the exact DNS-only record when a wildcard currently resolves the hostname through a Cloudflare proxy. Provider errors are redacted before they appear in Company Runtime, Community Runtime, CLI, or support artifacts. If NANAMI_GATEWAY_PUBLIC_IP is missing, Nanami does not call Cloudflare and reports the missing public IP issue instead.

Gateway-daemon is not a DNS automation actor. It reports dataplane capabilities, listener state, health, and observed runtime metadata. It must not receive Cloudflare credentials and must not create, update, or delete DNS records.

Runtime status

Gateway Runtime, Problem Center, and CLI diagnostics can report:

| Status | Meaning | | --- | --- | | endpoint_dns_only_direct | Endpoint resolves directly to the expected origin. | | endpoint_proxied_protocol_unsupported | Endpoint appears proxied and may not support gateway protocols. | | endpoint_missing_record | The expected DNS record is missing. | | endpoint_wrong_ip | DNS resolves, but not to the expected origin. | | endpoint_public_ip_missing | NANAMI_GATEWAY_PUBLIC_IP is missing or not public. | | endpoint_dns_sync_failed | Managed DNS sync failed. | | endpoint_ipv6_mismatch | IPv6 is enabled but AAAA does not match. | | endpoint_not_configured | Endpoint host/template configuration is incomplete. |

Protocol-specific health remains separate. For example, a WireGuard UDP endpoint can be DNS-correct while UDP 51820 is blocked by firewall or cloud networking.

Gateway route-domain safety

Endpoint health is not the same as isolation safety. A gateway can have a correct DNS endpoint and still be unsafe for production shared multi-tenant dataplane use.

Gateway sharing is not controlled by operator isolation toggles. Nanami gateways are platform dataplane workers. They may serve multiple tenants and networks only when the runtime reports the capabilities needed for safe route domains:

  • per-network WireGuard or GRE interfaces,
  • route-domain isolation for tenant/network routing tables,
  • packet-time source+destination ACL enforcement,
  • protocol support for the network,
  • endpoint readiness and health target readiness,
  • capacity for additional route domains and peers,
  • current desired/applied reconcile generation.

If those capabilities are missing, the gateway can remain process-healthy but is not dataplane-ready for that route domain. Overlapping CIDRs are allowed only across isolated route domains. GRE fails closed when route-domain isolation is unavailable. Endpoint DNS mode remains separate from route-domain safety.

Community deployments can use manual or Cloudflare endpoint DNS modes without requiring Cloudflare. Operators still need a public origin IP or hostname and firewall/port forwarding for inbound WireGuard UDP/GRE as configured.

Protocol restrictions

WireGuard on SaaS managed gateways must use per-network interface truth. Single-interface peer merge is not dataplane-ready for shared SaaS gateway use.

GRE is disabled on shared SaaS gateways until route-domain isolation is implemented. GRE has no port-level separation, so it is safe only in a single-network or carefully controlled single-tenant/self-hosted topology unless future VRF/network namespace isolation is available.

Overlapping network CIDRs may exist in different deployments or future route domains, but they must not be assigned to the same gateway route domain in the current release.

Readiness fields

Runtime surfaces should keep these states separate:

| Field | Meaning | | --- | --- | | Process registered | The worker registered with control-plane. | | Process healthy | The worker is heartbeating and can report runtime state. | | Endpoint DNS ready | The advertised gateway endpoint resolves to the expected public origin. | | Dataplane configured | WireGuard/GRE runtime metadata and health target are present. | | Isolation safe | The assignment respects isolation mode, CIDR, protocol, and interface-mode guards. | | Protocol ready | The selected protocol is allowed for the current isolation mode. | | Health target ready | The canonical tunnel health target responds or equivalent observed proof exists. |

Do not treat ready healthy as production dataplane readiness when any endpoint, isolation, protocol, or cleanup check is failing.

Troubleshooting

  • Public IP missing: set NANAMI_GATEWAY_PUBLIC_IP to the inbound gateway origin address.
  • DNS points to the wrong IP: update the A record to match NANAMI_GATEWAY_PUBLIC_IP.
  • DNS is proxied: switch the record to DNS-only or configure a protocol-capable proxy.
  • WireGuard unavailable: forward UDP NANAMI_GATEWAY_ENDPOINT_PORT to the gateway host.
  • GRE unavailable: allow IP protocol 47 when GRE is enabled.
  • Route-domain missing: provision a gateway runtime that can isolate tenant/network route domains.
  • ACL missing: enable packet-time source+destination ACL enforcement before serving shared route domains.
  • Overlapping CIDR: move the network to a different gateway route domain.
  • Stale peer cleanup failed: remove the gateway from dataplane service until desired/applied runtime state reconciles.
  • NAT/LB/homelab/Kubernetes: use the address clients actually reach from the internet, not pod/container/private node IPs.

Continue

Choose the most useful continuation instead of a random article.

Domain and URL strategyCommunity self-hosted deployment