danylomikula / ansible-pihole-cluster

☄️ The easiest way to bootstrap a robust Pi-hole Highly Available cluster using Ansible with Keepalived for failover management, Gravity Sync for nodes synchronization, and Unbound as a recursive DNS server for higher privacy.

Pi-hole HA cluster with Keepalived, Gravity-Sync, and Unbound

📖 General Information

This Ansible playbook will allow you to bootstrap a Highly Available Pi-hole cluster with:

• keepalived
• Gravity Sync
• unbound

Has been tested on:

• Debian - version 12 (bookworm)
• Ubuntu - version 22.04 (Jammy Jellyfish)
• Ubuntu - version 23.10 (Mantic Minotaur)
• Rocky - version 9.4

✅ Requirements

• 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 the nodes, 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 your ansible_user = rocky, run this command under root user to disable password verification for rocky user:
  

  echo rocky 'ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/rocky

🚀 Getting Started

• 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 in inventory/group_vars/all.yml

Note

You can run bootstrap-pihole.yaml playbook any time.
It will bootstrap a fresh Pi-hole installation with updates (statistics will not be deleted)

⚙️ Updates

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.