DDNS Updater

Deploy ddns-updater on Kubernetes. Keeps DNS A/AAAA records updated across 50+ providers (Cloudflare, Route53, DuckDNS, Namecheap, GoDaddy, Hetzner, and more) with a responsive web dashboard and persistent update history.

Key Features

• 50+ DNS providers — Cloudflare, Route53, DuckDNS, Namecheap, GoDaddy, Hetzner, and more
• Web UI — responsive dashboard at port 8000 for monitoring update status and history
• Multi-record support — manage records from different providers in a single deployment
• Persistent history — updates.json stored in a PVC survives pod restarts
• existingSecret — bring your own config.json Secret for GitOps and production use
• Configurable IP detection — HTTP, DNS, or combined public IP fetching strategies
• Restricted runtime — non-root container, read-only root filesystem, dropped capabilities, and ServiceAccount token automount disabled

Architecture

The chart runs one DDNS writer with a Recreate deployment strategy. It reads config.json from a chart-managed or existing Secret, polls public IP sources, updates provider APIs, stores update history on the PVC, and serves the status UI through a ClusterIP Service by default. service.type can select NodePort or LoadBalancer instead. Horizontal replicas are intentionally avoided because concurrent writers can race DNS updates and history writes.

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install ddns-updater helmforge/ddns-updater -f values.yaml

OCI registry:

helm install ddns-updater oci://ghcr.io/helmforgedev/helm/ddns-updater -f values.yaml

Deployment Examples

# values.yaml — Single Cloudflare record
# Tokens are stored in a chart-managed Secret — consider existingSecret for production.
config:
  settings:
    - provider: cloudflare
      zone_identifier: 'your-zone-id'
      domain: 'example.com'
      host: '@' # '@' for root domain, or subdomain like 'home'
      ttl: 300
      token: 'your-cloudflare-api-token'
      proxied: false
      ip_version: ipv4

ddns:
  period: 5m

persistence:
  enabled: true
  size: 256Mi

# values.yaml — Multiple records across different providers
config:
  settings:
    - provider: cloudflare
      zone_identifier: 'cf-zone-id'
      domain: 'example.com'
      host: '@'
      token: 'cf-api-token'
      proxied: true

    - provider: duckdns
      domain: 'myhost.duckdns.org'
      token: 'duckdns-token'

    - provider: namecheap
      domain: 'example.org'
      host: 'home'
      password: 'namecheap-ddns-password'

ddns:
  period: 5m
  updateCooldownPeriod: 5m # prevents flapping when IP changes rapidly

persistence:
  enabled: true
  size: 256Mi

# values.yaml — GitOps-safe: load config.json from a pre-existing Secret
# Create the secret manually:
#   kubectl create secret generic ddns-config \
#     --from-file=config.json=./config.json
#
# config.json format:
# {
#   "settings": [
#     {
#       "provider": "cloudflare",
#       "zone_identifier": "zone-id",
#       "domain": "example.com",
#       "host": "@",
#       "token": "api-token",
#       "proxied": false,
#       "ip_version": "ipv4"
#     }
#   ]
# }

config:
  existingSecret: ddns-config
  existingSecretKey: config.json

ddns:
  period: 5m

persistence:
  enabled: true
  size: 256Mi

# values.yaml — Web UI exposed via Ingress with TLS
# The web UI runs on port 8000 in the container (mapped to 80 on the Service).
config:
  existingSecret: ddns-config
  existingSecretKey: config.json

ddns:
  period: 5m
  rootUrl: / # set to '/ddns' if behind a reverse proxy on a subpath

persistence:
  enabled: true
  size: 256Mi

ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: ddns.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: ddns-tls
      hosts:
        - ddns.example.com

Configuration Reference

Core

Image

DDNS Configuration

Application Options

Persistence

Service

Ingress

Probes

Resources and Security

Service Account

Scheduling

Extra

Upgrade Safety

Keep the release name, nameOverride, fullnameOverride, configuration Secret reference, and persistence.existingClaim stable so upgrades retain workload, Service, and PVC identity. Export the stored overrides, review them against the new schema, and use a complete values file with the normal Helm merge:

helm get values ddns-updater --namespace ddns-updater -o yaml > values.yaml
helm upgrade ddns-updater helmforge/ddns-updater \
  --namespace ddns-updater --values values.yaml

The file must retain every non-default setting, especially config.existingSecret or config.settings; omitting both can replace the active configuration with an empty chart-managed Secret. --reuse-values preserves stored overrides but also preserves old defaults, so compare the stored values with the new schema before using it. Back up config.json and update history, then confirm both the UI and a real provider update after the pod becomes Ready.

Troubleshooting

• For startup failures, validate config.json and existingSecretKey.
• For stale records, inspect provider errors in the logs and verify outbound DNS, public IP checker, and provider API connectivity.
• For an unavailable proxied UI, align ddns.rootUrl, the Service port, and the Ingress path.
• For PVC mount failures, verify the existing claim, access mode, and StorageClass before changing persistence settings.

More Information

• ddns-updater GitHub Repository
• Supported Providers
• Configuration Reference
• HelmForge DDNS Updater Chart Source