DEV Community

Cover image for What is Kubernetes API Deprecation.
Sandesh Pawar
Sandesh Pawar

Posted on

What is Kubernetes API Deprecation.

#kubernetes #devops #apiversions

Introduction

Kubernetes evolves rapidly, and with each release, APIs are improved, stabilized, or removed. While this evolution helps improve reliability and performance, it also introduces challenges for administrators and developers maintaining Kubernetes clusters.

One common issue teams encounter during cluster upgrades is API deprecation. If deprecated APIs are still being used in manifests, Helm charts, or automation scripts, deployments can fail, applications may stop working, and in severe cases, production outages can occur.

In this guide, we will explain:

  • What Kubernetes API deprecation means
  • Why deprecated APIs can break your workloads
  • How to identify deprecated APIs in your cluster
  • A practical example of converting deprecated APIs using kubectl-convert

What is Kubernetes API Deprecation?

Kubernetes is built around an API-driven architecture. Every resource inside a Kubernetes cluster — such as Pods, Deployments, Services, and Ingress — is defined and managed using APIs.

Users interact with these APIs using:

  • kubectl CLI
  • REST API
  • Client libraries
  • Infrastructure tools like Terraform or Helm

Each Kubernetes resource is defined with an apiVersion field in the manifest.

Example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
Enter fullscreen mode Exit fullscreen mode

The apiVersion determines which version of the Kubernetes API is used to create or manage the resource.

As Kubernetes evolves, APIs go through different stages:

  1. Alpha – Experimental and unstable
  2. Beta – Stable but may change
  3. GA (General Availability) – Production-ready

When an API version becomes outdated or is replaced by a better version, Kubernetes marks it as deprecated.

What Does API Deprecation Mean?

API deprecation means that an API version is still available but scheduled for removal in future Kubernetes releases.

Kubernetes maintains a strict policy regarding deprecated APIs:

  • Beta APIs are supported for at least 9 months or 3 releases
  • After that, they may be completely removed

For example:

extensions/v1beta1
Enter fullscreen mode Exit fullscreen mode

This API version for Ingress resources was removed starting from Kubernetes v1.22.

If you attempt to deploy resources using a removed API version, Kubernetes returns an error.

Example error:

Error: UPGRADE FAILED: current release manifest contains removed kubernetes api(s)
error from kubernetes: unable to recognize "": no matches for kind "Ingress" in version "extensions/v1beta1"
Enter fullscreen mode Exit fullscreen mode

Why Deprecated APIs Are Dangerous

Using deprecated APIs can cause serious operational issues.

1. Cluster Upgrade Failures

When upgrading Kubernetes clusters, manifests using deprecated APIs may fail to deploy.

This can break:

  • CI/CD pipelines
  • Helm upgrades
  • Infrastructure automation

2. Application Downtime

Applications depending on removed APIs may stop functioning after a cluster upgrade.

Even subtle API changes can introduce unexpected behavior and debugging complexity.

3. Compatibility Issues

Infrastructure tools such as:

  • Terraform providers
  • Helm charts
  • CI/CD pipelines

may depend on certain Kubernetes API versions. When those APIs are removed, compatibility breaks.

How to Identify API Versions in Kubernetes

You can list all supported API versions in your cluster using:

kubectl api-versions
Enter fullscreen mode Exit fullscreen mode

Example output:

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
Enter fullscreen mode Exit fullscreen mode

This command helps administrators verify which APIs are currently supported by the cluster.

However, identifying which resources actually use deprecated APIs inside your cluster can be challenging.

Example: Deprecated Ingress API

Below is an example of an old Ingress manifest using a deprecated API version.

cat ingress-old.yaml
Enter fullscreen mode Exit fullscreen mode 
---
# Deprecated API version
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: ingress-space
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - http:
      paths:
      - path: /video-service
        pathType: Prefix
        backend:
          serviceName: ingress-svc
          servicePort: 80
Enter fullscreen mode Exit fullscreen mode

This API version (networking.k8s.io/v1beta1) is deprecated and removed in newer Kubernetes versions.

How to Fix Deprecated Kubernetes APIs

One of the easiest ways to migrate deprecated APIs is by using the kubectl-convert tool.

This tool automatically converts manifests from older API versions to the latest supported version.

Step 1: Download kubectl-convert 

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl-convert"
Enter fullscreen mode Exit fullscreen mode

Output:

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
100 55.8M  100 55.8M    0     0  55.3M      0  0:00:01  0:00:01 --:--:-- 55.3M
Enter fullscreen mode Exit fullscreen mode

Step 2: Download the Checksum 

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl-convert.sha256"
Enter fullscreen mode Exit fullscreen mode

Step 3: Verify the Binary 

echo "$(cat kubectl-convert.sha256) kubectl-convert" | sha256sum --check
Enter fullscreen mode Exit fullscreen mode

Expected output:

kubectl-convert: OK
Enter fullscreen mode Exit fullscreen mode

Step 4: Install the Tool 

sudo install -o root -g root -m 0755 kubectl-convert /usr/local/bin/kubectl-convert
Enter fullscreen mode Exit fullscreen mode

Step 5: Verify Installation 

kubectl convert --help
Enter fullscreen mode Exit fullscreen mode

This command displays the usage instructions for converting Kubernetes manifests.

Step 6: Convert Deprecated Manifest

The correct command is:

kubectl-convert -f ingress-old.yaml --output-version networking.k8s.io/v1
Enter fullscreen mode Exit fullscreen mode

Converted output:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
  name: ingress-space
spec:
  rules:
  - http:
      paths:
      - backend:
          service:
            name: ingress-svc
            port:
              number: 80
        path: /video-service
        pathType: Prefix
status:
  loadBalancer: {}
Enter fullscreen mode Exit fullscreen mode

Step 7: Save the Converted Manifest 

kubectl-convert -f ingress-old.yaml --output-version networking.k8s.io/v1 > ingress-new.yaml
Enter fullscreen mode Exit fullscreen mode

Verify the new file:

cat ingress-new.yaml
Enter fullscreen mode Exit fullscreen mode

Step 8: Deploy the Updated Resource 

k create -f ingress-new.yaml
Enter fullscreen mode Exit fullscreen mode

Output:

ingress.networking.k8s.io/ingress-space created
Enter fullscreen mode Exit fullscreen mode

Step 9: Verify the Deployment 

k get ingress
Enter fullscreen mode Exit fullscreen mode

Example output:

NAME            CLASS    HOSTS   ADDRESS   PORTS   AGE
ingress-space   <none>   *                 80      6s
Enter fullscreen mode Exit fullscreen mode

Best Practices to Avoid API Deprecation Issues

To avoid disruptions caused by deprecated APIs, follow these best practices:

1. Monitor Kubernetes Release Notes

Always review release notes before upgrading clusters.

2. Regularly Audit Your Manifests

Check all YAML manifests, Helm charts, and automation scripts for deprecated APIs.

3. Use Tools for API Migration

Tools such as kubectl-convert help automate the migration process.

4. Test Upgrades in Staging Environments

Before upgrading production clusters, test upgrades in staging environments to identify deprecated API usage.

Conclusion

Kubernetes API deprecation is a normal part of the platform's evolution. However, failing to update deprecated APIs can lead to failed deployments, compatibility issues, and unexpected downtime.

Understanding how Kubernetes APIs evolve and knowing how to migrate deprecated resources is an essential skill for Kubernetes administrators and DevOps engineers.

By regularly auditing manifests and using tools like kubectl-convert, teams can ensure smooth cluster upgrades and maintain stable Kubernetes environments.

Top comments (0)