Set Attribute
Set attributes store an unique, unordered collection of single element type. Values are represented by a set type in the framework, containing elements of the element type.
In this Terraform configuration example, a set of string attribute named example_attribute
is set to the unordered values "one"
and "two"
:
Schema Definition
Use one of the following attribute types to directly add a set value to a schema or nested attribute type:
Schema Type | Attribute Type |
---|---|
Data Source | schema.SetAttribute |
Provider | schema.SetAttribute |
Resource | schema.SetAttribute |
Ephemeral Resource | schema.SetAttribute |
The ElementType
field must be defined, which represents the single value type of every element of the set.
In this example, a resource schema defines a top level required set of strings attribute named example_attribute
:
An element type may itself contain further collection types, if necessary.
In this example, a resource schema defines a top level required set of set of strings attribute named example_attribute
:
If the set value should be the element type of a collection attribute type, set the ElementType
field according to the set type. Refer to the collection attribute type documentation for additional details.
If the set value should be a value type of an object attribute type, set the AttributeTypes
map value according to the set type. Refer to the object attribute type documentation for additional details.
Configurability
At least one of the Computed
, Optional
, or Required
fields must be set to true
. This defines how Terraform and the framework should expect data to set, whether the value is from the practitioner configuration or from the provider logic, such as API response value.
The acceptable behaviors of these configurability options are:
Required
only: The value must be practitioner configured to an eventually known value (not null), otherwise the framework will automatically raise an error diagnostic for the missing value.Optional
only: The value may be practitioner configured to a known value or null.Optional
andComputed
: The value may be practitioner configured or the value may be set in provider logic when the practitioner configuration is null.Computed
only: The value will be set in provider logic and any practitioner configuration causes the framework to automatically raise an error diagnostic for the unexpected configuration value.
Custom Types
You may want to build your own attribute value and type implementations to allow your provider to combine validation, description, and plan customization behaviors into a reusable bundle. This helps avoid duplication or reimplementation and ensures consistency. These implementations use the CustomType
field in the attribute type.
Refer to Custom Types for further details on creating provider-defined types and values.
Deprecation
Set the DeprecationMessage
field to a practitioner-focused message for how to handle the deprecation. The framework will automatically raise a warning diagnostic with this message if the practitioner configuration contains a known value for the attribute. Terraform version 1.2.7 and later will raise a warning diagnostic in certain scenarios if the deprecated attribute value is referenced elsewhere in a practitioner configuration. The framework deprecations documentation fully describes the recommended practices for deprecating an attribute or resource.
Some practitioner-focused examples of a deprecation message include:
- Configure
other_attribute
instead. This attribute will be removed in the next major version of the provider. - Remove this attribute's configuration as it no longer is used and the attribute will be removed in the next major version of the provider.
Description
The framework provides two description fields, Description
and MarkdownDescription
, which various tools use to show additional information about an attribute and its intended purpose. This includes, but is not limited to, terraform-plugin-docs
for automated provider documentation generation and terraform-ls
for Terraform configuration editor integrations.
Plan Modification
Tip
Only managed resources implement this concept.
The framework provides two plan modification fields for managed resource attributes, Default
and PlanModifiers
, which define resource and attribute value planning behaviors. The resource default and plan modification documentation covers these features more in-depth.
Common Use Case Plan Modification
The setdefault
package defines common use case Default
implementations:
StaticValue(types.Set)
: Define a static set default value for the attribute.
The setplanmodifier
package defines common use case PlanModifiers
implementations:
RequiresReplace()
: Marks the resource for replacement if the resource is being updated and the plan value does not match the prior state value.RequiresReplaceIf()
: Similar toRequiresReplace()
, but also checks if a given function returns true.RequiresReplaceIfConfigured()
: Similar toRequiresReplace()
, but also checks if the configuration value is not null.UseStateForUnknown()
: Copies a known prior state value into the planned value. Use this when it is known that an unconfigured value will remain the same after a resource update.
Sensitive
Set the Sensitive
field if the attribute value should always be considered sensitive data. In Terraform, this will generally mask the value in practitioner output. This setting cannot be conditionally set and does not impact how data is stored in the state.
Validation
Set the Validators
field to define validation. This validation logic is ran in addition to any validation contained within a custom type.
Common Use Case Validators
HashiCorp provides the additional terraform-plugin-framework-validators
Go module which contains validation logic for common use cases. The setvalidator
package within that module has set attribute validators such as defining conflicting attributes.
Accessing Values
The accessing values documentation covers general methods for reading schema (configuration, plan, and state) data, which is necessary before accessing an attribute value directly. The set type documentation covers methods for interacting with the attribute value itself.
Setting Values
The set type documentation covers methods for creating or setting the appropriate value. The writing data documentation covers general methods for writing schema (plan and state) data, which is necessary afterwards.