Introduction

For a lot of people (including myself) the relationship between these two and their release cycles can feel quite confusing at first. With this article, I will try to demystify all that. I’ll also talk about the impact of deprecated APIs, how to tackle them and the tools that assist you in identifying them.

Why is this important?

Various API resources, their versions and their deprecation is something that’ll come up during a Kubernetes cluster version upgrade. In fact, its the most important thing you’ve to account for before you jump to a new K8s version.

How they differ and relate

Kubernetes Version:
  • This refers to the version of the Kubernetes platform itself. (the control plane, kubelet, kube-proxy, etc.)
  • Kubernetes uses a semantic versioning scheme like v1.x.x. (e.g., v1.27.0)
  • Each Kubernetes version introduces new features, improvements, bug fixes, and sometimes deprecates or removes certain API versions.
API Version:
  • Kubernetes organizes its API into different groups and versions. (e.g., apps/v1, batch/v1, core/v1, etc.)
  • The API version refers to the version of a specific API resource or group. (e.g., Deployment, Pod, Service, ConfigMap etc.)
  • These API versions follow a format:
    • Alpha: v1alpha1, v1alpha2 (experimental, unstable, may change or be removed)
    • Beta: v1beta1, v1beta2 (more stable than alpha, but subject to change).
    • Stable: v1 (fully stable, backward-compatible).
post-image

Relationship Between Kubernetes and API Versions

Kubernetes version release determines the availability and defaulting of API versions. For example, a particular API version (like apps/v1) might be introduced as stable in a certain Kubernetes release (e.g., v1.9.0). Older API versions may be deprecated or removed in future Kubernetes releases. For instance, extensions/v1beta1 for Deployment objects was deprecated and replaced by apps/v1 in Kubernetes v1.16.0.

Kubernetes versioning doesn't necessarily map 1:1 to API versions. While the Kubernetes platform evolves, certain API versions might remain stable (e.g., core/v1) or change more slowly than Kubernetes releases.

Example: A Kubernetes cluster running v1.27.0 may support several API versions for the same resource. Like apps/v1beta1 (deprecated) and apps/v1 (stable) being supported at the same time. But in future releases, like v1.30.0, deprecated API versions may no longer be supported, and only stable versions like apps/v1 will be available.

Impact of Deprecated API Versions on Cluster Upgrades

Breaking Changes:

Deprecated API versions may be removed in newer Kubernetes versions. If your cluster uses these deprecated APIs, resources that rely on them may fail to work properly after the upgrade. For example, if you are using extensions/v1beta1 for Deployment resources and upgrade to a version where this API is removed, your resources will become unusable.

post-image
Deployment Failures:

Helm charts, custom resource definitions (CRDs), or YAML manifests that reference deprecated APIs will fail to apply or update.

Incompatibility:

Automation scripts, CI/CD pipelines, and third-party integrations that rely on deprecated API versions might break after the upgrade.

How to Overcome Issues from Deprecated APIs?

Audit for Deprecated APIs:

Before upgrading, you should audit your cluster to identify any resources or manifests that use deprecated API versions. This includes:

  • Inspecting Helm charts, YAML files, and other configurations.
  • Checking the Kubernetes API server logs for warnings about deprecated APIs being used.
Update Resources:

Update the resource definitions to use newer, stable API versions. For example, replace extensions/v1beta1 with apps/v1 for Deployments.

Test in a Staging Environment:

Perform a dry run or test the upgrade in a staging environment to ensure all deprecated APIs have been replaced and resources function as expected.

Plan for Gradual Upgrades:

If upgrading across multiple major versions, consider upgrading incrementally to avoid massive API version changes at once.

How kubent helps

post-image

kubent (Kube No Trouble) is one of the tools specifically designed to assist in identifying deprecated API versions in a Kubernetes cluster before performing an upgrade. Some other notable alternatives to this tool are Plural and Pluto . Here's how kubent helps:

  • Scan the Cluster: kubent scans all the resources in the cluster (including CRDs, Deployments, Services, etc.) and reports any instances where deprecated API versions are used.
  • Detailed Reporting: It lists the deprecated APIs found, shows which resources are using them, and provides information on the API version that should be used instead.
  • Upgrade Planning: By using kubent , you can get a clear view of which resources need to be updated before an upgrade, reducing the risk of downtime or deployment failures due to removed APIs.
  • Works Across Versions: It supports scanning for APIs deprecated across multiple Kubernetes versions, helping you ensure compatibility for major version upgrades.
Example Workflow with kubent :
  • Install kubent : You can install it as a binary or run it as a Kubernetes job.
  • Scan the Cluster: Run kubent to scan the cluster. The tool will generate a report listing all resources using deprecated API versions.

    Here's an example output of kubent run while jumping from v1.25.0 to v1.26.0
    • 											
$ kubent upgrade

Checking Kubernetes resources for deprecated APIs...

-----------------------------------
|          Upgrade Summary        |
-----------------------------------
Kubernetes Version: v1.25.0
Upgrade Target: v1.26.0

1. **Namespaces**:
	- No deprecated APIs found.

2. **Deployments**:
	- deployment/my-app:
		- Deprecated API version: extensions/v1beta1
		- Recommended API version: apps/v1
		- Action Required: Update your deployment manifest.

3. **Services**:
	- service/my-service:
		- No issues found.

4. **Ingress**:
	- ingress/my-ingress:
		- Deprecated API version: networking.k8s.io/v1beta1
		- Recommended API version: networking.k8s.io/v1
		- Action Required: Update your ingress manifest.

5. **CronJobs**:
	- cronjob/my-cronjob:
		- Deprecated API version: batch/v1beta1
		- Recommended API version: batch/v1
		- Action Required: Update your cron job manifest.

-----------------------------------
|           Recommendations       |
-----------------------------------
- Review and update the listed resources to ensure compatibility with Kubernetes v1.26.0.
- Test your applications in a staging environment after making changes.
- Backup your cluster and configurations before proceeding with the upgrade.

-----------------------------------
|           Upgrade Ready!        |
-----------------------------------
Your cluster is ready for the upgrade. Make the necessary changes before proceeding.
  • Update Resources: Based on the output, update the affected resources in your manifests or Helm charts to use the appropriate API versions.
  • Validate Changes: After updating the resources, run kubent again to ensure there are no remaining deprecated APIs.
  • Perform the Upgrade: Once all deprecated APIs are updated, proceed with the Kubernetes upgrade with confidence that your resources will remain compatible.

Summary

  • Kubernetes versions govern the platform as a whole, while API versions relate to the stability and availability of specific resources and groups.
  • Deprecated API versions can cause resource failures and deployment issues during cluster upgrades. To overcome these issues, you should audit and update resources to use the latest stable APIs.
  • By proactively addressing deprecated APIs, you can avoid many upgrade-related issues and ensure that your cluster is future-proof.
Share: