API removal planning — the 9-month calendar

The Kubernetes project’s API deprecation policy is the operator’s planning tool. The policy gives a 9-month window for deprecated APIs to be removed; during that window, the API is supported across 3 minor versions. This lesson walks the policy, the timeline, and the planning involved.

The policy

The Kubernetes project’s API deprecation policy:

• 9 months between deprecation announcement and API removal.
• 3 minor versions of supported skew during the deprecation period.
• The deprecated API continues to be served (with warnings) during the deprecation period.
• After removal, the API returns 404 Not Found for all calls.

gantt
    title API deprecation timeline
    dateFormat  YYYY-MM-DD
    section API
    Available (current)           :done,    a1, 2025-01-01, 365d
    Deprecated (warnings emitted) :active,  a2, 2026-01-01, 270d
    Removed (404 Not Found)       :         a3, 2026-10-01, 365d

The policy is intentionally generous. The 9-month window gives operators time to plan, test, and roll out the migration.

The deprecation list

The Kubernetes project documents the deprecated APIs in the API deprecation guide:

The list is current as of 1.34. The “Removed in” column shows the version where the API is no longer served.

The timeline

A typical migration timeline:

2025-09-01: extensions/v1beta1 Ingress deprecated in 1.14
2025-09-01: 9-month clock starts
2026-06-01: extensions/v1beta1 Ingress removed in 1.22

The operator must:

1. Update the manifests to networking.k8s.io/v1 before the removal version.
2. Test the migration in staging.
3. Roll out the migration to production.
4. Verify the cluster has no extensions/v1beta1 Ingress objects.

The 9-month window is the planning period.

The cluster audit

The cluster audit identifies the deprecated API objects:

kubent --target-version=v1.34.0

The output lists the deprecated API objects that are still running. Each object must be migrated to the replacement API before the removal version.

flowchart LR
    A[Cluster] --> B[kubent]
    B --> C[Deprecated API objects]
    C --> D{Replace with new API?}
    D -->|yes| E[Update manifest]
    D -->|no| F[Investigate]
    E --> G[Apply manifest]
    G --> H[Audit clean]

The manifest update

The manifest update is the schema change. The new API may have:

• New required fields. e.g., pathType for Ingress networking.k8s.io/v1.
• Different field types. e.g., backend.service (object) vs backend.serviceName (string).
• Removed fields. e.g., spec.backend for Ingress.

# Before: extensions/v1beta1
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: my-ingress
spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            backend:
              serviceName: my-service
              servicePort: 80

# After: networking.k8s.io/v1
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-service
                port:
                  number: 80

The schema change is significant; the operator must read the migration guide.

The migration guide

The migration guide is the canonical documentation for the API replacement. The Kubernetes project publishes a migration guide for each deprecated API:

URL: https://kubernetes.io/docs/reference/using-api/deprecation-guide/

The migration guide covers:

• The new API version.
• The schema changes.
• The migration steps.
• The example manifests.

The operator reads the guide before updating the manifests.

The failure mode

A missed API removal causes immediate failures:

After upgrading to 1.22:
  - extensions/v1beta1 Ingress is no longer served
  - kubectl get ingress returns 404 Not Found
  - The Ingress objects are unreachable
  - The cluster's HTTP routing breaks

The cluster is broken; the operator must escalate to restore.

The mitigation is the pre-flight audit: the operator runs kubent before the upgrade and addresses the deprecated APIs.

Cross-course references

• The Helm course covers chart template evolution.
• The CI/CD course covers pipeline integration.
• The Observability course covers upgrade validation.

Quiz

Production discipline

• Track the deprecation calendar. 9 months is the planning window.
• Audit the cluster before every upgrade. kubent is the tool.
• Read the migration guide. The schema changes are significant.
• Test the migration in staging. Catch the schema changes before production.
• Roll out the migration. Apply the new manifests; verify the cluster.
• Document the migration. The audit, the manifest updates, the rollout.

The API removal is the cluster’s planning event. Operating it well is keeping the calendar current and the migration rehearsed.