Planning and reviewing recent Kubernetes API deprecations
Kubernetes features a clear API deprecation and removal strategy, which has gained traction after v1.22 used it to finally remove APIs that had been designated as deprecated for several versions. More APIs will be removed in version 1.25.
Many of these APIs have moved from beta to stable, marking a significant step forward for Kubernetes…
However, that API deprecation policy change occurred in September of 2019, approximately three years ago. They must now depart.
Red Hat, Inc. Remote Health Monitoring by OpenShift is aimed to provide Red Hat with insight into real-world Kubernetes usage so that it may proactively discover defects, resolve platform-specific issues, and foresee issues like outdated APIs. We started seeing actual usage counts for these deprecated APIs after the OpenShift user base began upgrading to OpenShift 4.8. For another six months, usage increased, but it has recently plateaued as clients restrict their use of the APIs.
While the utilization figures may have been higher than planned, this is the community’s first large-scale Kubernetes API deprecation. We’ll go over the deprecation policies for Kubernetes and OpenShift in more detail later, but first, let’s learn about them.
Deprecations in Kubernetes recently
The removal of v1beta1 APIs in Kubernetes v1.22 is complicated by the fact that many of these objects were highly popular, particularly since many customers accelerated their Kubernetes adoption in 2019, making use of more powerful APIs like:
- CustomResourceDefinition (CRD)
- ValidatingWebhookConfiguration
- MutatingWebhookConfiguration
- CertificateSigningRequest
These are popular ways of extending the platform, and several Operators, for example, exploited them extensively.
The first step for Kubernetes administrators is to start observing and measuring the usage of these APIs before they are deleted. Later in this post, we’ll go into how OpenShift goes above and beyond to make this simple.
Vendors of Kubernetes-based solutions must devise a strategy for tracking which deprecations affect the supported Kubernetes versions. The engineering team has been working diligently to prepare for these changes. We’ve developed tools to aid migrations and revised our documentation in the hopes of making these deprecations less unpleasant.
Another big list of anticipated v1beta1 security and workload stability deprecations is included in Kubernetes v1.25, including:
- PodSecurityPolicy
- PodDistruptionBudget
- RuntimeClass
- CronJobs
The worst situation for a Kubernetes administrator is having to choose between a security update and a third-party product that is still utilizing a deprecated API. These upstream updates must be considered by Kubernetes administrators and vendors.
We’ll see examples of how this has played out once OpenShift 4.9 was released, which included Kubernetes v1.22.
Deprecations in Kubernetes and OpenShift
Let’s take a look at how OpenShift handles Kubernetes deprecations before we get into what we’re seeing throughout the OpenShift fleet. Overall, Red Hat aims to launch a Kubernetes release three to four months after it is released in OpenShift. In comparison to other certified Kubernetes products, OpenShift has a track record of exceeding this target.
This approach strikes a balance between stability and innovation for our consumers by delivering the most recent features. Because Red Hat pushes a lot of development upstream, it makes sense for us to consume our own code in OpenShift.
When our engineers are involved upstream as APIs change, we plan for deprecations. When the Kubernetes version is out, we begin informing our customers and partners about the changes they should be aware of.
During the months leading up to and following the general availability of OpenShift 4.9, Red Hat worked with over 100 partners to help them understand how their Kubernetes API usage needs to evolve. Because partner software is certified for OpenShift but also has an influence on others, this initiative benefits the whole Kubernetes community.
Other API Deprecations and How OpenShift Handles Them
OpenShift provides an API Compatibility Guide, which includes a discussion of API tiers, their lifecycles, and how they can be changed over time. For illustration, here’s a small copy of the policy:
| Openshift API Tier | Description | Examples |
| Tier 1 | Stable within a major release, eg. OpenShift 4 | Any Kubernetes v1
oauth.openshift.io/v1 route.openshift.io/v1 |
| Tier 2 | Stable for 9 months or 3 releases from the announcement of deprecation, whichever is longer. | Any Kubernetes v1beta1
console.openshift.io/v1 |
| Tier 3 | Stable on a component-specific schedule. | Language runtimes
Optional Operators Technology Preview features |
| Tier 4 | None. No compatibility is guaranteed. | Any Kubernetes v1alpha1
Developer Preview features |
As you can see, Tier 1 covers all Kubernetes v1 “stable” APIs, ensuring that they remain stable throughout the OpenShift 4 lifecycle.
Tier 2 applies to Kubernetes v1beta1 APIs, which is the policy that regulates the API reductions we discussed in v1.22 and the impending v1.25 release. Since the incorporation of Kubernetes v1.16 in OpenShift 4.3, OpenShift 4.9 with Kubernetes v1.22 was the fourth release.
