How Does Kubernetes API Versioning Work?

Detailed Answer

Kubernetes exposes its functionality through a versioned REST API. Understanding how API versioning works is essential for writing correct manifests, planning cluster upgrades, and working with custom resources.

API Groups and Versions

Every Kubernetes resource belongs to an API group and is served at a specific version. The apiVersion field in a manifest combines these:

# Core group (legacy) — no group name, just "v1"
apiVersion: v1
kind: Pod

# Named group "apps" at version "v1"
apiVersion: apps/v1
kind: Deployment

# Named group "batch" at version "v1"
apiVersion: batch/v1
kind: CronJob

# Named group "networking.k8s.io" at version "v1"
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy

The core group contains fundamental resources like Pods, Services, ConfigMaps, and Secrets. Named groups allow the API to evolve independently — the apps group can release v2 without affecting batch.

Version Levels

| Level | Example | Enabled by Default | Stability | |-------|---------|-------------------|-----------| | Alpha | v1alpha1 | No (requires feature gate) | May change or be removed at any time | | Beta | v1beta1 | Yes (since 1.22, beta APIs require opt-in for new APIs) | Schema and semantics may change | | Stable | v1 | Yes | Backward-compatible, will not be removed |

The Deprecation Policy

Kubernetes follows a strict deprecation policy:

• GA (stable) APIs: Never removed within a major version (v1.x)
• Beta APIs: Available for at least 9 months or 3 releases after deprecation
• Alpha APIs: Can be removed in any release without notice

A practical example: extensions/v1beta1 Ingress was deprecated in 1.14, replaced by networking.k8s.io/v1beta1 in 1.19, and then networking.k8s.io/v1 became stable in 1.22. The beta was removed in 1.22.

Discovering Available APIs

# List all API group/version pairs
kubectl api-versions

# List all resources with their API group
kubectl api-resources

# Get details about a specific resource
kubectl explain deployment --api-version=apps/v1

# Check if a specific API is available
kubectl get --raw /apis/batch/v1 | jq .

Storage Versions

The API server can serve the same resource at multiple versions simultaneously (e.g., v1 and v1beta1), but it stores objects in etcd using a single storage version. When you read an object at a different version, the API server converts it on the fly.

# See which version is the storage version
kubectl get --raw /apis/apps | jq '.versions[] | select(.storage==true)'

Migrating Manifests Between Versions

When upgrading a cluster, you may need to update manifests to use newer API versions:

# Check for deprecated APIs in your manifests
# Using kubectl-convert plugin (install separately)
kubectl convert -f old-deployment.yaml --output-version apps/v1

# Or use tools like pluto to scan your cluster
# pluto detect-helm -owide
# pluto detect-files -d ./manifests/

Custom Resource Versions

CRDs (Custom Resource Definitions) also use API versioning. You can serve multiple versions of a custom resource with conversion webhooks:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myresources.example.com
spec:
  group: example.com
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                replicas:
                  type: integer
    - name: v1beta1
      served: true
      storage: false
  scope: Namespaced
  names:
    plural: myresources
    singular: myresource
    kind: MyResource

Best Practices for API Version Management

1. Always use stable versions in production manifests when available
2. Run deprecation checks before cluster upgrades using tools like pluto or kubent
3. Pin API versions in Helm charts and update them as part of your upgrade runbook
4. Test with --dry-run=server to validate manifests against the cluster's current API server
5. Watch Kubernetes release notes for deprecation announcements — they are listed prominently

Feature Gates and Alpha APIs

Alpha APIs require explicit opt-in via feature gates on the API server:

# kube-apiserver flag
--feature-gates=SomeAlphaFeature=true
--runtime-config=example.k8s.io/v1alpha1=true

Never enable alpha features in production clusters unless you fully understand the implications and are prepared for breaking changes.