apiversion

apiVersion is a field used in API requests and resource definitions to indicate the version of the API and the corresponding data schema that should be used to process the resource. It helps clients and servers agree on how a resource is structured and validated, and it supports evolving APIs without breaking existing integrations.

In Kubernetes manifests, apiVersion is typically the first line of the resource description, and it identifies both the API group and the version, such as v1 for core resources or apps/v1 for resources in the apps group. Examples include apiVersion: v1 for core resources like Pod and Service, and apiVersion: apps/v1 for resources like Deployment and StatefulSet. The exact set of available versions depends on the API group and the Kubernetes cluster’s version.

The primary purpose of apiVersion is to enable API versioning and backward compatibility. Different versions may expose different fields or behavior, so the server routes requests to the appropriate code paths and validates payloads against the correct schema. This allows multiple versions to coexist, supports feature gating, and provides a path for deprecating older versions over time.

Version management encourages clients to specify stable, supported versions and to migrate when versions are deprecated. In practice, resource definitions may be updated to newer versions, while old versions are gradually phased out. It is also worth noting that in contexts outside Kubernetes, the term apiVersion may appear in different APIs or, in some tools like Helm, Chart.yaml, but in Kubernetes manifests it specifically denotes the API group and version of the resource.