Kubernetes Object Conversion Model

Kubernetes Object Conversion Model is the mechanism by which the API server translates an object between different versions of the same Kind, allowing a single stored object to be read and written correctly by clients requesting different API versions, and allowing the storage layer to standardize on one internal version regardless of how many versions a type is actually served under. Conversion is what makes multi-version coexistence within the API version model practically usable, rather than a purely theoretical possibility.

Why Conversion Is Necessary

One Storage Version, Many Served Versions

Every group-version-kind an object might be served under ultimately maps to a single storage version that the API server actually persists to etcd; when a client requests or submits an object in any other served version, the API server must convert between that version's shape and the storage version's shape, transparently to the client, on every read and write.

Version Differences Requiring Conversion

Differences between versions can include renamed fields, restructured nested objects, fields present in one version but not another, or fields whose meaning shifted as a type matured from alpha through beta to stable — conversion logic must account for every such difference to avoid silently losing or misinterpreting information as an object moves between versions.

Conversion for Built-In Types

Compiled Go Conversion Functions

Built-in types carry conversion logic implemented directly in the API server's Go codebase, typically generated in large part by code-generation tooling from field-level annotations, with hand-written conversion functions supplying logic for the cases that cannot be handled by straightforward field copying alone.

Round-Trip Correctness

Built-in conversion is expected to be round-trip safe wherever the target version can represent the same information: converting an object from version A to the storage version and back to version A should reproduce the original object exactly for any field both versions support, a property enforced through the project's own extensive conversion testing.

Conversion for Custom Resources

The Default: No-Op Conversion

When a CustomResourceDefinition serves multiple versions but does not configure a conversion webhook, the API server performs a purely structural, no-op conversion that assumes all served versions share an identical schema; this is only safe when versions truly are wire-compatible, since no actual field transformation occurs.

Conversion Webhooks

For CRDs whose versions genuinely differ in structure, the CRD spec can configure a conversion webhook — an external HTTP service the API server calls, sending the object and the target version, and receiving back the converted object — giving custom resource authors the same transformation capability built-in types have through compiled Go code, implemented instead as an external, independently deployable service.

Webhook Availability Risk

Because conversion webhooks sit in the request path for any read or write of a non-storage version, an unavailable or malfunctioning conversion webhook can block access to affected custom resources entirely, making the webhook's own reliability and the CRD's conversion strategy an operationally significant consideration for any CRD relying on this mechanism.

Conversion Review Requests

The Webhook Contract

A conversion webhook receives a ConversionReview request containing the objects to convert and the desired target apiVersion, and must return a ConversionReview response containing the converted objects in the same order, or a failure status if conversion cannot be performed, following a request/response contract analogous to the one used for admission webhooks.

Batch Conversion for Efficiency

Conversion requests can include multiple objects in a single ConversionReview call, particularly relevant for list operations returning many objects in a non-storage version, reducing the number of round trips to the conversion webhook compared to converting one object per call.

Interaction With Other API Mechanisms

Conversion Happens Before Admission

For incoming write requests, conversion to the storage version occurs before admission control and validation are applied against the object's storage-version representation, ensuring that validation logic, which is typically written against the storage version's schema, always evaluates a consistently structured object regardless of which version the client originally submitted.