5.24 Kubernetes Object Conversion Model

Kubernetes Object Conversion Model is the internal machinery by which the API server translates an object between the different versions it serves for a given kind, ensuring a single stored representation can be correctly presented to clients requesting any supported version, and that objects submitted at one version are correctly transformed for storage and for any other version that might later request them.

Why Conversion Is Necessary

One Storage Version, Many Served Versions

A resource kind is typically persisted in etcd using exactly one designated storage version, yet the API server may serve that same kind at multiple versions simultaneously, meaning every read and write must pass through a conversion step translating between the client's requested version and the internal storage version.

Supporting Version Migration Without Breaking Clients

Conversion is what allows a cluster to introduce a new stable version of a resource while still serving an older, soon-to-be-deprecated version to clients that have not yet migrated, giving those clients a functioning bridge rather than an abrupt compatibility break.

Conversion for Built-In Types

Internal Version as a Hub

Built-in Kubernetes types are converted through an internal, unversioned Go representation that acts as a hub: external version A converts to the internal representation, and the internal representation converts to external version B, rather than requiring direct, pairwise conversion functions between every combination of served versions.

Generated and Hand-Written Conversion Functions

Much of this conversion logic is generated automatically from struct tags and naming conventions in the API server's Go source, though fields that changed shape or meaning between versions, rather than simply being renamed, require hand-written conversion functions to correctly translate semantics rather than just copying values field by field.

Conversion for Custom Resources

The Default: None Required for Single-Version CRDs

A Custom Resource Definition serving only a single version requires no conversion logic at all, since there is only one shape the object can ever take; conversion only becomes necessary once a CRD author introduces a second served version alongside the first.

None Strategy for Multi-Version CRDs

When multiple versions share an identical schema, differing only in name, a CRD can use the None conversion strategy, under which the API server serves the same stored bytes at every version without any actual transformation, appropriate only when the versions are truly interchangeable.

Webhook Conversion Strategy

When versions differ meaningfully in shape, a CRD specifies the Webhook conversion strategy, registering an external HTTP endpoint that the API server calls to perform the actual conversion, receiving objects at one version and returning them transformed to another, giving CRD authors full programmatic control over the conversion logic.

The Webhook Conversion Contract

Request and Response Structure

A conversion webhook receives a request containing a list of objects to convert and the desired target version, and must return a correspondingly ordered list of successfully converted objects, or explicit per-object failure information, allowing the API server to handle partial conversion failures gracefully within a batch.

Round-Trip Consistency Expectations

Well-designed conversion webhooks are expected to be round-trip consistent wherever possible, meaning converting an object from version A to version B and back to version A should not lose information that was present in the original, a property that matters because objects may be converted back and forth repeatedly as different clients request different versions over time.

Conversion and Storage Version Migration

Changing the Storage Version

When a resource's storage version changes, for example promoting from v1beta1 to v1 as the new canonical stored form, existing objects already persisted under the old storage version are not automatically rewritten; they continue to be stored in their original form and are converted on read until an explicit storage migration process rewrites them.

The Role of Storage Migration Tooling

Because unmigrated objects still round-trip correctly through conversion on every read, storage version changes do not cause immediate breakage, but administrators typically run a dedicated storage migration process afterward to actually rewrite older objects into the new storage version, both for consistency and to allow eventual removal of the old version's conversion path.

Conversion's Relationship to Validation and Defaulting

Ordering Within the Request Pipeline

Conversion to the internal or storage representation happens early in request processing, before validation and defaulting are applied against that internal representation, ensuring that validation rules, which are typically defined once against the canonical internal shape, apply consistently regardless of which external version a client originally submitted.