Dynamic Data
Note
Static types should always be preferred over dynamic types, when possible.
Dynamic data handling uses the framework dynamic type to communicate to Terraform that the value type of a specific field will be determined at runtime. This allows a provider developer to handle multiple value types of data with a single attribute, parameter, or return.
Dynamic data can be defined with:
- Dynamic attribute
- A dynamic attribute type in an object attribute
- Dynamic function parameter
- Dynamic function return
- A dynamic attribute type in an object parameter
- A dynamic attribute type in an object return
Using dynamic data has a negative impact on practitioner experience when using Terraform and downstream tooling, like practitioner configuration editor integrations. Dynamics do not change how Terraform's static type system behaves and all data consistency rules are applied the same as static types. Provider developers should understand all the below considerations when creating a provider with a dynamic type.
Only use a dynamic type when there is not a suitable static type alternative.
Considerations
When dynamic data is used, Terraform will no longer have any static information about the value types expected for a given attribute, function parameter, or function return. This results in behaviors that the provider developer will need to account for with additional documentation, code, error messaging, etc.
Downstream Tooling
Practitioner configuration editor integrations, like the Terraform VSCode extension and language server, cannot provide any static information when using dynamic data in configurations. This can result in practitioners using dynamic data in expressions (like for
) incorrectly that will only error at runtime.
Given this example, a resource schema defines a top level computed dynamic attribute named example_attribute
:
The configuration below would be valid until a practitioner runs an apply. If the type of example_attribute
is not iterable, then the practitioner will receive an error only when they run a command:
Results in the following error:
Dynamic data that is meant for practitioners to utilize in configurations should document all potential output types and expected usage to avoid confusing errors.
Handling All Possible Types
Terraform will not automatically convert values to conform to a static type, exposing provider developers to the Terraform type system directly. Provider developers will need to deal with this lack of type conversion by writing logic that handles every possible type that Terraform supports.
In this example, a resource schema defines a top level required dynamic attribute named example_attribute
:
An example of handling every possible Terraform type that could be provided to a configuration would be:
When writing test configurations and debugging provider issues, developers will also want to understand how Terraform represents complex type literals. For example, Terraform does not provide any way to directly represent lists, maps, or sets.
Handling Underlying Null and Unknown Values
With dynamic data, in addition to typical null and unknown value handling, provider developers will need to implement additional logic to determine if an underlying value for a dynamic is null or unknown.
Underlying Null
In the configuration below, Terraform knows the underlying value type, string
, but the underlying string value is null:
This will result in a known dynamic value, with an underlying value that is a null string type. This can be detected utilizing the (types.Dynamic).IsUnderlyingValueNull()
method. An equivalent framework value to this scenario would be:
Underlying Unknown
In the configuration below, Terraform knows the underlying value type of random_shuffle.result
, a list(string)
, but the underlying list value is unknown:
This will result in a known dynamic value, with an underlying value that is an unknown list of string types. This can be detected utilizing the (types.Dynamic).IsUnderlyingValueUnknown()
method. An equivalent framework value to this scenario would be:
Understanding Type Consistency
For managed resources, Terraform core implements data consistency rules between configuration, plan, and state data. With dynamic attributes, these consistency rules are also applied to the type of data.
For example, given a dynamic example_attribute
that is computed and optional:
If a practitioner configures this resource as:
Then the exact type must be planned and stored in state during apply
as a tuple with two string element types. If provider code attempts to store this attribute as a different type, like a list of strings, even with the same data values, Terraform will produce an error during apply:
If a practitioner configures this same resource as:
Then the exact type must be planned and stored in state during apply
as a list of strings.