Azure Policy Custom Versioning Enters Public Preview: More Control Over Governance Changes

Microsoft announced the public preview of custom policy versioning in Azure Policy on September 14, 2026. Custom policy definitions and initiatives can now maintain multiple versions under one definition ID, extending the versioning model previously available for built-in policies.

For cloud engineers, the interesting question is not how to add another version number. It is how to introduce a governance change without moving every environment onto it at the same time.

My recommendation is to evaluate this preview as a release-management capability: define what changed, decide which environments should receive it, and collect evidence before expanding the rollout.

More Than a Version String

The versioned definition model uses properties.version in major, minor, and patch format. This is separate from metadata.version, which does not control version selection. The REST API exposes individual versions beneath the policy definition resource.

I would keep the policy content, its version, and a short change description together in source control. A reviewer should be able to understand the operational difference between two releases without reconstructing it from a portal screenshot.

Before adopting the preview, review how your current automation creates definitions and assignments. Treat publishing a definition and choosing where to use it as separate decisions.

Version Pinning Does Not Freeze Every Update

Assignments select a version through definitionVersion. The wildcard matters: 1.*.* follows minor and patch updates within major version 1, while 1.1.* stays within the 1.1 release line and follows patch updates. An exact patch value such as 1.1.1 is not supported for assignment pinning.

That distinction deserves a place in the change procedure. “Pinned” should not be shorthand for “nothing can change.”

My recommendation is to document the intended update policy for each environment. Development might follow a broader version range, while a sensitive workload might require explicit approval before moving to a different minor release line.

Microsoft also notes that semantic-versioning recommendations are not enforced by comparing the contents of each custom version. Your review process still needs to decide whether a change is compatible.

Pilot the Behavior, Not Just the Deployment

Microsoft’s safe-deployment guidance recommends gradually exposing environments to policy changes and validating both compliance results and application health at each stage. A successful assignment deployment is therefore only the beginning of the assessment.

Consider a hypothetical custom policy that requires an ownership tag. The next release introduces stricter validation of the tag value.

I would prepare a small test set: a resource with an accepted value, one with a rejected value, one with the tag missing, and one outside the intended scope. Record the expected outcome before applying the new version.

Then test an ordinary application deployment against the same scope. The policy should reject what the organisation intends to reject—not accidentally block an unrelated maintenance operation.

This is a proposed evaluation approach, not a claim that the preview has been tested here.

Separate Evaluation from Enforcement

Azure Policy supports enforcementMode: DoNotEnforce to evaluate an assignment without enforcing its effect during resource creation or update. However, remediation tasks can still be started for deployIfNotExists policies in this mode.

My recommendation is to make the pilot procedure explicit about both enforcement and remediation. Do not rely on a label such as “test assignment” to communicate what the environment is allowed to change.

Assign an owner to the evaluation, agree on the expected compliance results, and decide who can approve enforcement. For a first pilot, I would avoid starting remediation until the team has reviewed the affected resource set.

A Policy Rollback Is Not a Resource Restore

The preview allows an assignment to return to an earlier version selection. Separately, Azure Policy remediation can deploy resources or modify existing configuration through deployIfNotExists and modify effects.

The operational implication is important: do not treat a version rollback as proof that earlier resource changes have been reversed.

I would write two recovery procedures. One restores the intended policy assignment configuration. The other checks resources changed during the rollout and determines whether corrective action is necessary.

For policies that perform remediation, also verify the assignment identity and its permissions. Microsoft documents that changing a definition does not automatically update the associated managed identity, and changes to required roles may need separate permission updates.

Know the Preview Boundaries

The announcement lists several current limits: up to four versions per custom definition or initiative, support for All and Indexed modes, and no custom policyVersion assignment overrides. Versions referenced by assignments cannot be deleted.

For an initial evaluation, I would keep the release sequence deliberately small: a baseline, a candidate, and enough room to investigate a correction.

Avoid making version cleanup an automatic housekeeping step until the team has agreed which releases must remain available for recovery.

Practical Cloud Engineer Takeaway

Start with one custom policy in a disposable evaluation scope and keep a compact evidence pack:

• Record the definition content, version selection, assignment parameters, and scope.

• Write expected outcomes for compliant, non-compliant, and out-of-scope resources.

• Validate compliance results alongside a representative application deployment.

• Review enforcement settings, remediation permissions, and any resulting resource changes.

• Rehearse returning to the previous assignment configuration before expanding the rollout.

For command-line inspection, the Azure CLI provides az policy definition version list and az policy definition version show to retrieve available versions and their contents. These are useful starting points for collecting evidence rather than relying only on the portal.

Who Should Care?

Azure administrators, platform engineers, landing-zone owners, and governance teams maintaining custom policies across multiple subscriptions or management groups.

This is particularly worth evaluating when policy changes require coordination between the team writing the rules and the teams operating the affected applications.

Bottom Line

My recommendation is to use this preview to improve the change process—not simply to introduce more version numbers.

A useful result is a repeatable answer to four questions: what changed, where it applies, whether it behaves as expected, and how the team will recover when it does not.