fizzlepoof/truenas-stacks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update Pi-hole docs for live HA rollout

Browse Source
This commit is contained in:
Fizzlepoof
2026-05-15 17:00:07 +00:00
parent bd065445cd
commit 1c5cce5535
3 changed files with 38 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/planning/DEPLOY_PIHOLE.md
View File

@@ -1,6 +1,6 @@
# Pi-hole Deployment Plan # Pi-hole Deployment Plan
**Status:** PD primary stack scaffolded repo-side at `pihole/`; live 3-node rollout still pending replica details and PD-side deployment verification **Status:** PD primary and NOMAD backup are live and working; DNS clients are pointed at VIP `10.5.1.53`. RPi4 remains optional future BACKUP2 work.
**Architecture:** 3-node HA cluster with Keepalived VIP, Unbound recursive DNS, Nebula Sync **Architecture:** 3-node HA cluster with Keepalived VIP, Unbound recursive DNS, Nebula Sync
--- ---
@@ -32,6 +32,7 @@
- **Unbound** on each node acts as the local recursive resolver (replaces Cloudflare/Quad9) - **Unbound** on each node acts as the local recursive resolver (replaces Cloudflare/Quad9)
- **Pi-hole** on each node forwards upstream queries to its local Unbound (`127.0.0.1#5335`) - **Pi-hole** on each node forwards upstream queries to its local Unbound (`127.0.0.1#5335`)
- **Nebula Sync** (running on PD) syncs all Pi-hole configs from primary → replicas daily - **Nebula Sync** (running on PD) syncs all Pi-hole configs from primary → replicas daily
- Current live replica target is NOMAD at `10.5.1.16:8954`
All nodes use `network_mode: host` for Pi-hole, Unbound, and Keepalived — this is required for Keepalived to manipulate the VIP and for Pi-hole to bind cleanly to port 53. All nodes use `network_mode: host` for Pi-hole, Unbound, and Keepalived — this is required for Keepalived to manipulate the VIP and for Pi-hole to bind cleanly to port 53.
@@ -469,6 +470,12 @@ Point **only the VIP** as DNS:
--- ---
## Current live endpoints
- **PD admin UI:** `http://10.5.1.6:8953/admin/`
- **NOMAD admin UI:** `http://10.5.1.16:8954/admin/`
- **VIP for DNS clients:** `10.5.1.53`
## Post-Deploy ## Post-Deploy
### Verify VIP is working ### Verify VIP is working
@@ -523,6 +530,8 @@ Nebula Sync will propagate these to all replicas.
| `pihole.paccoco.com` | `http://10.5.1.6:8953` (primary) | | `pihole.paccoco.com` | `http://10.5.1.6:8953` (primary) |
| `pihole2.paccoco.com` | `http://10.5.1.16:8954` (N.O.M.A.D.) | | `pihole2.paccoco.com` | `http://10.5.1.16:8954` (N.O.M.A.D.) |
Use `/admin/` on the public hostname for the Pi-hole admin UI path.
Enable Pangolin auth — Pi-hole admin should not be publicly accessible. Enable Pangolin auth — Pi-hole admin should not be publicly accessible.
--- ---

21
pihole/README.md
View File

@@ -13,7 +13,7 @@ This stack intentionally covers the **PD primary** plus PD-hosted sync:
- Keepalived - Keepalived
- Nebula Sync - Nebula Sync
NOMAD and RPi4 replicas still need their own deployment steps. NOMAD replica deployment is now documented and live; only the RPi4 replica remains future work.
## Files ## Files
@@ -39,6 +39,24 @@ If that validates cleanly, bring it up:
/usr/bin/bash bin/prepare_pd.sh --up /usr/bin/bash bin/prepare_pd.sh --up
``` ```
## Current live topology
- **PD primary**
- service root: `/mnt/docker-ssd/docker/compose/pihole`
- Pi-hole container: `pihole-primary`
- Unbound container: `unbound-pihole-primary`
- Keepalived container: `keepalived-pihole-primary`
- Nebula Sync container: `nebula-sync`
- LAN admin URL: `http://10.5.1.6:8953/admin/`
- **NOMAD backup**
- service root: `/opt/pihole-nomad`
- Pi-hole container: `pihole-nomad`
- Unbound container: `unbound-pihole-nomad`
- Keepalived container: `keepalived-pihole-nomad`
- LAN admin URL: `http://10.5.1.16:8954/admin/`
- **VIP for client DNS:** `10.5.1.53`
- **Shared Pi-hole admin password:** stored in the local `.env` files; Nebula and both nodes use the same current value.
## Important notes ## Important notes
- `KEEPALIVED_PASSWORD` must be **8 chars or fewer** because VRRP PASS auth is annoying and old. - `KEEPALIVED_PASSWORD` must be **8 chars or fewer** because VRRP PASS auth is annoying and old.
@@ -46,5 +64,6 @@ If that validates cleanly, bring it up:
- `FTLCONF_dns_listeningMode=LOCAL` is set because TrueNAS binds loopback on port 53. - `FTLCONF_dns_listeningMode=LOCAL` is set because TrueNAS binds loopback on port 53.
- Pi-hole NTP is explicitly disabled here because PD host `chronyd` already owns UDP 123. - Pi-hole NTP is explicitly disabled here because PD host `chronyd` already owns UDP 123.
- Nebula Sync runs on PD and uses `NEBULA_SYNC_PRIMARY` / `NEBULA_SYNC_REPLICAS` from `.env`. - Nebula Sync runs on PD and uses `NEBULA_SYNC_PRIMARY` / `NEBULA_SYNC_REPLICAS` from `.env`.
- Current replica target is NOMAD at `http://10.5.1.16:8954`.
- Nebula Sync is intentionally set to selective mode with gravity sync toggles enabled for groups, adlists, and domain lists so replica-specific runtime/network settings are not clobbered. - Nebula Sync is intentionally set to selective mode with gravity sync toggles enabled for groups, adlists, and domain lists so replica-specific runtime/network settings are not clobbered.
- `keepalived.conf` is generated and should stay local/untracked. - `keepalived.conf` is generated and should stay local/untracked.

8
pihole/nomad/README.md
View File

@@ -30,3 +30,11 @@ sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
``` ```
Pi-hole on NOMAD is pinned to `enp5s0` with `FTLCONF_dns_interface=enp5s0` and `FTLCONF_dns_listeningMode=SINGLE` so it answers cleanly on the LAN IP without fighting Docker bridge noise. Pi-hole on NOMAD is pinned to `enp5s0` with `FTLCONF_dns_interface=enp5s0` and `FTLCONF_dns_listeningMode=SINGLE` so it answers cleanly on the LAN IP without fighting Docker bridge noise.
Current live containers:
- `pihole-nomad`
- `unbound-pihole-nomad`
- `keepalived-pihole-nomad`
Current LAN admin URL:
- `http://10.5.1.16:8954/admin/`