kubectl deprecations — inspecting manifest compatibility

kubectl deprecations is the command-line tool for inspecting manifests for deprecated API versions. The command was introduced as alpha in Kubernetes 1.30 and graduated to GA in 1.34. This lesson walks the command, the output format, and the integration with the upgrade workflow.

The command

kubectl deprecations --help

Inspect yaml files for deprecated API versions.

Usage:
  kubectl deprecations [flags]

Flags:
  -f, --filename strings   Files or directories to scan
  -R, --recursive          Recursively scan directories
  -o, --output string      Output format (table, json, yaml)

The command scans manifest files or directories for deprecated API versions.

The first scan

kubectl deprecations -f manifests/

FILE            API VERSION                   REPLACEMENT
manifests/pod.yaml     v1                  (current)
manifests/deploy.yaml  extensions/v1beta1   apps/v1
manifests/ingress.yaml extensions/v1beta1   networking.k8s.io/v1
manifests/cronjob.yaml batch/v2alpha1       batch/v1

The output lists each manifest, the deprecated API version, and the recommended replacement.

flowchart LR
    A[manifests/] --> B[pod.yaml v1 OK]
    A --> C[deploy.yaml extensions/v1beta1]
    A --> D[ingress.yaml extensions/v1beta1]
    A --> E[cronjob.yaml batch/v2alpha1]
    C --> F[replace with apps/v1]
    D --> G[replace with networking.k8s.io/v1]
    E --> H[replace with batch/v1]

The deprecated API versions

The Kubernetes project deprecates API versions in three stages:

1. Deprecated. The API is still served but scheduled for removal. Warnings are emitted on use.
2. Removed. The API is no longer served. Calls return 404 Not Found.

The project’s standard policy:

• 9 months between deprecation and removal.
• 3 minor versions of supported skew during the deprecation period.

For Kubernetes 1.34.x, the deprecated APIs include:

• extensions/v1beta1 (Ingress, NetworkPolicy, PodSecurityPolicy)
• apps/v1beta1, apps/v1beta2 (Deployment, StatefulSet, DaemonSet)
• batch/v2alpha1 (CronJob)
• policy/v1beta1 (PodSecurityPolicy)
• rbac.authorization.k8s.io/v1beta1 (Role, ClusterRole)

The list is current as of 1.34. Each minor docs release updates the list.

The output format

The default output is a table. The JSON output:

kubectl deprecations -f manifests/ -o json

[
  {
    "file": "manifests/deploy.yaml",
    "deprecated": "extensions/v1beta1",
    "replacement": "apps/v1",
    "since": "1.9.0"
  },
  {
    "file": "manifests/ingress.yaml",
    "deprecated": "extensions/v1beta1",
    "replacement": "networking.k8s.io/v1",
    "since": "1.14.0"
  }
]

The JSON output is suitable for CI/CD integration.

The directory scan

kubectl deprecations -f manifests/ -R

The -R flag recursively scans the directory. The command traverses subdirectories and inspects every manifest.

kubectl deprecations -f helm-chart/templates/ -R

A Helm chart is a directory of templates. The scan inspects every template.

Replacing the deprecated APIs

The output recommends the replacement. The replacement is typically a 1:1 mapping:

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

# After: manifest with current API
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 changes (e.g., pathType is required for networking.k8s.io/v1 Ingress) are part of the replacement.

The integration with the upgrade workflow

flowchart LR
    A[Cluster at v1.33.x] --> B[kubectl deprecations]
    B --> C[Deprecated APIs flagged]
    C --> D[Update manifests]
    D --> E[Re-scan until clean]
    E --> F[Upgrade to v1.34.x]

The cluster is not upgraded until the deprecations scan is clean. The pre-upgrade gate is the deprecation audit.

Cross-course references

• The OpenAPI / Kubernetes API reference documents the schemas.
• The Helm course covers chart template evolution.
• The Linux course covers static analysis tools.

Quiz

Production discipline

• Run kubectl deprecations before every upgrade. The audit is the pre-flight gate.
• Update manifests in Git. The manifest is the source of truth.
• Re-scan after updating. The audit is clean only when no deprecated APIs remain.
• Document the deprecation policy. The 9-month / 3-minor rule.
• Track deprecations in the runbook. The API version, the replacement, the migration date.

The deprecation audit is the cluster’s API hygiene. Operating it well is keeping the manifests current and the cluster supported.