This Ansible playbook will allow you to bootstrap a Highly Available Pi-hole cluster with:
Has been tested on:
- Debian - version 12 (bookworm)
- Ubuntu - version 22.04 (Jammy Jellyfish)
- Ubuntu - version 23.10 (Mantic Minotaur)
- Rocky - version 9.4
-
Ansible 2.14+
-
Two
nodes
on which Pi-hole will be installed. -
Each
node
should have a static IP address.If your Linux distribution network controller is NetworkManager, you can use this example to set static IP, DNS, and gateway:
nmcli con mod "Wired connection 1" ipv4.addresses 10.0.20.50/24 ipv4.gateway 10.0.20.1 ipv4.dns "1.1.1.1 1.0.0.1" ipv4.ignore-auto-dns yes ipv4.method manual
-
Passwordless SSH access between the machine running
ansible
and thenodes
. If not, you can supply arguments to provide credentials--ask-pass --ask-become-pass
to each command. -
Ansible should be able to use sudo without a password.
You may need to configure this on
Rocky Linux
.
Suppose youransible_user = rocky
, run this command underroot
user to disable password verification forrocky
user:echo rocky 'ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/rocky
-
Install collections that this playbook uses by running
ansible-galaxy collection install -r ./collections/requirements.yml
-
Edit the
inventory/hosts.ini
file with IP addresses, hostnames and paths to your SSH keys for each node.[master] pihole-master ansible_host=10.0.20.50 ansible_ssh_private_key_file=~/.ssh/pihole-master priority=150 [backup] pihole-backup ansible_host=10.0.20.51 ansible_ssh_private_key_file=~/.ssh/pihole-backup priority=140
-
Modify
inventory/group_vars/all.yml
based on your needs. -
Start cluster provisioning using the following command:
ansible-playbook bootstrap-pihole.yaml
-
Point your DNS server settings to the virtual IP (
pihole_vip_ipv4
,pihole_vip_ipv6
) that you set previously ininventory/group_vars/all.yml
Note
You can run bootstrap-pihole.yaml
playbook at any time.
It will bootstrap a fresh Pi-hole installation with updates (statistics will not be deleted)
To quickly update system or change settings you can run update-pihole.yaml
playbook
ansible-playbook update-pihole.yaml
You can use this playbook to:
- Update Pi-hole version.
- Update Pi-hole settings.
- Modify Pi-hole custom DNS or CNAME records.
- Update host packages and dependencies.