APIs Release and Versioning Model

[whitneygriffith]

Istio has chosen to not use conversion webhooks to manage CRD versions due to its complexity and therefore the schemas of all versions of a CRD are identical.

As such, as long as the previous versions of a CRD is supported, field annotations will be used to denote the subset of fields that are Deprecated across all versions of the CRD.

An example of denoting a field as deprecated can be seen in the v1alpha3 gateway and the v1beta1 gateway.

There aren't infrastructure to support denoting a field based on their stage such as Alpha or Beta. However, work for this was proposed here but John doesn't know to what extent it was implemented.

Future API graduation will more than likely occur at the field level and as such we want to use our learnings from Telemetry API graduation to provide opionated guidance on how to do other similar graduations.

Options we want to explore here are:

• Creating a separate API that is not forced to conform to the previous API versions. This can be done by using a new API name, API group and Release Channels as was done in K8s Gateway API

• Building out the Istio Tooling (client facing and operational) to support field level annotations that denote a field is a certain stage and able to enforce/validate the desired version of an API used in a mesh. Some of this work was started here.

• Untangling Istio's support of deprecated fields/APIs as part of #156

[whitneygriffith]

Proposed Istio APIs Release Model

[whitneygriffith]

Release Channels will be the solution to this. This work is tracked here 173