I'm running Pi-hole with Unbound on k3s. It currently runs as a single-replica Deployment, but I'd like to move to a three-replica StatefulSet so I can perform staged upgrades. What migration strategy would avoid database or configuration conflicts while preserving persistent data and keeping DNS available during rollouts?
3 Answers
Be careful with shared persistent storage. Pi-hole’s database and configuration files may not support multiple pods writing to the same volume at the same time. A StatefulSet gives every replica its own stable identity and PVC, which avoids two pods sharing one database, but then the instances need an explicit synchronization mechanism. Tools such as Gravity Sync may help keep settings and blocklists aligned. Pause synchronization during upgrades if a schema change could make versions incompatible.
Pi-hole is not especially well suited to active-active replication in Kubernetes. If you want independently scalable replicas with predictable rollouts, consider a more declarative DNS stack such as CoreDNS with Blocky. CoreDNS can load zones from Git or OCI, while Blocky can refresh blocklists from a defined source. Each pod can start from the same configuration without sharing a writable database, and a separate Redis-compatible cache can be used if shared caching is useful.
You may not need a StatefulSet just to get rolling updates. A Deployment can run three replicas with a RollingUpdate strategy, for example with maxSurge set to 1 and maxUnavailable set to 1. That gradually replaces the pods. The important question is whether all replicas can safely use the same Pi-hole data and database.
The main constraint is making sure only one process modifies a given database at a time. Separate volumes prevent file corruption, but they do not automatically keep the replicas’ settings and statistics consistent.