Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/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.
https://github.com/danylomikula/ansible-pihole-cluster

ansible ansible-playbook debian high-availability linux pi-hole pihole raspberry-pi rockylinux ubuntu

Last synced: 3 months ago
JSON representation

Host: GitHub
URL: https://github.com/danylomikula/ansible-pihole-cluster
Owner: danylomikula
License: apache-2.0
Created: 2024-03-24T02:19:59.000Z (9 months ago)
Default Branch: main
Last Pushed: 2024-09-18T18:48:28.000Z (3 months ago)
Last Synced: 2024-09-27T13:01:33.579Z (3 months ago)
Topics: ansible, ansible-playbook, debian, high-availability, linux, pi-hole, pihole, raspberry-pi, rockylinux, ubuntu
Language: Jinja
Homepage:
Size: 1.01 MB
Stars: 11
Watchers: 1
Forks: 3
Open Issues: 0
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

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:
- [x] [keepalived](https://github.com/acassen/keepalived)
- [x] [Gravity Sync](https://github.com/vmstan/gravity-sync)
- [x] [unbound](https://github.com/NLnetLabs/unbound)

Has been tested on:
- [x] Debian - version 12 (bookworm)
- [x] Ubuntu - version 22.04 (Jammy Jellyfish)
- [x] Ubuntu - version 23.10 (Mantic Minotaur)
- [x] 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:

```bash
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:

```bash
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.
```bash
[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 at 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.