Dynamic DNS (System App)

What you see

URL: /network (DDNS tab)

The Dynamic DNS (DDNS) system app is always installed in PodWarden. It runs entirely server-side — no Kubernetes deployment is required. Every five minutes it checks the public IP of each gateway host and, if the IP has changed, updates DNS records with each configured provider.

DDNS configurations are managed from the Network page on the DDNS tab. A configuration links one gateway host to one DNS provider, and controls which domain names get updated.

How DDNS fits into PodWarden's network model

PodWarden's network model has three layers that work together:

The DDNS system app bridges the first two layers: when the gateway's IP changes, DDNS updates the domain's A record so traffic continues to reach the right host.

DDNS provider list

DDNS config fields

Status badges

Available actions

Adding a Cloudflare provider

Cloudflare is the recommended provider because PodWarden can fetch and validate your A records directly from the API.

1. Click + Add Provider on the Network DDNS tab.
2. Enter a Name (e.g. example.com on gateway-01).
3. Select Cloudflare as the provider.
4. Enter your Zone ID (found in the Cloudflare dashboard under your domain's overview).
5. Enter your API token (needs Zone:DNS:Edit permission for the target zone).
6. Enter domains manually, or click the search icon to fetch existing A records from Cloudflare and select them with one click.
7. Select the Gateway host whose IP should be tracked.
8. Click Add Provider.

After saving, PodWarden automatically imports the zone's base domain into the Domains table and links it to this DDNS config.

Auto-discovery

PodWarden runs an auto-discovery step on every 5-minute check cycle. It looks for gateway hosts that have Cloudflare-managed domains in their ingress rules but no DDNS config, then creates one automatically if a matching Cloudflare API token can be found in an existing config for that zone.

Auto-created configs are named Auto: <domain> on <gateway> and are enabled immediately.

If no existing config with credentials for that zone can be found, auto-discovery skips the gateway and logs a warning. You will also see a "Gateway: Cloudflare domains without DDNS" warning in System Messages.

IP detection strategy

For each gateway host, PodWarden detects the public IP using this priority order:

1. hosts.public_ip — if a cached public IP is stored for this host
2. SSH to the gateway and run an IP detection command
3. Third-party IP detection services (ifconfig.me, api.ipify.org, icanhazip.com), with PodWarden Hub's /api/v1/ip endpoint first if Hub is configured

All configs for the same gateway host share a single IP detection call per cycle — PodWarden does not make redundant requests.

Update cycle

The background loop runs every 5 minutes. Within each cycle:

1. Auto-discovery runs and creates any missing configs.
2. For each enabled config, PodWarden checks whether the gateway's current IP differs from the last recorded IP.
3. If the IP has changed, the provider's DNS API is called to update the record.
4. If the IP is unchanged, the cycle skips the config with no API call.

The loop starts 30 seconds after PodWarden boots to allow the database connection pool to initialize.

Health monitoring

The DDNS system app registers health checks that run alongside PodWarden's standard 15-minute infrastructure audit:

These appear on the System Messages page under the DDNS category. Fixing the underlying issue (bad credentials, unreachable gateway, stopped background loop) will auto-resolve the message on the next clean check cycle.

Related docs

• Settings: DDNS — The settings tab that also exposes DDNS configuration
• Zones — Network zones for grouping gateway hosts
• Ingress — Ingress rules that use DDNS-managed domains
• System Messages — DDNS health check alerts