Standardizing the Use of Coupled Attributes in Terraform Configuration

[YakDriver]

Description

TL;DR

We need to standardize the use of coupled attributes in Terraform configuration, considering scenarios where users may expect outcomes that diverge from their configurations. While Terraform's declarative approach typically aims for perfect convergence between user configurations and actual outcomes, the flexibility of partial configurations and the abstraction of cloud services necessitate a nuanced approach. Intentional use of coupled attributes provide users with access to both their configured values and the precise outcomes, enhancing flexibility and precision in complex systems.

Definition

"Coupled attributes" are two or more Terraform provider attributes that relate to a single aspect of configuration but provide differing views. They are useful where users reasonably anticipate valid outcomes that deviate from their configurations. For example, imagine a Terraform provider allows a user to configure the version of a database engine. In some situations, the user may want to abstract away some detail by providing only the major version. In other situations, the user provides a detailed version. Regardless, the user also wants to know the details of the resulting configuration and checks the coupled attribute, version_actual, to find out the exact version AWS selected.

Goal

We need to standardize the use of coupled attributes in Terraform configuration defining:

1. When they should be used, and
2. How they should be named.

Why not use coupled attributes

Although we propose that there are valid reasons for using couple attributes, there are also good reasons to not use them:

1. At the core of Terraform's declarative approach lies the expectation that user configurations precisely match the resulting outcomes. Using coupled attributes may muddy, in the minds of users, the concept and ideal of perfect convergence.
2. Adding a lot of coupled attributes makes configurations messy with extra attributes that don't have a 1:1 relation with an API value.
3. Adding a coupled attribute can be used to workaround situations where the more appropriate response is an API or provider fix.

Why use coupled attributes

At the core of Terraform's declarative approach lies the expectation that user configurations precisely match the resulting outcomes. However, this notion encounters limitations when dealing with partial configurations and the inherent abstraction of cloud services. Users often define only key aspects of their desired outcomes, relying on the Terraform provider and associated cloud service to fill in the gaps as necessary, such as with optional arguments. Additionally, users frequently receive feedback--"output"--on specific details of the outcome, including information that may not have been directly configured.

While a single attribute aligns well with scenarios where user-configured values are expected to perfectly converge with actual outcomes, it falls short in situations where users provide imprecise information and anticipate precision in outcomes. For instance, users may request a major version (such as "8.0") of a database from a cloud provider, expecting a more precise version number (such as "8.0.44") in return. A single "version" attribute, computed and optional, does not adequately capture this expectation, leading to discrepancies between original configured value and actual value.

In complex systems where resources depend on each other and precision is paramount, users should have the flexibility to connect dependencies to either the original configured value or the actual value. Coupled attributes offer a solution by providing users with access to both their configured values and the precise outcomes, enhancing flexibility and precision in configuration management.

Because coupled attributes can lead to messy configurations, they should be used sparingly and only in situations where a user, in reasonable circumstances, expects additional information to be returned.

In addition, coupled attributes should not be used as a workaround for API bugs. For example, if the API expects a setting to be in all caps, such as "RADIAL_PATTERN," but returns the settings in all lowercase, "radial_pattern," using coupled attributes to workaround this glitch is a bad idea. It confuses a user, leads to unnecessary clutter, and is not based on a user's reasonable expectation of additional information. Instead, rather than coupled attributes, we should pursue other workarounds and bug fixes in the API.

Proposal

We propose adopting coupled attributes in scenarios where cloud services allow users to imprecisely define configurations, and users reasonably expect outcomes to deviate from their initial configurations. By incorporating coupled attributes into Terraform configuration standards, users gain greater control over their configurations and ensure alignment with actual outcomes.

Current usage and examples

While coupled attributes already exist for some arguments, they currently follow different naming standards, highlighting the need for standardization and consistent implementation across Terraform configurations.

Below are examples of coupled attributes and the basic pattern of naming:

Base argument	Coupled attribute	Note
version	version_actual	Used in AWS provider (1 2 3 4 5 6)
version	effective_version	Used in AWS provider (1)
version	version_returned	Azure recommendation
version	version_api_value	Azure recommendation
initial_version	version	Used in GCP provider
version	effective_version	Used in GCP provider (1 2)

References

• rds: Improve version/instance data sources #35698
• https://google.aip.dev/129

[github-actions]

Community Note

Voting for Prioritization

• Please vote on this issue by adding a 👍 reaction to the original post to help the community and maintainers prioritize this request.
• Please see our prioritization guide for information on how we prioritize.
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request.

Volunteering to Work on This Issue

• If you are interested in working on this issue, please leave a comment.
• If this would be your first contribution, please review the contribution guide.