https://github.com/sbarbett/pihole-ansible
Collection of modules and roles for the PiHole v6 API
https://github.com/sbarbett/pihole-ansible
ad-blocking ansible dns infrastructure-as-code pihole
Last synced: 5 months ago
JSON representation
Collection of modules and roles for the PiHole v6 API
- Host: GitHub
- URL: https://github.com/sbarbett/pihole-ansible
- Owner: sbarbett
- License: mit
- Created: 2025-02-23T03:22:58.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-07-01T01:13:50.000Z (5 months ago)
- Last Synced: 2025-07-01T01:38:38.989Z (5 months ago)
- Topics: ad-blocking, ansible, dns, infrastructure-as-code, pihole
- Language: Python
- Homepage: https://shane.barbetta.me
- Size: 69.3 KB
- Stars: 22
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 🍓 pihole-ansible
This collection provides Ansible modules and roles for managing PiHole v6 via a custom API client. This collection is built on top of the [pihole6api](https://github.com/sbarbett/pihole6api) Python library, which handles authentication and requests.
## Overview
This collection includes:
- **Modules:**
- `local_a_record`: Manage local A records.
- `local_aaaa_record`: Manage local AAAAA records. (see `local_a_record` configuration and examples )
- `local_cname`: Manage local CNAME records.
- `dhcp_config`: Enable, disable and configure the DHCP client.
- `dhcp_remove_lease`: Delete existing leases.
- `listening_mode`: Toggle the PiHole's listening mode.
- `block_list`: Manage block lists.
- `allow_list`: Manage allow lists.
- `groups`: Manage groups.
- `clients`: Manage clients.
- **Roles:**
- `manage_local_records`: A role that iterates over one or more PiHole hosts and manages a batch of local DNS records (both A and CNAME) as defined by the user. ([README](https://github.com/sbarbett/pihole-ansible/blob/main/roles/manage_local_records/README.md))
- `manage_lists`: A role that iterates over one or more PiHole hosts and manages a batch of allow and block lists as defined by the user. ([README](https://github.com/sbarbett/pihole-ansible/blob/main/roles/manage_lists/README.md))
- `manage_groups_clients`: A role that iterates over one or more PiHole hosts and manages a batch of groups and clients as defined by the user. ([README](https://github.com/sbarbett/pihole-ansible/blob/main/roles/manage_groups_clients/README.md))
## Getting Started
### Prerequisites
- **Ansible:** Version 2.9 or later.
- **Python:** The control node requires Python 3.x.
- **pihole6api Library**
### Installation
Install the collection via Ansible Galaxy:
```bash
ansible-galaxy collection install sbarbett.pihole
```
You can also build it locally:
```bash
git clone https://github.com/sbarbett/pihole-ansible
ansible-galaxy collection build
ansible-galaxy collection install sbarbett-pihole-x.x.x.tar.gz
```
#### `pihole6api` Dependency
The `pihole6api` library is required for this Ansible collection to function. The installation method depends on how you installed Ansible.
```bash
pip install pihole6api
```
However, some Linux distributions (Debian, macOS, Fedora, etc.) **restrict system-wide `pip` installs** due to [PEP 668](https://peps.python.org/pep-0668/). In that case, use one of the methods below.
**Installing in a Virtual Environment (Recommended):**
If you want an isolated environment that won’t interfere with system-wide packages, install both `pihole6api` and Ansible in a virtual environment:
```bash
python -m venv venv
source venv/bin/activate
pip install pihole6api ansible
```
To confirm that `ansible` and `pihole6api` are installed correctly within the environment, run:
```bash
which python && which ansible
python -c "import pihole6api; print(pihole6api.__file__)"
```
To exit the virtual environment:
```bash
deactivate
```
**Using `pipx`:**
If Ansible is installed via `pipx`, inject `pihole6api` into Ansible’s environment:
```bash
pipx inject ansible pihole6api --include-deps
```
Verify installation:
```bash
pipx runpip ansible show pihole6api
```
Since Ansible does not automatically detect `pipx` environments, you must explicitly set the Python interpreter in your Ansible configuration:
Edit `ansible.cfg`:
```
[defaults]
interpreter_python = ~/.local/pipx/venvs/ansible/bin/python
```
For more information on `pipx` see [the official documentation](https://github.com/pypa/pipx) and [the Ansible install guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html).
**Installing for System-Wide Ansible (Generally Not Recommended):**
If Ansible was installed via a package manager (`apt`, `dnf`, `brew`) and a virtual environment or `pipx` is not a feasible or desired solution, run `pip` with `--break-system-packages` to bypass **PEP 668** restrictions:
```bash
sudo pip install --break-system-packages pihole6api
```
Verify installation:
```bash
python3 -c "import pihole6api; print(pihole6api.__file__)"
```
## Usage Examples
### Modules
* [Enable and Configure the PiHole DHCP Client](https://github.com/sbarbett/pihole-ansible/blob/main/examples/configure-dhcp-client.yml)
* [Disable the PiHole DHCP Client](https://github.com/sbarbett/pihole-ansible/blob/main/examples/disable-dhcp-client.yml)
* [Remove a DHCP Lease](https://github.com/sbarbett/pihole-ansible/blob/main/examples/remove-dhcp-lease.yml)
* [Create a Local A Record](https://github.com/sbarbett/pihole-ansible/blob/main/examples/create-a-record.yml)
* [Remove a Local A Record](https://github.com/sbarbett/pihole-ansible/blob/main/examples/delete-a-record.yml)
* [Create a Local CNAME](https://github.com/sbarbett/pihole-ansible/blob/main/examples/create-cname.yml)
* [Remove a Local CNAME](https://github.com/sbarbett/pihole-ansible/blob/main/examples/delete-cname.yml)
* [Create an Allow List](https://github.com/sbarbett/pihole-ansible/blob/main/examples/create-allow-list.yml)
* [Create a Block List](https://github.com/sbarbett/pihole-ansible/blob/main/examples/create-block-list.yml)
* [Manage Allow Lists](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-allow-lists.yml)
* [Manage Block Lists](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-block-lists.yml)
* [Manage Groups](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-groups.yml)
* [Manage Clients](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-clients.yml)
### Roles
Roles are designed to orchestrate changes across multiple PiHole instances.
* [Manage Local Records](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-records.yml)
* [Manage Lists](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-lists.yml)
* [Manage Groups and Clients](https://github.com/sbarbett/pihole-ansible/blob/main/examples/manage-groups-clients.yml)
## Documentation
* Each module includes embedded documentation. You can review the options by using `ansible-doc sbarbett.module_name`.
* Detailed information for each role is provided in its own `README` file within the role directory.
## License
MIT