Skip to content
DDNS Updater icon
v1.4.14App: v2.10.0Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

DDNS Updater Helm Chart

Deploy ddns-updater on Kubernetes using the official qmcgaw/ddns-updater Docker image. Keep DNS A/AAAA records updated across 50+ providers with a responsive web UI.

This chart currently deploys qmcgaw/ddns-updater:2.10.0.

Features

  • 50+ DNS providers — Cloudflare, Route53, DuckDNS, Namecheap, GoDaddy, Hetzner, and more
  • Web UI — responsive dashboard for monitoring update status
  • Multi-provider — manage records across different providers in a single deployment
  • Persistent history — update history stored in a PVC
  • Existing secrets — bring your own Secret for credentials
  • Ingress support — expose the web UI with TLS
  • Restricted runtime — non-root container, read-only root filesystem, dropped capabilities, and ServiceAccount token automount disabled

Architecture

The single-replica Deployment reads config.json from either a chart-managed or existing Secret, polls public IP sources, and updates the configured provider APIs. A PVC retains update history when persistence is enabled; otherwise the history volume is ephemeral. By default, a ClusterIP Service exposes the status UI; service.type can select NodePort or LoadBalancer instead. The Recreate strategy prevents two writers from racing during upgrades. See DESIGN.md for the topology and responsibility boundaries.

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

Quick Start

# values.yaml
config:
  settings:
    - provider: cloudflare
      zone_identifier: "your-zone-id"
      domain: "example.com"
      host: "@"
      ttl: 300
      token: "your-cloudflare-api-token"
      proxied: false
      ip_version: "ipv4"

Access the web UI:

kubectl port-forward svc/<release>-ddns-updater 8000:80
# Open http://localhost:8000

Using an Existing Secret

Store your config.json in a Kubernetes Secret:

kubectl create secret generic ddns-config \
  --from-file=config.json=./config.json
config:
  existingSecret: ddns-config
  existingSecretKey: config.json

Multi-Provider Example

config:
  settings:
    - provider: cloudflare
      zone_identifier: "cf-zone-id"
      domain: "example.com"
      host: "@"
      token: "cf-token"
      proxied: true
    - provider: duckdns
      domain: "myhost.duckdns.org"
      token: "duck-token"
    - provider: namecheap
      domain: "example.org"
      host: "home"
      password: "ddns-password"
Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

|-----|---------|-------------| | image.repository | docker.io/qmcgaw/ddns-updater | ddns-updater container image repository | | image.tag | 2.10.0 | ddns-updater container image tag | | config.settings | [] | DNS records to update (provider-specific) | | config.existingSecret | "" | Existing secret with config.json | | ddns.period | 5m | Check interval | | ddns.httpTimeout | 10s | HTTP timeout | | ddns.publicIpFetchers | all | IP detection method (all, http, dns) | | ddns.updateCooldownPeriod | 5m | Minimum interval between updates for the same record | | ddns.logLevel | info | Log level | | ddns.port | 8000 | Web UI container port | | ddns.rootUrl | / | Web UI root URL path | | persistence.enabled | true | Persist update history | | persistence.size | 256Mi | PVC size | | resources.requests.cpu | 10m | Default CPU request | | resources.requests.memory | 32Mi | Default memory request | | resources.limits.cpu | 100m | Default CPU limit | | resources.limits.memory | 128Mi | Default memory limit | | serviceAccount.automountServiceAccountToken | false | Mount Kubernetes API token into pods | | service.port | 80 | Web UI service port | | ingress.enabled | false | Enable ingress | | podSecurityContext.runAsUser | 1000 | Upstream image user | | securityContext.readOnlyRootFilesystem | true | Keep the container root filesystem read-only |

Operations

Use config.existingSecret for production credentials so DNS provider tokens are not stored in values files. Before upgrading, confirm the provider-specific configuration format against the upstream documentation and inspect pod logs after rollout:

kubectl logs -l app.kubernetes.io/name=ddns-updater --all-containers --tail=100

Upgrade Safety

Helm upgrades preserve the Deployment, Service, and PVC names. Keep the release name, nameOverride, fullnameOverride, persistence.existingClaim, and configuration Secret reference stable. 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 the update-history PVC, then verify both the UI and a provider update after the pod is Ready.

Troubleshooting

  • If the pod cannot start, validate the config.json syntax and the configured existingSecretKey.
  • If the UI is healthy but records stay stale, inspect the logs for provider errors and verify outbound DNS, public IP checkers, and provider API access.
  • If the UI is unavailable behind Ingress, confirm ddns.rootUrl, the Service port, and the Ingress path agree.
  • If an upgrade cannot mount history, verify the existing PVC name, access mode, and StorageClass before changing persistence values.

Security Scan

🟢 Security Scan: ddns-updater

Framework Score
MITRE + NSA + SOC2 93.94%

✅ Security posture acceptable.

Local details:

Framework Score
MITRE 100.00%
NSA 95.00%
SOC2 80.00%

The remaining local scan findings are expected for raw chart scanning and platform-level controls: NetworkPolicy and egress firewall policy are supplied by the platform layer because DNS provider APIs and public IP detection endpoints vary by deployment.

More Information

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  Pod[ddns-updater Deployment] --> Checkers[Public IP checkers]
  Secret[config.json Secret] --> Pod
  Pod --> Providers[DNS provider APIs]
  Pod -. persistence enabled .-> PVC[Update history PVC]
  User[Operator browser] --> Service[Web UI Service]
  Ingress[Optional Ingress] -. exposure .-> Service
  Service --> Pod
Official Contractvalues.schema.json

DDNS Updater Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

75 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring""Override the chart name used in resource names

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring""Override the full release name used in resource names

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to every resource created by this chart

Image(3)

ParameterTypeDefaultDescription
image.repositorystringqmcgaw/ddns-updaterddns-updater container image
image.tagstring""Image tag (defaults to appVersion)
image.pullPolicystringIfNotPresentImage pull policy
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets for private registries

Configuration(3)

ParameterTypeDefaultDescription
config.settingsarray-DNS records to keep updated (rendered as config.json secret). Each entry must have a "provider" field plus provider-specific fields.
config.existingSecretstring""Use an existing secret containing config.json instead of inline settings
config.existingSecretKeystringconfig.jsonKey inside the existing secret

Ddns(8)

ParameterTypeDefaultDescription
ddns.periodstring5mPeriod between IP checks
ddns.httpTimeoutstring10sHTTP timeout for IP detection and API calls
ddns.publicIpFetchersstringallPublic IP fetchers (all, http, dns)
Allowed:allhttpdns
ddns.updateCooldownPeriodstring5mUpdate cooldown period per record
ddns.logLevelstringinfoLog level
Allowed:debuginfowarningerror
ddns.portinteger8000Web UI listen port
ddns.rootUrlstring/Web UI root URL path (useful behind a reverse proxy)
ddns.extraEnvarray-Extra environment variables for the container

Persistence(5)

ParameterTypeDefaultDescription
persistence.enabledbooleantrueEnable persistence for update history
persistence.sizestring256MiStorage size
persistence.storageClassstring""Storage class (leave empty for cluster default)
persistence.accessModesarray["ReadWriteOnce"]Access modes for the PVC
persistence.existingClaimstring""Use an existing PVC instead of creating one

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createbooleanfalseCreate a ServiceAccount
serviceAccount.automountServiceAccountTokenbooleanfalseMount Kubernetes API token into pods
serviceAccount.namestring""ServiceAccount name
serviceAccount.annotationsobject-Annotations for the ServiceAccount

Service & Networking(3)

ParameterTypeDefaultDescription
service.typestringClusterIPService type
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger80Web UI service port
service.annotationsobject-Annotations for the Service

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledbooleanfalseEnable ingress for the web UI
ingress.ingressClassNamestringtraefikIngress class name (for example: traefik, nginx)
ingress.annotationsobject-Annotations for the ingress
ingress.hostsarray-Ingress hosts
ingress.tlsarray-Ingress TLS configuration

Health Probes(18)

ParameterTypeDefaultDescription
probes.startup.enabledbooleantrueChart configuration parameter
probes.startup.pathstring/Chart configuration parameter
probes.startup.initialDelaySecondsinteger-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledbooleantrueChart configuration parameter
probes.liveness.pathstring/Chart configuration parameter
probes.liveness.initialDelaySecondsinteger-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledbooleantrueChart configuration parameter
probes.readiness.pathstring/Chart configuration parameter
probes.readiness.initialDelaySecondsinteger-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Resources(4)

ParameterTypeDefaultDescription
resources.requests.cpustringnumber-Requested CPU quantity
resources.requests.memorystringnumber-Requested memory quantity
resources.limits.cpustringnumber-CPU limit
resources.limits.memorystringnumber-Memory limit

Pod Security(5)

ParameterTypeDefaultDescription
podSecurityContext.runAsNonRootboolean-Require the pod to run as a non-root user
podSecurityContext.runAsUserinteger-User ID used by the pod
podSecurityContext.runAsGroupinteger-Primary group ID used by the pod
podSecurityContext.fsGroupinteger-Group ID applied to mounted volumes
podSecurityContext.seccompProfile.typestring-Seccomp profile type

Container Security(1)

ParameterTypeDefaultDescription
securityContextobject-Container-level security context

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Node selector for pod scheduling

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Tolerations for pod scheduling

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Affinity rules for pod scheduling

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Topology spread constraints

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring""Priority class name

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger30Grace period for shutdown (seconds)

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Additional labels for the pod

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Additional annotations for the pod

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Additional volumes for the pod

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Additional volume mounts for the container

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Extra Kubernetes manifests to deploy alongside the chart