Terraform Provider: DNS

The DNS provider supports resources that perform DNS updates (RFC 2136) and data sources for reading DNS information. The provider can be configured with secret key based transaction authentication (RFC 2845) or GSS-TSIG (RFC 3645).

Requirements

• Terraform
• Go (1.24)
• GNU Make
• golangci-lint (optional)

Documentation, questions and discussions

Official documentation on how to use this provider can be found on the Terraform Registry. In case of specific questions or discussions, please use the HashiCorp Terraform Providers Discuss forums, in accordance with HashiCorp Community Guidelines.

We also provide:

• Support page for help when using the provider
• Contributing guidelines in case you want to help this project

Compatibility

Compatibility table between this provider, the Terraform Plugin Protocol version it implements, and Terraform:

DNS Provider	Terraform Plugin Protocol	Terraform
>= 3.0.x	5	>= 0.12
>= 2.1.x	4 and 5	>= 0.12
<= 2.x.x	4	<= 0.12

Details can be found querying the Registry API that return all the details about which version are currently available for a particular provider. Here are the details for DNS (JSON response).

Development

Building

1. git clone this repository and cd into its directory
2. make will trigger the Golang build

The provided GNUmakefile defines additional commands generally useful during development, like for running tests, generating documentation, code formatting and linting. Taking a look at it's content is recommended.

Testing

In order to test the provider, you can run

• make test to run provider tests
• make testacc to run provider acceptance tests (excluding ones requiring a DNS_UPDATE_SERVER)
• ./internal/provider/acceptance.sh to run the full suite of acceptance tests

Running acceptance.sh has the following prerequisites:

• Docker
• Go
• Kerberos Clients (e.g. kinit)
• Make
• Terraform CLI
• /etc/hosts entry (or equivalent): 127.0.0.1 ns.example.com

macOS Setup

• Docker for Mac
• Go or with Homebrew: brew install go
• Terraform CLI or with Homebrew: brew install hashicorp/tap/terraform

echo "127.0.0.1 ns.example.com" | sudo tee -a /etc/hosts

Ubuntu Setup

• Docker Engine
• Go
• Terraform CLI

echo "127.0.0.1 ns.example.com" | sudo tee -a /etc/hosts
sudo apt-get install krb5-user make
# If prompted for Kerberos configuration:
# Default Realm: EXAMPLE.COM
# Server: ns.example.com
# Administrative Server: ns.example.com

It's important to note that acceptance tests (testacc) will actually spawn terraform and the provider. Read more about they work on the official page.

Generating documentation

This provider uses terraform-plugin-docs to generate documentation and store it in the docs/ directory. Once a release is cut, the Terraform Registry will download the documentation from docs/ and associate it with the release version. Read more about how this works on the official page.

Use make generate to ensure the documentation is regenerated with any changes.

Using a development build

If running tests and acceptance tests isn't enough, it's possible to set up a local terraform configuration to use a development builds of the provider. This can be achieved by leveraging the Terraform CLI configuration file development overrides.

First, use make install to place a fresh development build of the provider in your ${GOBIN} (defaults to ${GOPATH}/bin or ${HOME}/go/bin if ${GOPATH} is not set). Repeat this every time you make changes to the provider locally.

Then, setup your environment following these instructions to make your local terraform use your local build.

Testing GitHub Actions

This project uses GitHub Actions to realize its CI.

Sometimes it might be helpful to locally reproduce the behaviour of those actions, and for this we use act. Once installed, you can simulate the actions executed when opening a PR with:

# List of workflows for the 'pull_request' action
$ act -l pull_request

# Execute the workflows associated with the `pull_request' action 
$ act pull_request

Releasing

The releasable builds are generated from the build GH workflow and the release/promotion process is completed via internal HashiCorp deployment tooling. Prior to release, the changelog should be updated in main with the changie tool, example:

changie batch 3.7.2 && changie merge

License

Mozilla Public License v2.0