Design: How do we manage ASO upgrades with breaking changes?

[theunrepentantgeek]

Describe the current behavior

Thus far we've managed to ensure each release of ASO v2 is backward compatible with resources used with the previous releases. This applies even for the prefix change from v1alpha1api to v1beta.

We need to have a plan, and hopefully a design, for what we are going to do when we need to release a breaking change of ASO.

How do we make a breaking change to the structure of our generated resources without causing havoc for our existing users?

Describe the improvement

Ideally, we'd be able to make this change to the actual structure of our custom resources (CRs) without breaking any existing users, including those who are deploying ASO "v.latest" automatically using a gitOps workflow.

One suggested approach is to serialize the old CR to ARM API format (which won't have changed) and then deserialize to the new object, effectively tunnelling through the change via ARM.

A prerequisite for this approach would be to always retain the existing CR object structure and add the new structure by using a new prefix (following the same approach as we used in PR #2163 when moving to beta).

[matthchr]

We still need to think about this. We have done some breaks in individual resources (in alpha), that we just announced and made people delete and recreate but as a pattern that doesn't scale well at all.

[matthchr]

I think we're looking for some thinking/design here, but the general plan is that we don't make breaking changes on the v1 shape, and any breaking changes that are done by the upstream Azure teams will be in subsequent API versions such as v120220101 -> v120230101 and so we can deal with them in the conversion there.