Split Terraform customer managed key interface into two variants

[Jared Holgate (jaredfholgate)]

Summary

Splits the Terraform Customer Managed Key interface into two variants, mirroring the Variant 1 / Variant 2 pattern already used by the Bicep spec.

Variant 1 is the existing shape, unchanged. Existing modules and existing consumers stay valid.

Variant 2 is new and minimal:

key_vault_key_uri                = string
user_assigned_identity_client_id = optional(string, null)

Why

Terraform reads a data source during plan whenever its arguments are already known.

• azurerm_key_vault_key takes a vault resource ID and a key name.
• azurerm_user_assigned_identity takes a name and a resource group name.

Those arguments are known literals even when the key or the identity is created by the same terraform apply, so the read runs before the resource exists and the plan fails. Modules that need an identity's client ID — Microsoft.ContainerRegistry/registries is the current example — have no way to obtain it from a resource ID without hitting exactly this problem. That is what drove the non-standard customer_managed_key_direct_values workaround in terraform-azurerm-avm-res-containerregistry-registry#201.

Reading the vault by key_vault_resource_id is safe in both directions, because that argument is unknown at plan time whenever the vault is created by the same apply, which defers the read. Variant 1 therefore keeps working as it always has.

Why two variants rather than extending the existing one

Adding client_id to the single existing object is a breaking change for every module that consumes it, and it permanently clutters the interface for resources such as Microsoft.Storage/storageAccounts that will never use it. Splitting means a module only ever sees the attributes its resource provider actually consumes.

Linting accepts either shape.

Which variant applies

This is determined by the resource provider's API, not by module owner preference.

	Variant 1	Variant 2
Identity identified by	resource ID	client ID
Key supplied as	vault URI + key name + version	single key URI
Example provider	Microsoft.Storage/storageAccounts	Microsoft.ContainerRegistry/registries

Side effects of Variant 2

• Carrying the full key URI means the consumer owns the host, so sovereign clouds and Managed HSM work unchanged with no DNS suffix derivation in the module.
• Omitting the trailing version segment leaves the resource provider following key rotations automatically.
• Variant 2 carries no identity resource ID, so a module cannot cross-check the encryption identity against managed_identities.user_assigned_resource_ids. This is intentional — the spec instead requires the module to document that the consumer assigns the identity.

Validation

Both schemas were exercised with terraform test: 6 cases for Variant 1 and 12 for Variant 2, covering versionless and versioned URIs, Managed HSM and sovereign hosts, and rejection of secret URIs, key resource IDs, http scheme and non-GUID client IDs. 18/18 pass. terraform fmt -check is clean on all six include files.

Companion changes

• Azure/terraform-azure-avm-utl-interfaces — add the Variant 2 shape.
• Azure/tflint-ruleset-avm — accept either shape.
• The corresponding update to Azure-Verified-Modules-Docs.

Note on CI

The buildpr failure on this branch is pre-existing and unrelated. Commit 11edbf8 (#2861) flipped two avm-ptn-alz-application-landing-zone-cicd-bootstrap-* rows in TerraformPatternModules.csv to Available, and their registry URLs return 404, so Hugo fails resolving them. Unrelated PRs fail identically. It needs a separate fix in the CSV.

[myaschmitz]

I like the approach here, since it would remove the data sources as well as fix the root issue of Azure/terraform-azurerm-avm-res-containerregistry-registry#201.