Understanding Deprecated Kubernetes APIs and Their Significance

If you’re running an outdated version of the Kubernetes API, you’re putting your application at risk of substantial downtime. You may even experience a sitewide outage like the one experienced by Reddit.

Even if an upgrade doesn't result in an outage, subtle differences in Kubernetes APIs can cause frustration and wasted effort investigating underlying problems.

This was evident when we encountered the upgrade to Kubernetes 1.24, which brought an issue with service account default secrets. Consequently, it rendered the version incompatible with other Kubernetes terraform provider versions. Although it didn't cause a complete outage, it was a significant drain on our valuable time as we worked to identify the root cause of the problem.

The Kubernetes API serves as the interface to interact with a Kubernetes cluster. It allows users to query and manipulate various Kubernetes objects like pods, namespaces, and deployments. These APIs can be accessed through tools such as kubectl, via the REST API directly, or by using client libraries.

In this guide, we will explore the significance of deprecating Kubernetes APIs and how Plural can provide valuable insights for identifying these deprecations.

Deprecating and Removing Kubernetes APIs

Kubernetes is a dynamic system driven by APIs, which evolve with each new release. A crucial aspect of any API-driven system is having a well-defined deprecation policy. This policy informs users about APIs that are slated for removal or modification. Kubernetes follows this principle and periodically refines or upgrades its APIs. Consequently, older APIs are marked as deprecated and eventually phased out.

In this context, deprecation implies identifying an API component for eventual removal. While it functions currently, it is scheduled to be eliminated in an upcoming version. Further details on how Kubernetes manages API deprecation can be found in the deprecation policy documentation.

Why the Concern about Deprecated APIs?

When configuring an application, the user specifies the API version of the Kubernetes object to be employed. Whether it's a straightforward Kubernetes YAML manifest or a Helm chart, the apiVersion field designates the API version of the Kubernetes object. This underscores the importance for users or maintainers to be aware of deprecated Kubernetes API versions and the Kubernetes release in which they are set to be removed.

Additionally, during a Kubernetes cluster upgrade, encountering deprecated APIs is a possibility if the upgraded version does not support them. For instance, if resources in your cluster utilize an outdated API version, your application relying on that resource may cease to function if the deprecated API has been eliminated in the new cluster version.

An illustrative example is the APIVersion extensions/v1beta1 of the Ingress Resource, which was removed in Kubernetes version v1.22. Attempting to use such a removed API version in your configuration would result in an error message:

‌                   Error: UPGRADE FAILED: current release manifest contains removed kubernetes api(s) for this kubernetes version and it is therefore unable to build the kubernetes objects for performing the diff. error from kubernetes: unable to recognize "": no matches for kind "Ingress" in version "extensions/v1beta1"

Where and How Kubernetes APIs are Utilized

‌‌To specify a particular API version in your configuration, refer to the sample below, sourced from Kubernetes documentation:

   apiVersion: apps/v1     <------ API Version of the kubernetes object
   kind: Deployment
  metadata:
    name: nginx-deployment
    labels:
      app: nginx
  spec:
    replicas: 3

You can also review all supported API groups along with their versions through official documentation or by using the kubectl command-line tool's api-versions command:‌

kubectl api-versions
admissionregistration.k8s.io/v1
admissionregistration.k8s.io/v1beta1
apiextensions.k8s.io/v1
apiextensions.k8s.io/v1beta1
apiregistration.k8s.io/v1
apiregistration.k8s.io/v1beta1
apps/v1

Challenges in Identifying Deprecated APIs in Your Cluster

Although Kubernetes provides official documentation to examine deprecated or removed APIs, identifying the resources in your cluster that utilize these APIs can be quite challenging.

On top of that, Kubernetes abides by a stringent API versioning protocol, resulting in multiple deprecations of v1beta1 and v2beta1 APIs across several releases. Their policy states that Beta API versions are mandated to receive support for a minimum of 9 months or 3 releases (whichever is longer) after deprecation, after which they may be subject to removal.

In cases where APIs that have been deprecated are still actively employed by workloads, tools, or other components interfacing with the cluster, disruptions may occur. Hence, it is imperative for users and administrators to conduct a thorough assessment of their cluster to identify any APIs in use slated for removal, and subsequently migrate the affected components to leverage the appropriate new API version.

Merely listing your Kubernetes resources using kubectl commands may yield inaccurate API version information, as explained in this issue.

To tackle this problem, you can employ a tool like Plural.

What is Plural?

Plural is an end-to-end self-hosted platform for managing Kubernetes clusters and application deployment. Plural offers users a managed Cluster API provisioner to consistently set up managed and custom Kubernetes control planes across top infrastructure providers.

Additionally, Plural provides a robust deployment pipeline system, empowering users to effortlessly deploy their services to these clusters. Plural acts as a single pane of glass for managing application deployment across environments.

With Plural you can effortlessly detect deprecated Kubernetes APIs used in your code repositories and helm releases minimizing the effect deprecated APIs can have on your ecosystem.

Features:

• Rapidly create new Kubernetes environments across any cloud without ever having to write code
• Managed, zero downtime upgrades with cluster API reconciliation loops, don’t worry about sloppy and fragile terraform rollouts
• Dynamically add and remove nodes to your cluster node topology as you like
• Use scaffolds to create functional gitops deployments in a flash
• First-class support for cdk8s.io to provide a robust Kubernetes authoring experience with unit testability and package management
• Integrated secret management
• A single, scalable user interface where your org can deploy and monitor everything fast.

How Plural detects deprecated Kubernetes APIs

Previously, identifying deprecated versions of the Kubernetes API was a laborious and error-prone task, requiring manual inspection of all manifests. This process becomes even more cumbersome and unfeasible when multiple teams deploy to a cluster without a centralized manifest repository.

Plural offers a comprehensive analysis of source code deployed to your Kubernetes clusters by scanning existing Git repositories. It provides an overview of the entire footprint, ensuring you stay up-to-date with the latest API versions. If any Kubernetes API is deprecated, Plural notifies you promptly, making it easy to troubleshoot and update configurations as needed.

Behind on Kubernetes upgrades and wary of API deprecations? Reach out to us to learn more about Plural.