docs(terraform): document cloud-specific policy version differences

[RISHABHJAIN27]

Summary

This PR adds documentation describing cloud-specific differences in Azure Policy built-in definition and initiative versions.

Context

Issue #4213 identified that built-in policy and initiative versions can differ across Azure clouds, including Azure Government. In some scenarios, a specific version available in Azure Commercial may not yet be available in Azure Government.

Changes

• Added guidance to modifyingPolicyAssets.md
• Documented cloud-specific policy version considerations
• Added recommendation to use custom policy assets and archetype overrides when versioning requirements differ across clouds

Testing

Documentation-only change.

Fixes [#4213] [https://github.com//issues/4213]

[Copilot]

Pull request overview

This PR updates the Terraform documentation to clarify that built-in Azure Policy definition and initiative versions can differ across Azure clouds (e.g., Azure Commercial vs Azure Government), and provides guidance on what to do when a required built-in version isn’t available in the target cloud.

Changes:

• Added a new “Cloud-specific policy versions” section to highlight cross-cloud built-in policy/initiative version drift.
• Documented the limitation that policy assignment changes alone may not solve version availability gaps.
• Recommended using custom policy assets and archetype overrides to explicitly control policy content/versioning in those scenarios.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/content/terraform/howtos/modifyingPolicyAssets.md:102

• Section heading uses sentence case elsewhere in this doc, and using backticks for property names is common in this repo. Consider renaming the heading for consistency and readability.

## definitionVersion override limitation

docs/content/terraform/howtos/modifyingPolicyAssets.md:108

• The warning text says definitionVersion overrides are "ignored" via policy_assignments_to_modify, but definitionVersion isn’t supported by the alz_architecture policy_assignments_to_modify schema (so it can’t be overridden via that input). Reword to avoid implying the value is accepted and silently dropped.

{{< hint type="warning" >}}
The policy assignment override flow does not currently support `definitionVersion` overrides.

Any `definitionVersion` value provided through `policy_assignments_to_modify` is ignored when policy assignment properties are generated.
{{< /hint >}}

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/content/terraform/howtos/modifyingPolicyAssets.md:110

• This workaround does not actually document the cloud difference promised by the PR, and it omits where the required version must be set. A reader could copy the existing assignment unchanged and reproduce the same deployment failure. State that built-in policy/initiative versions vary by cloud, set properties.definitionVersion in the custom assignment to a version available in the target cloud, and explicitly remove the original assignment while adding the custom one in the archetype override.

For cloud-specific version requirements, create a custom policy assignment asset in your custom library and replace the built-in assignment using an archetype override.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/content/terraform/howtos/modifyingPolicyAssets.md:110

• The guidance is duplicated: the sentence after the hint repeats the same recommendation as inside the hint. Consolidate into the warning callout and optionally make the cloud-specific motivation explicit (Commercial vs Government, etc.) to match the PR intent.

If a specific `definitionVersion` is required, create a custom policy assignment asset in your custom library and replace the built-in assignment using an archetype override.
{{< /hint >}}

For cloud-specific version requirements, create a custom policy assignment asset in your custom library and replace the built-in assignment using an archetype override.

docs/content/terraform/howtos/modifyingPolicyAssets.md:102

• Section heading style is inconsistent with other headings in this doc (which use sentence/title-style capitalization). Consider rephrasing while keeping the literal property name definitionVersion intact.

This issue also appears on line 106 of the same file.

## definitionVersion override limitation