Allow Optional SingleNestedBlocks and Required Attributes within

[kenchan0130]

Module version

v1.2.0

Use-cases

There are times when we want to define multiple distinct SingleNestedBlocks, and would like to make those blocks optional.

In conjunction, there are also cases where we would like to make some attributes of the SingleNestedBlock required.

Here's a specific example of definitions:

schema.Schema{
	Blocks: map[string]schema.Block{
		"block1": schema.SingleNestedBlock{
			Validators: []validator.Object{
				objectvalidator.ExactlyOneOf(path.Expressions{
					path.MatchRoot("block1"),
					path.MatchRoot("block2"),
				}...),
			},
			Attributes: map[string]schema.Attribute{
				"attrA": schema.StringAttribute{
					Required: true,
				},
			},
		},
		"block2": schema.SingleNestedBlock{
			Validators: []validator.Object{
				objectvalidator.ExactlyOneOf(path.Expressions{
					path.MatchRoot("block1"),
					path.MatchRoot("block2"),
				}...),
			},
                         Attributes: map[string]schema.Attribute{
				"attrB": schema.StringAttribute{
					Optional: true,
				},
			},
		},
	}
}

resource "test_resource" "example" {
   block2 {
      attrB = "exmaple"
   }
}

However, due to the current specification of SingleNestedBlock, if one or more attributes of the block we want to make optional are required, the parent block also functions as if it were required.

Error: Missing Configuration for Required Attribute
 
   with test_resource.example,
   on terraform_plugin_test.tf line 2, in resource "test_resource" "example":
    2: resource "test_resource" "example" {
 
 Must set a configuration value for the block1.attrA attribute as the
 provider has marked it as required.

Attempted Solutions

schema.Schema{
	Blocks: map[string]schema.Block{
		"block1": schema.ListNestedBlock{
			Validators: []validator.List{
				listvalidator.ExactlyOneOf(path.Expressions{
					path.MatchRoot("block1"),
					path.MatchRoot("block2"),
				}...),
				listvalidator.SizeAtMost(1),
			},
			NestedObject: schema.NestedBlockObject{
				Attributes: map[string]schema.Attribute{
					"attrA": schema.StringAttribute{
						Required: true,
					},
				},
			},
                },
		"block2": schema.SingleNestedBlock{
			Validators: []validator.Object{
				objectvalidator.ExactlyOneOf(path.Expressions{
					path.MatchRoot("block1"),
					path.MatchRoot("block2"),
				}...),
			},
		},
	}
}

This use case can be achieved by using ListNestedBlock. However, for users who will end up using this provider, the internal implementation as a list, such as test_resource.example.block1[0], leaks into the resource interface. This is not a favorable situation for users.

Proposal

type SingleNestedBlock struct {
   // ... existing methods ...
  
  Required: bool,
  Optional: bool,
}

For instance, it could be considered to prepare an attribute that determines whether the SingleNestedBlock is optional or not. If it's optional, then the requirement of the child attributes could be ignored.

References

[bflad]

Hi @kenchan0130 👋 Thank you for raising this.

Before diving into the proposal further, it may be helpful to provide some additional background about Terraform schema and data handling concepts. Blocks are generally considered more "structural" rather than attributes which are always values. This distinction is important in the case of single nested blocks because it is unavoidable that Terraform sends a non-null "object" with all attribute values set to null for a single nested block when it is not configured. Exposing single nested blocks in this framework was in reality a pragmatic compromise to enable existing terraform-plugin-sdk providers to migrate the prior timeouts functionality without introducing breaking changes.

For list and set nested blocks, Terraform also sends a non-null and empty list/set when not configured, however the framework can (and in fact does) automatically convert those empty list/set blocks to null to ease provider developer burden as it is not possible for Terraform to be configured in a manner which would create an empty list/set for a block. This is what prevents the block nested attribute Required validation issue for list/set blocks, since the framework validation logic will not progress deeper down a null value.

The same to/from null value conversion cannot necessarily be directly applied to single nested blocks without worrying about causing potential regressions with existing provider code though. Today it is valid for provider code to be missing null checks for single nested blocks due to the current framework behavior of preserving Terraform's representation. Maybe this type of behavior could be considered for a future major version of the framework if all the semantic details are discussed further.

Another slight proposal wrinkle here is that the protocol itself does not expose "optional" and "required" behaviors for blocks, only attributes (https://github.com/hashicorp/terraform/blob/13cb0d03c7d6cca7b22966428c6032ab1ac4c574/docs/plugin-protocol/tfplugin6.3.proto#L84-L104). This framework has been designed, over its terraform-plugin-sdk predecessor, without overloaded abstractions when there are correlating protocol concepts.

With the above in mind and without other potential changes, introducing this type of provider behavior configuration therefore might be confusing given that the "object" for a single nested block always exists. Having a block behavior configuration of "optional" or "required" in this sense could never apply the same way it does for an attribute value. To be "optional" would imply the "object" could potentially not exist while "required" could never trigger a validation error.

There should be an existing solution for this use case though. Nested attributes, such as a single nested attribute in this situation, should provide an enhanced provider developer and practitioner experience. Nested attribute values are treated the same as attribute values, meaning they can be null, unknown, or known directly based on the configuration. Nested attributes also can be configured via any Terraform configuration language expression, rather than being limited to dynamic block expressions. The Go and website documentation should mention that nested attributes are preferable over blocks for new implementations.

Given these realities, it seems fair to mention upfront that the prioritization of changing the existing single nested block behaviors or introducing further configurability of behaviors may be limited. That being said though, thank you for your time writing up this feature request.

[bflad]

Hi again, @kenchan0130 👋

After discussing this with the maintainer team further today, we have concluded that the current behavior is desirable/correct based on the details given above. Using a single nested attribute in this situation, instead of a single nested block should work as expected. If you need to maintain Terraform 0.12-0.15 compatibility (e.g. migrating a terraform-plugin-sdk/v2 based provider without a breaking change) then using a list nested block with a size limiting validator would be the direct migration path.

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.