Pi-hole is an ad blocking application which acts as a DNS proxy that returns empty responses when DNS requests for known advertisement domains are made from your devices. It has a number of additional capabilities like optional DHCP server capabilities, specific allow/deny profiles for specific clients, and a neat UI with a ton of information regarding your internet traffic.
Pi-hole is an open source project and can be found at https://github.com/pi-hole/pi-hole.
This provider is published to the Terraform Provider registry.
terraform {
required_providers {
pihole = {
source = "iolave/pihole"
version = "x.x.x"
}
}
}Configure the provider with credentials, or pass environment variables.
provider "pihole" {
url = "https://pihole.domain.com" # PIHOLE_URL
password = var.pihole_password # PIHOLE_PASSWORD
# api_token = var.pihole_api_token # PIHOLE_API_TOKEN (experimental, requires Web Interface >= 5.11)
}See the provider documentation for more details.
There are a few ways to configure local providers. See the somewhat obscure Terraform plugin installation documentation for a potential recommended way.
One way to run a local provider is to build the project, move it to the Terraform plugins directory and then use a required_providers block to note the address and version.
Note
Note the /darwin_arm64/ path portion targets a Mac with an ARM64 processor,
see https://github.com/ryanwholey/terraform-provider-pihole/blob/main/.goreleaser.yml#L18-L27
for possible supported combinations.
# from the project root
go build .
mkdir -p ~/.terraform.d/plugins/terraform.local/local/pihole/0.0.1/darwin_arm64/
cp terraform-provider-pihole ~/.terraform.d/plugins/terraform.local/local/pihole/0.0.1/darwin_arm64/terraform-provider-pihole_v0.0.1In the Terraform workspace, use a required_providers block to target the locally built provider
terraform {
required_providers {
pihole = {
source = "terraform.local/local/pihole"
version = "0.0.1"
}
}
}Testing a Terraform provider comes in several forms. This chapter will attempt to explain the differences, where to find documentation, and how to contribute.
Note
For the current tests in this repository the SDKv2 is used. In issue #4 an upgrade from SDKv2 to plugin-testing can be tracked.
make testThe make testall command is prefixed with the TF_ACC=1. This tells go to include the tests that utilise the helper/resource.Test() functions.
For further reading, please see Hashicorp's documenation on acceptance tests.
To setup a proper environment combining an instance of Pihole in a docker container with tests, some environment variables need to be set for the tests to make their requests to the correct location.
Run the following commands to test against a local Pi-hole server via docker
# Set the local Terraform provider environment variables
export PIHOLE_URL=http://localhost:8080
export PIHOLE_PASSWORD=test
# Start the pi-hole server
make docker-run
# Run Terraform tests against the server
make testallTo test against a specific Pi-hole image tag, specify the tag via the TAG env var
TAG=nightly make docker-runFor further reading about Terraform acceptance tests, see Hashicorp's documenation on acceptance tests.
To assert that resources are created by the planned result of Terraform, the Terraform tests chapter is a good introduction on the topic.
No such tests are yet implemented.
Documentation is auto-generated via tfplugindocs from description fields within the provider package, as well as examples and templates from the examples/ and templates/ folders respectively.
To generate the docs run
make docs