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"
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.
|-----|---------|-------------|
| 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.jsonsyntax and the configuredexistingSecretKey. - 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 SyncedVerified 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
DDNS Updater Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global settings shared by the chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | "" | Override the chart name used in resource names |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | "" | Override the full release name used in resource names |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Labels added to every resource created by this chart |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | qmcgaw/ddns-updater | ddns-updater container image |
| image.tag | string | "" | Image tag (defaults to appVersion) |
| image.pullPolicy | string | IfNotPresent | Image pull policy Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Image pull secrets for private registries |
Configuration(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| config.settings | array | - | DNS records to keep updated (rendered as config.json secret). Each entry must have a "provider" field plus provider-specific fields. |
| config.existingSecret | string | "" | Use an existing secret containing config.json instead of inline settings |
| config.existingSecretKey | string | config.json | Key inside the existing secret |
Ddns(8)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ddns.period | string | 5m | Period between IP checks |
| ddns.httpTimeout | string | 10s | HTTP timeout for IP detection and API calls |
| ddns.publicIpFetchers | string | all | Public IP fetchers (all, http, dns) Allowed: allhttpdns |
| ddns.updateCooldownPeriod | string | 5m | Update cooldown period per record |
| ddns.logLevel | string | info | Log level Allowed: debuginfowarningerror |
| ddns.port | integer | 8000 | Web UI listen port |
| ddns.rootUrl | string | / | Web UI root URL path (useful behind a reverse proxy) |
| ddns.extraEnv | array | - | Extra environment variables for the container |
Persistence(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | true | Enable persistence for update history |
| persistence.size | string | 256Mi | Storage size |
| persistence.storageClass | string | "" | Storage class (leave empty for cluster default) |
| persistence.accessModes | array | ["ReadWriteOnce"] | Access modes for the PVC |
| persistence.existingClaim | string | "" | Use an existing PVC instead of creating one |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | false | Create a ServiceAccount |
| serviceAccount.automountServiceAccountToken | boolean | false | Mount Kubernetes API token into pods |
| serviceAccount.name | string | "" | ServiceAccount name |
| serviceAccount.annotations | object | - | Annotations for the ServiceAccount |
Service & Networking(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | ClusterIP | Service type Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | 80 | Web UI service port |
| service.annotations | object | - | Annotations for the Service |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | false | Enable ingress for the web UI |
| ingress.ingressClassName | string | traefik | Ingress class name (for example: traefik, nginx) |
| ingress.annotations | object | - | Annotations for the ingress |
| ingress.hosts | array | - | Ingress hosts |
| ingress.tls | array | - | Ingress TLS configuration |
Health Probes(18)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | true | Chart configuration parameter |
| probes.startup.path | string | / | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | true | Chart configuration parameter |
| probes.liveness.path | string | / | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | true | Chart configuration parameter |
| probes.readiness.path | string | / | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Resources(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources.requests.cpu | stringnumber | - | Requested CPU quantity |
| resources.requests.memory | stringnumber | - | Requested memory quantity |
| resources.limits.cpu | stringnumber | - | CPU limit |
| resources.limits.memory | stringnumber | - | Memory limit |
Pod Security(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.runAsNonRoot | boolean | - | Require the pod to run as a non-root user |
| podSecurityContext.runAsUser | integer | - | User ID used by the pod |
| podSecurityContext.runAsGroup | integer | - | Primary group ID used by the pod |
| podSecurityContext.fsGroup | integer | - | Group ID applied to mounted volumes |
| podSecurityContext.seccompProfile.type | string | - | Seccomp profile type |
Container Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext | object | - | Container-level security context |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Node selector for pod scheduling |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Tolerations for pod scheduling |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Affinity rules for pod scheduling |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Topology spread constraints |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | "" | Priority class name |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | 30 | Grace period for shutdown (seconds) |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Additional labels for the pod |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Additional annotations for the pod |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Additional volumes for the pod |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Additional volume mounts for the container |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Extra Kubernetes manifests to deploy alongside the chart |
No schema parameters match your search
Try searching for a different keyword or reset the filter.