Path to a beta API version

[a-thaler]

Description

The telemetry API should head towards a proper v1 version. For the logs and trace API, smaller things should get adjusted like changing the status to be conform to k8s conventions (#601). For logs the OTLP support will introduce a breaking change (#556).

The goal is to get a streamlined API with a betaV1 version and then do the switch to V1 if there is no major feedback. For going that way, a more detailed path needs to be outlined - when to switch the version for which resource and in which order.

Criterias

• Outline in more detail a plan how to get to a betaV1 version for all types
• Answer following questions:
  • Can we have in between a beta version for trace and metrics already but not for logs (yet) - to decouple the activities
  • Can we have two version at the same time without automatic conversion? What are the implications on the code base?
  • What does it require to have a conversion webhook? Other teams had problems, talk to tunas for example
  • Is there a way to figure out usage of old API if conversion is in place

[skhalash]

The following ADRs will guide us on the path to Telemetry beta API:
#761
#763
#764

Q: Can we have a beta version for trace and metrics already but not for logs (yet) - to decouple the activities
A: No, since versioning is applied to API groups, not kinds

Q: Can we have two versions at the same time without automatic conversion? What are the implications on the code base?
A: No, we can not. Every API server client can read or update every resource at any version.

Q: What does it require to have a conversion webhook? Other teams had problems, talk to Tunas for example
A: An implementation of a conversion webhook is well documented in this example: https://book.kubebuilder.io/multiversion-tutorial/tutorial. Since we already have the required setup for the validation webhook, adding a conversion webhook will not be a difficult task.

Q: Is there a way to figure out the usage of the old API if conversion is in place
A: We can use the following metric: apiserver_crd_conversion_webhook_duration_seconds (https://github.com/kubernetes/apiextensions-apiserver/blob/master/pkg/apiserver/conversion/metrics.go#L62).