Hub DDNS Subdomains

Overview

PodWarden Hub provides managed DDNS subdomains, which is the fastest way to get a public URL for your self-hosted workloads. You don't need a DNS provider account, an API token or any zone configuration: connect to Hub, allocate a subdomain, and your workload is reachable from the internet.

On the Pro and Enterprise plans you can also bring your own domain. You add a Cloudflare zone you own, and Hub keeps A records in that zone pointed at your instances. See Your own domains.

How It Works

1. Hub manages a pool of parent domains in Cloudflare. If your organization brought its own domains, those are included too.
2. Your PodWarden instance allocates a subdomain, for example swift17.<parent domain>.
3. PodWarden detects its public IP every 5 minutes and pushes it to Hub.
4. Hub creates the Cloudflare A record on the first push and updates it on every push after that.

The DNS records are set to DNS-only mode (not proxied through Cloudflare), so your gateway node handles TLS itself through Let's Encrypt. Records are IPv4 A records with a 300-second TTL.

Allocating a Subdomain

From PodWarden (Recommended)

1. Go to Settings > Hub in your PodWarden instance
2. Make sure Hub is connected (URL and API key configured)
3. Scroll to the Hub DDNS Subdomains section
4. Click Allocate
5. Select a domain from the dropdown
6. Optionally enter a custom slug (Pro and above on PodWarden domains; any plan that has own domains on yours)
7. Click Allocate

Your subdomain is created immediately and appears in the list.

From Hub Dashboard

1. Sign in at www.podwarden.com
2. Go to Dashboard > DDNS
3. Click Allocate Subdomain
4. Select a domain. Your domains are listed first, then PodWarden domains.
5. Optionally enter a custom slug, then click Allocate

Note: a subdomain allocated from the Hub dashboard still needs your IP pushed to it. A PodWarden instance does this automatically when you use the Settings > Hub method.

Subdomain Naming

Auto-Generated (All Plans)

By default, subdomains are auto-generated using a word + number pattern, such as swift17, pulse42 or echo8.

Names are short, memorable, and guaranteed unique. The generator picks from ~200 common words and appends a random number 1-99.

Custom Slugs on PodWarden domains (Pro and Above)

On paid plans you can choose your own slug, such as myapp or homelab.

Custom slug rules on PodWarden domains:

• 3-30 characters
• Lowercase letters, numbers, and hyphens only
• Cannot start or end with a hyphen
• Certain reserved words are blocked (e.g. www, api, admin, mail)

On your own domains the rules are looser, because the zone is yours. See Names on your own domain.

Managing Subdomains

Viewing Status

Each subdomain shows:

• FQDN: the full domain name
• IP Address: the current A record value
• Status: active, pending, error, or suspended
• Last Updated: when the IP was last pushed
• Slug Type: auto or custom

Updating IP

From PodWarden (Settings > Hub > DDNS Subdomains):

• Click the wifi icon on any subdomain to push your current public IP
• The DDNS update loop also does this automatically every 5 minutes

From Hub Dashboard:

• IP updates happen when your PodWarden instance pushes them via the API

Releasing a Subdomain

1. Click the trash icon on any subdomain
2. Confirm the release
3. The Cloudflare A record is deleted and the subdomain becomes available again

A released subdomain on a PodWarden domain frees up your quota, and another organization can claim the same name later. Don't rely on a released name staying yours. On your own domain, only your organization can ever allocate names.

Your own domains

Pro and Enterprise organizations can add a Cloudflare zone they own, for example example.com. Hub then manages A records such as home.example.com in that zone, the same way it does on PodWarden domains.

This is the plan feature called Bring your own domain. An older version of these docs described a different feature under that name: pointing your domain at a Hub subdomain with a CNAME. That CNAME variant is not offered.

Who can manage them

• Owners and admins of an organization can add, re-verify, pause, resume and remove domains, and replace their tokens.
• Members can see the domains and allocate subdomains on them, but cannot change them.
• A PodWarden instance's Hub API key can list and allocate on your domains, but it can never add a domain or read its token.

Create the Cloudflare API token

In Cloudflare, open My Profile → API Tokens → Create Token → Create Custom Token and set:

Don't grant "All zones" or any account-level permissions. An expiry date (TTL) is fine: when the token expires, the daily check marks it rejected and the dashboard asks you to replace it.

Add the domain

1. Go to Dashboard > DDNS and find Your domains
2. Click Add domain
3. Enter the zone name (example.com, not a name inside it) and paste the token
4. Paste the Zone ID only if your token lacks Zone → Zone → Read
5. Click Verify and add

Before saving anything, Hub checks that the token is active, that it controls exactly this zone, and that it can write DNS records. It proves the last point by creating a temporary _podwarden-verify TXT record and deleting it again. The token is stored encrypted and is never shown again, not even to PodWarden staff through the dashboard.

Common errors when adding:

PodWarden's own domains can't be added as an organization domain.

Names on your own domain

• No subdomain limit, and names on your own domains don't count toward your plan's DDNS subdomain quota
• Any single DNS label of 1-63 lowercase letters, digits and hyphens. No reserved words: www is fine.
• A records only (IPv4)
• Not supported: multi-level names (a.b.example.com), the zone apex (example.com itself), wildcards, and AAAA (IPv6) records

Token problems

Hub notices a dead token in two ways. A failed IP push reports the rejection immediately, and a daily read-only check (it makes no DNS writes) re-tests every stored token. When a token is rejected:

• The domain shows Token rejected and a red banner appears at the top of the DDNS page
• Existing A records keep answering with the last IP; only updates stop
• Replace token verifies the new token. The next update cycle then heals every subdomain that was in error, with nothing else to do.

Pausing and removing

• Pause stops new subdomains being allocated on that domain. Existing subdomains keep receiving IP updates. Resume allows allocation again.
• Remove releases every subdomain on the domain, deletes their A records from your zone, and deletes the stored token. The confirmation tells you how many records will be deleted. Nothing else in your zone is touched.
• If PodWarden staff disable your domain, it shows Disabled by PodWarden and can't be resumed from your organization. Contact support.

Downgrades and leaving

• Downgrading to Free freezes your domains. The cards show Frozen (plan), new allocations and IP updates are refused, and your records stay in your zone untouched. Upgrading again resumes everything with no setup.
• Deleting your organization immediately deletes the stored tokens. DNS records in your zone are left as they are. Hub no longer has the means to touch them, so remove them yourself in Cloudflare if you want them gone.

Tier Limits

Free Tier

One subdomain with an auto-generated name on a PodWarden domain. This suits homelabs that need a single public entry point: use path-based routing in your ingress rules to serve multiple workloads from one subdomain.

Pro Tier

Up to 50 subdomains on PodWarden domains with custom slugs, plus your own Cloudflare zones with no limit on names.

Enterprise

Unlimited subdomains on PodWarden domains, plus your own Cloudflare zones.

Using with Ingress Rules

After allocating a subdomain, create an ingress rule to route traffic to your workload:

1. From PodWarden Settings > Hub > DDNS Subdomains: Note the FQDN of your subdomain

2. Go to Ingress > Create Rule:

   • Domain: your subdomain FQDN
   • deployment: select the workload
   • Backend Port: the container port
   • Gateway Host: your gateway node
   • TLS: enabled (Caddy handles Let's Encrypt)

3. Apply the Caddy config and verify

For a complete walkthrough, see Ingress, Gateway Nodes & DDNS.

Available Domains

The PodWarden parent domains currently on offer are listed in the domain dropdown when you allocate a subdomain, and under Domain Quotas on Dashboard > DDNS. Domains may be added or retired over time, so this page doesn't list them. Your own domains appear in the same dropdown under Your domains.

Troubleshooting

Subdomain shows "pending" status

The IP hasn't been pushed yet. From PodWarden Settings > Hub, click the wifi icon to push your current IP manually. The automatic update loop runs every 5 minutes.

Subdomain shows "error" status

Check the error message displayed below the subdomain. Common causes:

• Hub can't reach Cloudflare (temporary API issue, so try again)
• Invalid IP address format
• On your own domain: the Cloudflare token was rejected, so replace it under Your domains
• On a PodWarden domain: Cloudflare zone misconfiguration (contact support)

"Your plan does not include your own DNS domains"

The subdomain is on one of your own domains and your organization is on the Free plan. Upgrade to resume updates. Nothing in your zone was changed.

DNS not resolving after IP update

DNS propagation takes time. Most resolvers update within 5 minutes (TTL is set to 300 seconds), but some ISP resolvers cache longer. Try:

• dig <your subdomain FQDN> to check the current A record
• Wait 5-10 minutes for propagation
• Use 1.1.1.1 or 8.8.8.8 as your DNS resolver for faster updates

"Max subdomains reached" error

Your plan's limit for subdomains on PodWarden domains has been reached. Either:

• Release an unused subdomain
• Upgrade your plan for more subdomains
• Use path-based routing to serve multiple workloads from one subdomain
• On Pro or Enterprise, add your own domain, which has no limit