Overview
Core functions with identical implementations for Terraform, OpenTofu, Terratest, and other software in the so-called Terra/Fu ecosystem.
While some of these can be implemented in HCL, some of them begin to push up against the limits of Terraform and the HCL2 configuration language. Exposing these functions as both a Go library as well as a Terraform/OpenTofu provider enables us to use the same functionality in both our Terraform/OpenTofu applies as well as while using a testing framework.
The goal of this provider is not to call any network APIs, but to provide pre-built functions in the form of Data Sources or Provider Functions.
Vote for features!
View the list of issues, and give a thumbs-up to the ones you'd like to see. This is how we prioritize the work.
Compatibility testing
- We have automated testing that runs on every commit and every pull request.
- We intend for the Go libraries to work with all non-EOL versions of Go (i.e., current, current-1).
- Built using the Terraform Plugin Framework, which speaks Terraform Protocol v6.
| Testing type | Details | Description |
|---|---|---|
| integration | Terraform 1.0–1.14 | Executes the provider with this release, pulling from registry.terraform.io. |
| integration | OpenTofu 1.6–1.11 | Executes the provider with this release, pulling from registry.opentofu.org. |
| unit | Go 1.24–1.25 | Tests using these versions. |
| mutation | Go 1.24–1.25 | Tests using these versions. |
| fuzz | Go 1.24–1.25 | Tests using these versions. |
| terratest | Go 1.24–1.25 | Tests using these versions. |
Usage Examples
See the docs/ directory for user-facing documentation.
Documentation
Registries
Go Package
If you are using this as a Go library, see the documentation at pkg.go.dev.
go get -u github.com/northwood-labs/terraform-provider-corefunc/v2/corefunc
Ported Functions
While some of the functions in this provider are new, others have been backported from newer versions of Terraform/OpenTofu to make them available to versions back to 1.0. In other cases, some functions exist in one tool but not the other. In these cases, we aim to provide identical implementations available to both tools.
Warning
Code is either a clean room implementation, or ported from the MPL-2.0 licensed OpenTofu project. Zero code has been ported from BUSL-1.1 licensed versions of Terraform.
Implemented between Terraform 1.1–1.5
| Function | Terraform | Corefunc |
|---|---|---|
endswith |
1.3 | 2.2 |
startswith |
1.3 | 2.2 |
strcontains |
1.5 | 2.2 |
timecmp |
1.3 | 2.2 |
Implemented after the OpenTofu fork
| Function | Terraform | OpenTofu | Corefunc |
|---|---|---|---|
base64gunzip |
- | 1.7 | 1.5 |
cidrcontains |
- | 1.7 | 1.5 |
urldecode |
- | 1.7 | 1.5 |
Probably won’t implement
These are tied to specific features, or require deeper HCL/internal-type evaluation, and don’t necessarily make sense to backport or provide a Go equivalent for.
| Function | Terraform | OpenTofu |
|---|---|---|
ephemeralasnull |
1.10 | 1.11 |
issensitive |
1.8 | 1.7 |
plantimestamp |
1.5 | 1.5 |
provider::terraform::decode_tfvars |
1.8 | 1.10 |
provider::terraform::encode_expr |
1.8 | 1.10 |
provider::terraform::encode_tfvars |
1.8 | 1.10 |
templatestring |
1.9 | 1.7 |
More Information
After the provider is installed, you can run terraform-provider-corefunc on the CLI.
- Install with either
terraform initormake build. - The Go binary path (discovered by running
./find-go-bin.sh) is on your$PATH.
This will display the following text:
terraform-provider-corefunc
This binary is a plugin. These are not meant to be executed directly.
Please execute the program that consumes these plugins, which will
load any plugins automatically
However, by passing the --help flag, you can see the other options available, including a description of the software.
terraform-provider-corefunc --help
Extras
We've also bundled some CLI commands that you might find as useful as we have.
JSON → TOML
terraform-provider-corefunc json2toml file.json > file.tomlTOML → JSON
terraform-provider-corefunc toml2json file.toml > file.jsonEnsuring quality
Northwood Labs takes testing seriously, and quality is a high priority for us. This software undergoes the following types of testing before every release.
On every commit
- Unit testing of the Go library to ensure that the code behaves (and doesn't behave) as expected.
- Unit testing of the Go library’s documentation examples to ensure that the examples actually work.
- Mutation testing of the Go library to ensure that our tests are good at testing the code (as opposed to chasing code coverage).
- Acceptance testing of the provider (through both Terraform and OpenTofu) which uses table-driven testing to ensure that the inputs and expected outputs are correct.
- Terratest tests the provider using the same tools as one might use to test their own Terraform/OpenTofu modules.
- A very strict set of linting rules using golangci-lint.
On every release
- Fuzzing of the Go library which throws garbage at the code to ensure edge-cases don't slip through.
- We use the Bash Automated Testing System together with tfschema to ensure that nothing weird or unexpected occurs with the Terraform Plugin Protocol v6 between releases.
On a regular cadence
Supply-chain testing and validation. Some of these are on every commit, while a couple run before every release.
- Dependabot with auto-merging (by GitHub).
- Dependency Review (by GitHub).
- Go Dependency Submission (by GitHub).
- govulncheck (by the Go team).
- Harden-Runner (by StepSecurity).
- OSSF Scorecard (by OpenSSF).
- OSV Scanner (by Google).
- Trufflehog OSS (by Truffle Security).