Change versioning to be Kubernetes compliant

[theunrepentantgeek]

Describe the current behavior

As first reported in #4147 and explored in the ADR Resources and Version Priority, the way we're defining our resource versions in ASO is not compliant with Kubernetes rules.

This failure results in Kubernetes' version priority rules consistently selecting the oldest version of any ASO resource.

This has resulted in confusion, and more importantly, to data loss for users as they work with their resources. (See ASO #4723, CAPZ #5168, and CAPZ #5649 for examples.)

Describe the improvement

We're going to change our versioning using v1api as a consistent prefix to just v.

Old Version	New Version
v1api20250701	v120250701
v1api20250201preview	v20250201preview

And so on.

This will, eventually, be a breaking change but we're going to try and make this as painless as possible by introducing the new versioning scheme alongside the old one (we'll support both v1api20250701 and v20250701 of the resource simultaneously) wherever possible.

Plan

For v2.15 v2.17 get all the groundwork in place for the upgrade to occur (See PR #5031)

From v2.17:

• All new resources get new style versions
• Begin migration group by group, including all tests and samples
• All resources that existed prior to v2.16 continue to work unchanged

Post migration - sometime after v2.20 - we'll remove the old versions.

User Action

Once available, proactively migrate your ASO defined resources to use the new versioning style as we migrate them, group by group. Doing this will allow you to migrate in your own time, rather than being forced to do so when we deprecate the older style.

Progress

We'll update this section to reflect the status of resource migration.

Group	Old Style	Legacy	Hybrid	New Style
alertsmanagement	✅
apimanagement	✅
app	✅
appconfiguration	✅
authorization	✅
batch			✅
cache	✅
cdn	✅
compute	✅
containerinstance	✅
containerregistry	✅
containerservice	✅
datafactory	✅
dataprotection	✅
dbformariadb	✅
dbformysql	✅
dbforpostgresql		✅
devices	✅
documentdb	✅
entra	✅
eventgrid	✅
eventhub	✅
insights	✅
keyvault	✅
kubernetesconfiguration	✅
kusto	✅
machinelearningservices	✅
managedidentity	✅
monitor	✅
network	✅
network.frontdoor	✅
notificationhubs	✅
operationalinsights		✅
redhatopenshift	✅
resources	✅
search	✅
servicebus	✅
signalrservice	✅
sql	✅
storage			✅
subscription	✅
synapse	✅
web	✅

Legend

• Old Style - Resources in this group exclusively use the v1api version prefix. No action is required by users.

• Legacy - Resources introduced in ASO v2.16 and earlier continue to use the v1api version prefix. Resources introduced in ASO v2.17 and later use the new v prefix. Users should migrate to the new versions when possible.

• Hybrid - Resources introduced in ASO v2.16 and earlier are replicated and use both the v1api and v version prefixes. Resources introduced in ASO v2.17 and later use the only the new v prefix. Users must migrate to the new versions before we deprecate the old versions.

• New Style - Resources in this group exclusively use a the v prefix. Group is fully migrated to the new style.

TODO

• Work out which resources are too big to migrate this way, and what to do instead

[rbjorklin]

It is not obvious to me from the release notes of v2.16.0 that the "new style versions" have been implemented. Could someone confirm that that is the case? If it isn't then would you mind updating the description of this issue to mirror the revised timeline?

[theunrepentantgeek]

New style versions didn't land in v2.16; I hope to have the underlying foundation merged for v2.17 - see #5031.

Actual migration of issues will happen gradually, as we want to give users the opportunity to migrate in their own time. I'll update this issue to clarify.