In any software project, over time new features and APIs are added and from time-to-time some of them also become deprecated and eventually get removed. Even huge project such as Kubernetes is no exception to this, yet core parts of its API don't really come to mind when thinking about deprecating and eventual removal. So, the question is - could a core object or API in Kubernetes, such as Pod, Deployment or Service be removed and if so, how would that go?
Long Story Short
If the answer to this question was "no", then there would be no reason for this article, so long story short - "yes" - any core API object that's in GA, for example something from v1 API group could absolutely be deprecated.
This simple general answer doesn't tell us much though. When it comes to deprecations, Kubernetes differentiates between couple types of objects, for example REST APIs, CLIs or feature gates. Each of them with its own set of objects with different level of maturity such as alpha, beta or GA. All of this plays role in how long and under what conditions some object - even something like Pod - could be deprecated. So, let's take a bit closer look at each, as well as some examples from the past and also some hypothetical ones that could happen in future.
The Long Story
Different rules apply for different objects/features, so before we talk about the deprecation rules and timelines, let's first go through all the different groups of objects:
REST Objects
- GA: 12 months or 3 releases (whichever is longer)
- Beta: 9 months or 3 releases (whichever is longer)
- Alpha: 0 releases
For REST APIs or objects the general rule is that after deprecation is announced, API versions must be supported for at least:
| Release | API Versions | Preferred | Action |
| X | v1 | v1 | Task object is GA and non-deprecated in v1 |
| X+1 | v2alpha1, v1 | v1 | Task is announced as being deprecated, v2alpha1 is introduced, Task object doesn't exist in new version |
| X+2 | v2alpha2, v1 | v1 | v2alpha1 is replaced with v2alpha2 |
| X+3 | v2beta1, v1 | v1 | v2alpha2 is replaced with v2beta1 |
| X+4 | v2beta2, | v1 | v2beta2 is introduced, v2beta1 still exists, but is now deprecated |
| X+5 | v2, | v1 | v2 is introduced, all other versions including preferred v1 are deprecated |
| X+6 | v2, | v2 | No version are being removed yet, but v2 is now preferred version |
| X+7 | v2, | v2 | v2beta1 gets removed |
| X+8 | v2, | v2 | v2beta2 gets removed |
| X+9 | v2, | v2 | Nothing changes, v1 has to live for one more release |
| X+10 | v2 | v2 | v1 is finally removed and with it also Task object is gone |
From the above table you can see that if the Task object becomes deprecated in API version v2alpha1, it takes another 9 releases for it to be really gone from Kubernetes. Let me also remind you, that with current release cadence of 3 releases per year, this whole deprecation process would take more than 3 years!
That sounds pretty straightforward, but there are many other (not so understandable) rules that apply here, so let's just go straight to an example, that should make it clear. Let's imagine hypothetical API object called Task (fun fact - that's actually the original name of Pods - see first commit of Kubernetes). This Task is GA in API version v1 and it's decided that it should be deprecated, so what would really happen?
As for some real world examples - PodSecurityPolicy is probably the biggest one in recent history. This API object is going from v1beta1 to EOL and it's deprecated as of v1.21 and will be removed in v1.25. For details take a look at KEP-2579.
From the above table you can see that if the Task object becomes deprecated in API version v2alpha1, it takes another 9 releases for it to be really gone from Kubernetes. Let me also remind you, that with current release cadence of 3 releases per year, this whole deprecation process would take more than 3 years!
You should however consider all the objects that are not GA, yet we all are using them as if they were. One such example would be Ingress, which became GA only in 1.19 or CronJob very recently in 1.21. In case of these kinds of beta or even alpha features the deprecation schedule wold not be so generous. If you want to check into which category some resources fall, you can run for example kubectl api-resources | grep beta get list of all beta API in your cluster.
Flags or CLI
As for some real world examples - PodSecurityPolicy is probably the biggest one in recent history. This API object is going from v1beta1 to EOL and it's deprecated as of v1.21 and will be removed in v1.25. For details take a look at KEP-2579.
Another important recent/ongoing deprecation is removal of selfLink field. This one is part of KEP-1164 and work on this change is also tracked in this GitHub issue.
If you're curious about what other deprecations are there, what's their rationale or their whole process of removal, then you can search kubernetes/enhancements repository for mentions of "deprecate" and you will find all the relevant KEPs.
and for admin-facing components, such as kubelet, kube-apiserver or kube-scheduler it's:
Similarly to REST objects, also kubectl or kubelet subcommands or their flags can be deprecated and therefore have its own policy.
This is much simpler than the previous case. Here, for user-facing components, such as kubectl the policy is:
So bottom line for this section would be that deprecation timeline for CLIs is also quite generous, but if you're using some kubectl alpha ... command for automation, then you better check deprecations before upgrading your cluster or even CLI binary/tool.
Feature Gates
and for admin-facing components, such as kubelet, kube-apiserver or kube-scheduler it's:
As for the time it takes to deprecate and remove these - alpha features can disappear anytime and beta ones after 1 release if they're being removed or after 2 releases if they're moving to GA status.
Big recent example of deprecation in this area would be dockershim which is part of kubelet. Its deprecation and removal is outlined in following KEP which includes whole section for removal plan which lists release v1.20 as target for deprecation as well as release v1.24 as target for removal.
Metrics
So bottom line for this section would be that deprecation timeline for CLIs is also quite generous, but if you're using some kubectl alpha ... command for automation, then you better check deprecations before upgrading your cluster or even CLI binary/tool.
For a sample of deprecated and removed metric you can take a look at this commit which removes rest_client_request_latency_seconds metric. You can also find it in release notes of v1.17 along with bunch of other changed/deprecated metrics.
At any point in time, Kubernetes includes many experimental features. These features are controlled using so-called feature gates which are key/value pairs that we can use to turn them on or off.
Conclusion
As for the time it takes to deprecate and remove these - alpha features can disappear anytime and beta ones after 1 release if they're being removed or after 2 releases if they're moving to GA status.
For a concrete examples you can checkout full list of feature gates here. There you can see for example AffinityInAnnotations feature which went from alpha to deprecated, for the ones that went all the way to GA we could list e.g. BlockVolume, DryRun or EndpointSlice. As for the case of feature getting deprecated after getting to beta stage - I wasn't able to find any.