Schema fields that can have an effect at plan or apply time are collectively referred to as "Behavioral fields", or an element's behaviors. These fields are often combined in several ways to create different behaviors, depending on the need of the element in question, typically customized to match the behavior of a cloud service API. For example, at time of writing, AWS Launch Configurations cannot be updated through the AWS API. As a result, all of the schema elements in the corresponding Terraform Provider resource aws_launch_configuration are marked as ForceNew: true. This behavior instructs Terraform to first destroy and then recreate the resource if any of the attributes change in the configuration, as opposed to trying to update the existing resource.
Note: The primitive behavior fields cannot be set to false. You can opt out of a behavior by omitting it.
Data structure: bool
Values: true
Restrictions:
Required is trueRequired is omitted and element is not ComputedIndicates that this element is optional to include in the configuration. Note that Optional does not itself establish a default value. See Default below.
Schema example:
"encrypted": {
Type: schema.TypeBool,
Optional: true,
},
Configuration example:
resource "example_volume" "ex" {
encrypted = true
}
Data structure: bool
Values: true
Restrictions:
Optional is trueComputed is trueOptional is omitted and element is not ComputedIndicates that this element must be provided in the configuration. Omitting this attribute from configuration, or later removing it, will result in a plan-time error.
Schema example:
"name": {
Type: schema.TypeString,
Required: true,
},
Configuration example:
resource "example_volume" "ex" {
name = "swap volume"
}
Data structure: interface
Value: any value of an elements Type for primitive types, or the type defined by Elem for complex types.
Restrictions:
Required is trueDefaultFuncIf Default is specified, Terraform will use that value when this item is not set in the configuration.
Schema example:
"encrypted": {
Type: schema.TypeBool,
Optional: true,
Default: false,
},
Configuration example (specified):
resource "example_volume" "ex" {
name = "swap volume"
encrypted = true
}
Configuration example (omitted):
resource "example_volume" "ex" {
name = "swap volume"
# encrypted receives its default value, false
}
Data structure: bool
Value: true
Restrictions:
Required is trueDefault is specifiedDefaultFuncComputed is often used to represent values that are not user configurable or can not be known at time of terraform plan or apply, such as date of creation or a service specific UUID. Computed can be combined with other attributes to achieve specific behaviors, and can be used as output for interpolation into other resources
Schema example:
"uuid": {
Type: schema.TypeString,
Computed: true,
},
Configuration example:
resource "example_volume" "ex" {
name = "swap volume"
encrypted = true
}
output "volume_uuid" {
value = "${example_volume.ex.uuid}"
}
Data structure: bool
Value: true
ForceNew indicates that any change in this field requires the resource to be destroyed and recreated.
Schema example:
"base_image": {
Type: schema.TypeString,
Required: true,
ForceNew: true,
},
Configuration example:
resource "example_instance" "ex" {
name = "bastion host"
base_image = "ubuntu_17.10"
}
NOTE: Write-only arguments are only supported in Terraform v1.11 or higher
Data structure: bool
Value: true
Restrictions:
Required is true or Optional is trueComputed is trueForceNew is trueDefault is specifiedDefaultFunctypeMap, typeList, typeSet), but non-computed list nested block types can contain write-only arguments.WriteOnly should be used for arguments that handle secret values that do not need to be persisted in Terraform plan or state, such as passwords, API keys, etc. Write-only argument values are not sent to Terraform and do not persist in the Terraform plan or state artifacts. Arguments marked as WriteOnly can accept ephemeral values.
Schema example:
"password_wo": {
Type: schema.TypeString,
Required: true,
WriteOnly: true,
},
Configuration example:
ephemeral "random_password" "ex_pass" {
length = 15
}
resource "example_db_instance" "ex" {
username = "foo"
password_wo = random_password.ex_pass.password
}
Data structure: SchemaDiffSuppressFunc
When provided DiffSuppressFunc will be used by Terraform to calculate the diff of this field. Common use cases are capitalization differences in string names, or logical equivalences in JSON values.
Schema example:
"base_image": {
Type: schema.TypeString,
Required: true,
ForceNew: true,
// Suppress the diff shown if the base_image name are equal when both compared in lower case.
DiffSuppressFunc: func(k, old, new string, d *schema.ResourceData) bool {
if strings.ToLower(old) == strings.ToLower(new) {
return true
}
return false
},
},
Configuration example:
Here we assume the service API accepts capitalizations of the base_image name and converts it to a lowercase string. The API then returns the lower case value in its responses.
resource "example_instance" "ex" {
name = "bastion host"
base_image = "UBunTu_17.10"
}
Data structure: SchemaDefaultFunc
Restrictions:
Default is specifiedWhen provided DefaultFunc will be used to compute a dynamic default for this element. The return value of this function should be "stable", such that it is uncommon to return different values in subsequent plans without any other changes being made, to avoid unnecessary diffs in terraform plan.
DefaultFunc is most commonly used in Provider schemas to allow elements to have defaults that are read from the environment.
Schema example:
In this example, Terraform will attempt to read region from the environment if it is omitted from configuration. If it’s not found in the environment, a default value of us-west is given.
"region": {
Type: schema.TypeString,
Required: true,
DefaultFunc: func() (any, error) {
if v := os.Getenv("PROVIDER_REGION"); v != "" {
return v, nil
}
return "us-west", nil
},
},
Configuration example (provided):
provider "example" {
api_key = "somesecretkey"
region = "us-east"
}
Configuration example (default func with PROVIDER_REGION set to us-east in the environment):
provider "example" {
api_key = "somesecretkey"
# region is "us-east"
}
Configuration example (default func with PROVIDER_REGION unset in the environment):
provider "example" {
api_key = "somesecretkey"
# region is "us-west"
}
Data structure: SchemaStateFunc
StateFunc is a function used to convert the value of this element to a string to be stored in the state.
Schema example:
In this example, the StateFunc converts a string value to all lower case.
"name": &schema.Schema{
Type: schema.TypeString,
ForceNew: true,
Required: true,
StateFunc: func(val any) string {
return strings.ToLower(val.(string))
},
},
Configuration example (provided):
resource "example" "ex_instance" {
name = "SomeValueCASEinsensitive"
}
Value in statefile:
"name": "somevaluecaseinsensitive"
Deprecated: Use ValidateDiagFunc instead.
Data structure: SchemaValidateFunc
Restrictions:
ValidateFunc is a function used to validate the value of a primitive type. Common use cases include ensuring an integer falls within a range or a string value is present in a list of valid options. The function returns two slices; the first for warnings, the second for errors which can be used to catch multiple invalid cases. Terraform will only halt execution if an error is returned. Returning warnings will warn the user but the data provided is considered valid.
Terraform includes a number of validators for use in plugins in the validation package. A full list can be found here: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/helper/validation
Schema example:
In this example, the ValidateFunc ensures the integer provided is a value between 0 and 10.
"amount": &schema.Schema{
Type: schema.TypeInt,
Required: true,
ValidateFunc: func(val any, key string) (warns []string, errs []error) {
v := val.(int)
if v < 0 || v > 10 {
errs = append(errs, fmt.Errorf("%q must be between 0 and 10 inclusive, got: %d", key, v))
}
return
},
},
Configuration example:
resource "example" "ex_instance" {
amount = "-1"
}
Data structure: SchemaValidateDiagFunc
Restrictions:
ValidateDiagFunc is a function used to validate the value of a primitive type. Common use cases include ensuring an integer falls within a range or a string value is present in a list of valid options. The function returns a collection of Diagnostics. Developers should append and build the list of diagnostics up until a fatal error is reached, at which point they should return the Diagnostics. Terraform will only halt execution if an error is returned. Warnings will display a warning message to the practitioner, but continue execution.
The SDK includes some basic validators in the helper/validation package.
Schema example:
In this example, the ValidateDiagFunc ensures the string is abc.
"sample": &schema.Schema{
Type: schema.TypeString,
Required: true,
ValidateDiagFunc: func(v any, p cty.Path) diag.Diagnostics {
value := v.(string)
expected := "abc"
var diags diag.Diagnostics
if value != expected {
diag := diag.Diagnostic{
Severity: diag.Error,
Summary: "wrong value",
Detail: fmt.Sprintf("%q is not %q", value, expected),
}
diags = append(diags, diag)
}
return diags
},
},
Configuration example:
resource "example" "ex_instance" {
sample = "efg"
}
NOTE: Resource Identity is only supported in Terraform v1.12 or higher
If the schema being defined represents an identity for a managed resource, set either OptionalForImport or RequiredForImport to true to inform Terraform if practitioners must set the attribute when importing with that resource's identity.
Unlike the resource state schema, the resource identity schema does not support behaviors such as Required and Computed. All identity data is set by the provider, so the entire object is treated as Computed. The only behaviors allowed for identity schema are OptionalForImport or RequiredForImport, with the resulting behavior of:
RequiredForImport only: A practitioner must configure the attribute to a known value (not null), otherwise Terraform automatically raises an error diagnostic for the missing value.OptionalForImport only: A practitioner must configure the value to a known value or null.Schema example:
"id": {
Type: schema.TypeString,
RequiredForImport: true,
},
"region": {
Type: schema.TypeString,
OptionalForImport: true,
},
Configuration example:
import {
to = examplecloud_thing.test
identity = {
id = "id-123"
# region can be omitted or supplied
}
}
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4