bryan-bar / terraform-provider-toolbox

Utility provider that exists to provide an interface between Terraform and external programs. Useful for integrating Terraform with a system for which a first-class provider does not exist.

Terraform Provider: Toolbox

The Toolbox provider is a provider that provides an interface between Terraform and external programs. Using this provider, it is possible to write separate programs that can participate in the Terraform lifecycle by implementing a specific protocol. This provider is for last resort and existing providers should be preferred as external programs escape the lifecycle and can depend on the environment.

• Issue #610 (opened - 2014/11/27) (closed - 2022/08/29) - capture output of provisioners into variables
• Issue #5 (opened - 2017/07/19) - External resource provider

Uses:

• Allow execution of external programs during Terraform's lifecycle.
  • Direct CLI/API calls instead of relying on the provider to handle all cases.
  • Ansible playbooks to bootstrap a system after all resources are created/attached.
  • Execution of existing scripts/executables instead of creating a provider.
• Allow external program data to be returned back into the Terraform lifecycle.
  • Additional volume's UUID after formatting for tracking

Alternative Solutions:

• External provider by HashiCorp - Data source which allows for external program execution and exposes output for use in a terraform (expects no side-effects as it will execute with every terraform run)
• remote-exec provisioner by HashiCorp - Remote executable defined within a resource and executed after resource is created (requires temp files to read ouput back into terraform).
• local-exec provisioner by HashiCorp - Local executable defined within a resource and executed after a resource is created (requires temp files to read ouput back into terraform).
• cloudinit provider by HashiCorp - Cloud-Init configuration to override defaults from a resources used image.
• external shell module by Invicton Labs - Execute an external program on the local instance and expose output for use in terraform (temp files needed to read final output)
• SSH provider by loafoe - Execute an external program on a remote instance and expose the output for use in terraform.
• shell provider by scottwinkler - Execute an external program on the local instance and expose the output for use in terraform.
• restapi provider by Mastercard - Use of a rest api within the terraform lifecycle.
• Ansible provider by Ansible - Execute ansible resources within the terraform lifecycle.

Compatibility

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

Toolbox Provider	Terraform Plugin Protocol	Terraform	Golang
>= 0.2.2	6	>= 1.3.6	>= 1.20

Requirements

• Terraform
• Go
• 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 or issues, please raise an issue on github.

We also provide:

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

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 Time (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

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 release process is automated via GitHub Actions, and it's defined in the Workflow release.yml.

Each release is cut by pushing a semantically versioned tag to the default branch.

License

Mozilla Public License v2.0