terraform-provider-pihole

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.

Usage

This provider is published to the Terraform Provider registry.

terraform {
  required_providers {
    pihole = {
      source  = "ryanwholey/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.

Provider Development

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.1

In 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

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.

Unit testing

make test

Acceptance testing

The 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 testall

To test against a specific Pi-hole image tag, specify the tag via the TAG env var

TAG=nightly make docker-run

For further reading about Terraform acceptance tests, see Hashicorp's documenation on acceptance tests.

TFTest

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.

Docs

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