kubectl api-versions

When to Use kubectl api-versions

kubectl api-versions prints every API group/version combination the cluster supports. This is critical for writing correct manifests, planning Kubernetes upgrades, and troubleshooting deployment failures caused by API deprecation.

Understanding the Output

The output is a simple list of group/version strings:

admissionregistration.k8s.io/v1
apps/v1
autoscaling/v1
autoscaling/v2
batch/v1
certificates.k8s.io/v1
networking.k8s.io/v1
policy/v1
v1

The entry v1 (without a group prefix) represents the core API group, which includes fundamental resources like Pods, Services, ConfigMaps, and Secrets. All other entries have a group prefix.

Checking API Availability Before Deployment

Before applying a manifest, verify its apiVersion is supported:

# Your manifest uses networking.k8s.io/v1
kubectl api-versions | grep networking.k8s.io/v1
# If there's output, the API is available

# Check if the legacy Ingress API is still available
kubectl api-versions | grep extensions/v1beta1
# Empty output means it's been removed

API Deprecation Timeline

Kubernetes follows a structured deprecation policy:

1. GA (v1): Stable, no planned removal.
2. Beta (v1beta1, v2beta1): May change or be removed after 3 releases.
3. Alpha (v1alpha1): Can be removed at any time.

Track deprecations with:

# Find any beta APIs still in use
kubectl api-versions | grep beta

# Find alpha APIs (these are experimental)
kubectl api-versions | grep alpha

Migration Planning

When upgrading Kubernetes, check which APIs are being removed in the target version. Common historical removals include:

| Removed API | Replacement | Removed In | |-------------|------------|------------| | extensions/v1beta1 Ingress | networking.k8s.io/v1 | 1.22 | | apps/v1beta1 Deployment | apps/v1 | 1.16 | | policy/v1beta1 PodSecurityPolicy | Removed entirely | 1.25 | | autoscaling/v2beta2 | autoscaling/v2 | 1.26 |

Before upgrading, scan your manifests:

# Find manifests using deprecated APIs
grep -r "apiVersion: extensions/v1beta1" manifests/
grep -r "apiVersion: apps/v1beta" manifests/

# Use kubectl-convert to migrate
kubectl convert -f old-ingress.yaml --output-version networking.k8s.io/v1

Comparing Versions Across Clusters

If a deployment works in staging but fails in production, API version differences may be the cause:

# Compare available APIs
diff <(kubectl api-versions --context=staging | sort) \
     <(kubectl api-versions --context=production | sort)

This immediately shows which API groups are available in one cluster but not the other.

CRD-Provided APIs

Operators and controllers register their own API groups:

# Prometheus Operator APIs
kubectl api-versions | grep monitoring.coreos.com
# monitoring.coreos.com/v1

# Cert-Manager APIs
kubectl api-versions | grep cert-manager.io
# cert-manager.io/v1

If these entries are missing, the corresponding CRDs have not been installed.

Using in CI/CD Pipelines

Validate API compatibility as a pre-deployment check:

#!/bin/bash
REQUIRED_APIS="networking.k8s.io/v1 apps/v1 batch/v1"
AVAILABLE=$(kubectl api-versions)

for api in $REQUIRED_APIS; do
  if ! echo "$AVAILABLE" | grep -q "^${api}$"; then
    echo "ERROR: Required API $api not available"
    exit 1
  fi
done
echo "All required APIs available."

Relationship to kubectl api-resources

While api-versions shows group/version combinations, api-resources shows the actual resource types within those groups. Use them together for a complete picture:

# List API versions for networking
kubectl api-versions | grep networking
# networking.k8s.io/v1

# List resources in that group
kubectl api-resources --api-group=networking.k8s.io
# ingresses, networkpolicies, ingressclasses