API Deprecations
Let's understand a bit about the lifecycle of an API.
A new API group can be added to Kubernetes but will always start with v1alpha1.
Let's imagine a test/v1alpha1 API that was added to Kubernetes and that we have two objects we could declare, that is, two different kinds:
- course
- webinar
But let's imagine that webinar wasn't a good choice and we want to remove it.
It's not possible to remove it from version v1alpha1, it's necessary to release v1alpha2, because the first rule of API group policies is:
API elements can only be removed by incrementing the API Group version.
In version v1alpha1, we'll have the course and webinar kinds available, and in version v1alpha2, only course.
Kubernetes supporting multiple versions avoids having to change all manifests that use a previous version.
What would change would be the preferred version that would now be set to v1alpha2 when we use course.
This leads us to the second rule of API deprecation policies:
API objects must be able to navigate API versions in a given version without loss of information, with exceptions for REST resources that don't exist in some versions.
If we create an API and an object in version v1alpha1 and it's converted to v1alpha2 and back to v1alpha1, it must be equal to the original.
This means that if a field is added in v1alpha2, it must also be added in v1alpha1 because a direct conversion wouldn't be possible if a field doesn't exist.
Over time, v1beta1, v1beta2 are released until reaching the stable version v1. In this new v1, we don't need Kubernetes to support all these versions if v1 has compatibility with the previous ones, then they'll be deprecated to maintain only v1.
A new rule must be respected:
In addition to the most recent API versions in each range, older API versions must be supported after their announced discontinuation for a period of no less than:
- GA: 12 months or 3 releases
- Beta: 9 months or 3 releases
- Alpha: 0 releases
Alpha versions don't need to be supported for any release, but beta and GA (stable) versions need to be supported for between 9 and 12 months.
If we look at the example below, version x+1 doesn't need to support version v1alpha1.
When this happens, it's necessary to create a release note warning of this change, as actions are required for users who have already used v1alpha1.
It's also possible that in a v1beta1 version, for example, it doesn't need to support alpha versions. If this doesn't happen, a new release note will be given. That's why it's not very interesting to use alphas in production.
When the version reaches beta, things change because they need to be supported for a minimum time. We also have rule 3:
The preferred version and the storage version of an API group cannot advance until a release that supports the new version and the previous version has been made.
What we have here is that even though a new version appears, it cannot be the preferred one on its first appearance.
Deprecating a version doesn't mean it simply won't be supported immediately because at least 3 releases will need to be maintained.
Let's analyze a release and deprecation flow:
| Api Group Version | Preferred/ Storage Version | Release Versions | Notes |
|---|---|---|---|
| /v1alpha1 | x | First release | |
| /v1alpha2 | x+1 | Alphas don't need to support previous versions | |
| /v1beta1 | x+2 | First beta, rules must be respected | |
| /v1beta2 | /v1beta1 (deprecated) | x+3 | We release the new version but v1beta1 is still preferred |
| /v1beta1(deprecated) | /v1beta2 | x+4 | Second time v1beta1 appears as deprecated. At this moment, v1beta2 is already preferred |
| /v1 /v1beta1(deprecated) | /v1beta2 (deprecated) | x+5 | Release of v1. Third time v1beta1 appears as deprecated. First time v1beta2 appears as deprecated. Since it was v1's first appearance, v1beta1 is still preferred |
| /v1beta2 (deprecated) | /v1 | x+6 | Removed v1beta1 after 3 releases. v1beta2 is deprecated for the second time. v1 assumes preferred |
| /v1beta2 (deprecated) | /v1 | x+7 | v1beta2 cannot be removed yet. It's necessary to support it one more time to count 3 |
| /v1 | x+8 | v1beta2 removed completely |
If a v2alpha1 is created, the v1 stable version cannot be deprecated until a v2 stable exists. It would be necessary to create v2alphaXs, v2betaXs, v2 to then deprecate v1.
As we've seen, in new releases, new APIs can be added or removed, even changing preferred and stored APIs.
In a Kubernetes update to a new release, it may be necessary to convert manifests when an API version has been completely removed after 3 deprecated releases.
We can use kubectl convert for this. This is a plugin that needs to be installed separately as it's not built-in.
We can use the kubectl-convert cli directly, but if we have it in the path, the kubectl convert command will make a call to this cli.