Utilities for use with the HashiCorp Terraform Plugin Framework
This project, much like the framework itself, is a work in progress. I will try to keep it as up to date with upstream changes as possible but, as always, community help is appreciated!
| Terraform Plugin Framework | Framework Utils |
|---|---|
| v0.7.0-v0.9.0 | v1 |
| v0.10.x-v0.15.x | v2 |
| v1.x | v3 |
go get -u github.com/dcarbone/terraform-plugin-framework-utils/v3@latestConverting between types used internally by Terraform and typical Go types can be somewhat tricky and / or tedious.
To help with this, I have created a small suite of type conversion utilities designed to make converting to and from Terraform and Go easy and obvious.
You can see the complete list of available conversions here: terraform-plugin-framework-utils/conv
The Terraform Plugin Framework has a great set of per-value type validator interfaces that you may implement as needed: validators. This does not always fit the need, however, as some validations need not be aware of type, or may benefit from being applicable to multiple types.
To facilitate this, I have created a few that I have found useful when creating my own providers, and defined a small wrapper to make creating new validators as simple as defining a function.
Fails validation if the attribute is null or unknown
{
Validators: []validator.{Type}{
validation.Required()
},
}Fails validation if the attribute's value that does not match the user-defined regular expression. This validator will attempt to convert the attribute to a string first.
{
Validators: []validator.{Type}{
validation.RegexpMatch("{{ your regex here }}")
},
}Fails validation if the attribute's value matches the user-defined regular expression. This validator will attempt to convert the attribute to a string first.
{
Validators: []validator.{Type}{
validation.RegexpNotMatch("{{ your regex here }}")
},
}Fails validation if the attribute's value's length is not within the specified bounds.
{
Validators: []validator.{Type}{
// lower limit
validation.Length(5, -1),
// upper limit
validation.Length(-1, 10),
// lower and upper limit
validation.Length(5, 10),
},
}Fails validation if the attribute's value does not match the configured comparison operation.
See comparison.go for details on what comparison operations are available. You can add your own ComparisonFunc using SetComparisonFunc
{
Validators: []validator.{Type}{
// equal
validation.Compare(validation.Equal, 5),
// string comparisons are case sensitive by default
validation.Compare(validation.Equal, "five"),
// passing true as the 3rd arg executes a case-insensitive comparison with strings
validation.Compare(validation.Equal, "fIve", true),
// you may also equate string slices
validation.Compare(validation.Equal, []string{"one", "two"}),
validation.Compare(validation.Equal, []string{"oNe", "twO"}, true),
// you can also assert that a list of ints is equivalent
validation.Compare(validation.Equal, []int{1, 2}),
// less than
validation.Compare(validation.LessThan, 10),
// less than or equal to
validation.Compare(validation.LessThanOrEqualTo, 10),
// greater than
validation.Compare(validation.GreaterThan, 5),
// greater than or equal to
validation.Compare(validation.GreaterThanOrEqualTo, 5),
// not equal
validation.Compare(validation.NotEqual, 10),
// string comparisons are case sensitive by default
validation.Compare(validation.NotEqual, "ten"),
// passing true as the 3rd arg executes a case-insensitive comparison with strings
validation.Compare(validation.NotEqual, "tEn", true),
// you may also compare string slices
validation.Compare(validation.NotEqual, []string{"one", "two"}),
validation.Compare(validation.NotEqual, []string{"oNe", "twO"}, true),
// you can also assert that a list of ints is not equivalent
validation.Compare(validation.NotEqual, []int{1, 2}),
// one of
// currently OneOf only works with strings and ints
validation.Compare(validation.OneOf, []string{"one", "two"}),
// you can provide true for the 3rd parameter to perform a case-insensitive comparison
validation.Compare(validation.OneOf, []string{"one", "two"}, true),
validation.Compare(validation.OneOf []int{1, 2}),
// not one of
// currently NotOneOf only works with strings and ints
validation.Compare(validation.NotOneOf, []string{"one", "two"}),
// you can provide true for the 3rd parameter to perform a case-insensitive comparison
validation.Compare(validation.NotOneOf, []string{"one", "two"}, true),
validation.Compare(validation.NotOneOf []int{1, 2}),
}
}Fails validation if the attribute's value is not parseable by url.Parse
{
Validators: []validator.{Type}{
validation.IsUrl()
}
}Fails validation if the attribute's value is not parseable by time.ParseDuration
{
Validators: []validator.{Type}{
validation.IsDurationString()
}
}Fails validation if the environment variable name defined by the attribute's value is, itself, not valued at runtime.
{
Validators: []validator.{Type}{
validation.EnvVarValued()
}
}Fails validation if the file at the path defined in the attribute's value is not readable at runtime.
{
Validators: []validator.{Type}{
validation.FileIsReadable()
}
}Fails validation if the attribute is valued and the configured sibling attribute is also valued.
{
Validators: []validator.{Type}{
validation.MutuallyExclusiveSibling("{{ sibling field name }}")
}
}# Example provider Terraform HCL
provider "whatever" {
address = "http://example.com"
address_env = "EXAMPLE_ADDR"
}// Example validators list defined on the `address` attribute's schema
{
Validators: []validator.{Type}{
validation.MutuallyExclusiveSibling("address_env")
}
}Adding the above validator to the address attribute's Validators list above will require that the address_env
field must be empty when address is defined. You may also add same validator to the address_env attribute, this
time pointing at the address field.
Requires that two sibling attributes either both be valued or not valued.
{
Validators: []validator.{Type}{
validation.MutuallyInclusiveSibling("{{ sibling field name }}")
}
}# Example provider Terraform HCL
provider "whatever" {
ssh_key_file = file("local/filepath/ssh.key")
ssh_key_password = null
}// Example validators list defined on the `ssh_key_password` attribute's schema
{
Validators: []validator.{Type}{
validation.MutuallyInclusiveSibling("ssh_key")
}
}Adding the above validator to the ssh_key_password attribute's Validators list will require that, if the
ssh_key_file attribute is defined so, too, must the ssh_key_password attribute be valued.
The Terraform Provider Framework provides an excellent suite of test tools to use when creating unit and acceptance tests for provider.
For my uses, I wanted a way to construct hcl config blocks without having to define a heredoc string for each one.
So I created a few config utilities to assist with this.
fieldMap := map[string]interface{}{
"address": "http://example.com",
"token": acctest.ConfigLiteral(`file("/location/on/disk/token")`),
"number_of_fish_in_the_sea": 3500000000000,
}
confHCL := acctest.CompileProviderConfig("my_provider", fieldMap)provider "my_provider" {
address = "http://example.com"
token = file("/location/on/disk/token")
number_of_fish_in_the_sea = 3500000000000
}This can be used with the acctest.JoinConfigs func to bring together multiple reusable configuration blocks for
different tests.