Tip
Use nested attribute types instead of object attribute types where possible. Object attributes have limited utility as they can only define type information. A single nested attribute type supports the same configuration syntax as an object while each nested attribute can be fully defined in terms of configurability, validation, etc.
Object attributes are a single structure mapping explicit attribute names to type definitions. Values are represented by a object type in the framework, containing sub-attribute values of the mapped types.
In this Terraform configuration example, an object attribute named example_attribute is set to the mapped values of attr1 to "value1" and attr2 to 123:
resource "examplecloud_thing" "example" {
example_attribute = {
attr1 = "value1"
attr2 = 123
}
}
Use one of the following attribute types to directly add a map value to a schema or nested attribute type:
The AttributeTypes field must be defined, which represents the mapping of explicit string object attribute names to value types.
In this example, a resource schema defines a top level required object attribute named example_attribute with a string sub-attribute named attr1 and integer sub-attribute named attr2:
func (r ThingResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
resp.Schema = schema.Schema{
Attributes: map[string]schema.Attribute{
"example_attribute": schema.ObjectAttribute{
AttributeTypes: map[string]attr.Type{
"attr1": types.StringType,
"attr2": types.Int64Type,
},
Required: true,
// ... potentially other fields ...
},
// ... potentially other attributes ...
},
}
}
A sub-attribute type may itself contain further collection types, if necessary.
In this example, a resource schema defines a top level required object attribute named example_attribute with a list of strings sub-attribute named attr1 and integer sub-attribute named attr2:
func (r ThingResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
resp.Schema = schema.Schema{
Attributes: map[string]schema.Attribute{
"example_attribute": schema.ObjectAttribute{
AttributeTypes: map[string]attr.Type{
"attr1": types.ListType{
ElemType: types.StringType,
},
"attr2": types.Int64Type,
},
Required: true,
// ... potentially other fields ...
},
// ... potentially other attributes ...
},
}
}
If the object value should be the element type of a collection attribute type, set the ElementType field according to the object type. Refer to the collection attribute type documentation for additional details.
Tip
Only the object attribute itself, not individual sub-attributes, can define its configurability. Use nested attribute types for full control of nested attribute capabilities.
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 and Computed: 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.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.
DeprecationTip
Only the object attribute itself, not individual sub-attributes, can define deprecation. Use nested attribute types for full control of nested attribute capabilities.
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:
other_attribute instead. This attribute will be removed in the next major version of the provider.Tip
Only the object attribute itself, not individual sub-attributes, can define its description. Use nested attribute types for full control of nested attribute capabilities.
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.
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.
The objectdefault package defines common use case Default implementations:
StaticValue(types.Object): Define a static object default value for the attribute.The objectplanmodifier 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 to RequiresReplace(), but also checks if a given function returns true.RequiresReplaceIfConfigured(): Similar to RequiresReplace(), 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.Tip
Only the object attribute itself, not individual sub-attributes, can define its sensitivity. Use nested attribute types for full control of nested attribute capabilities.
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.
Tip
Only managed resources implement this concept.
Set the WriteOnly field to define a write-only argument. Write-only arguments can accept ephemeral values and are not persisted in the Terraform plan or state artifacts. Write-only arguments are supported in Terraform 1.11 and later.
Set the Validators field to define validation. This validation logic is ran in addition to any validation contained within a custom type.
HashiCorp provides the additional terraform-plugin-framework-validators Go module which contains validation logic for common use cases. The objectvalidator package within that module has map attribute validators such as defining conflicting attributes.
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 object type documentation covers methods for interacting with the attribute value itself.
The object 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.
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