Kubernetes CRD Version Management

Kubernetes CRD Version Management is the ongoing operational process of introducing, prioritizing, deprecating, and retiring API versions of a custom resource over its production lifetime, distinct from the one-time schema and conversion mechanics of a version transition: it is the discipline of sequencing changes so that clients, controllers, and stored data remain continuously functional across every step.

Version Naming and Priority Ordering

The Kubernetes Version Priority Convention

Custom resource versions follow the same naming convention as core Kubernetes APIs — v1, v2, v1beta1, v1alpha1 — and the API server uses this convention to determine the default version returned by discovery and by tools like kubectl api-resources when no explicit version is requested.

spec:
  versions:
    - name: v1alpha1
      served: true
      storage: false
    - name: v1beta1
      served: true
      storage: false
    - name: v1
      served: true
      storage: true

Stable versions (v1, v2) are prioritized over beta versions, which are prioritized over alpha versions, and within the same stability tier, higher numbers are prioritized over lower ones; this ordering determines which version a generic client receives by default, independent of which version is marked as the storage version.

The Version Lifecycle Process

Introducing a New Version

A new version begins as served: true, storage: false, running alongside the existing storage version, allowing early adopters to read and write against the new shape (translated through a conversion webhook) while the majority of stored objects and controllers remain on the prior stable version.

kubectl get postgresclusters.v1alpha2.databases.example.com

Promoting a Version to Storage

Once client and controller ecosystems have migrated to rely on the new version, storage: true is moved to it in a controlled rollout, after which every subsequent write persists objects in the new shape, while previously stored objects remain in the old shape until they are next written.

kubectl get postgresclusters --all-namespaces -o json \
  | jq -r '.items[] | select(.apiVersion=="databases.example.com/v1alpha1")'

Auditing which objects remain on the prior storage version, as above, is the standard way to measure how much of the storage migration remains outstanding before the old version can be safely dropped.

Completing Migration with Storage Version Migrator

apiVersion: migration.k8s.io/v1alpha1
kind: StorageVersionMigration
metadata:
  name: migrate-postgresclusters
spec:
  resource:
    group: databases.example.com
    resource: postgresclusters
    version: v1

The StorageVersionMigration custom resource, provided by the kube-storage-version-migrator component, triggers a no-op re-write of every existing object of a given type, forcing them onto the current storage version without requiring any actual field change, completing the migration deterministically rather than waiting for organic writes to touch every object.

Deprecation Policy and Communication

Marking a Version Deprecated

spec:
  versions:
    - name: v1alpha1
      served: true
      deprecated: true
      deprecationWarning: "batch.example.com/v1alpha1 CronBackup is deprecated; use v1"

The deprecationWarning string is surfaced to clients as an HTTP warning header on every request against the deprecated version, giving automated tooling and human operators a machine-readable signal to act on before the version is removed.

Support Window Discipline

Following the same discipline Kubernetes itself applies to its built-in APIs, a deprecated custom resource version is conventionally kept served: true for a defined minimum window (commonly aligned to a number of minor Operator releases) before being dropped from served entirely, giving downstream consumers — other controllers, CI pipelines, dashboards — adequate notice to migrate.

Retiring a Version

Removing from Served, Then from the Version List

spec:
  versions:
    - name: v1
      served: true
      storage: true

A version is first set to served: false while remaining in the versions list (still convertible for any objects that somehow remain, though none should by this stage), and only removed from the list entirely once verified that zero stored objects reference it and no client traffic targets it.

Verifying Zero Remaining Consumers

kubectl get --raw "/apis/databases.example.com/v1alpha1" 2>&1
kubectl get events --field-selector reason=DeprecatedVersion

Checking audit logs or API server metrics such as apiserver_requested_deprecated_apis for continued usage of a version scheduled for removal is a required verification step, since silent removal of a version still in active use breaks any client or controller still targeting it.

Coordinating Version Management with Operator Upgrades

Operator and CRD Version Coupling

Because a single CRD's CustomResourceDefinition object is shared cluster-wide, an Operator upgrade that introduces a new served version must remain backward compatible with any older Operator replica still running during a rolling upgrade, and multi-version support in the CRD is what allows both old and new Operator code to coexist briefly during that rollout without either failing to parse objects written by the other.

Relationship to CRD Management and Spec Structure

Version management is the temporal, process-oriented counterpart to the structural conversion and schema mechanics covered under general CRD management: where CRD management and spec structure define what a version transition technically requires (conversion webhooks, structural schema, subresources), version management defines the sequence, timing, and verification steps that make executing that transition safe in a live, continuously running cluster.