↓ Skip to main content
mi-homes.org

Pi-hole

Table of Contents

Pi-hole runs as Argo CD Application pihole from the public manifests in homelabs/pihole/ plus the private overlay at clusters/<cluster>/overlays/pihole/. Config and gravity data live on claim pihole-data-lh (longhorn-ssd). The web admin password comes from a Kubernetes Secret that you write before the first sync.

Access is on the home network. Service pihole is a MetalLB LoadBalancer for DNS (TCP/UDP 53) and the admin UI (HTTP 80). Cloudflare Tunnel is not part of this path. Do not add a Public Hostname for pihole.<your-domain>, and delete that hostname plus its Access application if one still exists from an earlier setup. Minecraft is the same LAN-only pattern.

Configure
#

Copy the secret template into the Pi-hole overlay and generate the Secret there:

cp apps/pihole/secret.yaml.template clusters/<cluster>/overlays/pihole/secret.yaml
kubectl -n pihole create secret generic pihole-password --from-literal=WEBPASSWORD='your-strong-password' --dry-run=client -o yaml > clusters/<cluster>/overlays/pihole/secret.yaml

Storage
#

The Deployment mounts pihole-data-lh (public shape in homelabs/pihole/pvc.yaml) under the usual Pi-hole data paths. FTL uses SQLite with WAL, so treat any filesystem copy during a storage cutover carefully: checkpoint and integrity-check rather than a blind recursive copy. Patterns and the migrate Job example are on the Longhorn page.

Deploy
#

Register the Argo CD stack, then let Argo sync Pi-hole:

kubectl apply -k argocd

To bring Pi-hole up by hand before Argo owns it (first bootstrap or recovery), apply the overlay directly. Once Argo manages the application, change Git and sync instead of applying manifests by hand:

kubectl apply -k clusters/<cluster>/overlays/pihole

LAN access
#

Read the LoadBalancer IP, then point household DNS and the admin browser at that address. The UI is under /admin:

kubectl -n pihole get svc pihole -o jsonpath="{.status.loadBalancer.ingress[0].ip}"

Set the primary DNS in the Deco app to that IP. Open the admin UI at http://<loadBalancerIP>/admin/ from a device on the LAN. There is no public hostname and no tunnel origin for this Service.