5.22 Kubernetes API Discovery Model

Kubernetes API Discovery Model is the mechanism through which a client determines, at runtime, what API groups, versions, and resources a given cluster actually supports, along with the operations and schema each resource exposes, allowing generic tooling to function correctly against clusters whose exact set of available APIs varies by version, configuration, and installed extensions.

Why Runtime Discovery Is Necessary

Variability Across Clusters

Different clusters expose different sets of API resources depending on their Kubernetes version, enabled feature gates, and installed Custom Resource Definitions or aggregated API servers, meaning a client that hardcoded an assumed fixed API surface would break against any cluster whose available resources differed even slightly from that assumption.

Enabling Generic Tooling

Tools like kubectl need to operate correctly against resource types they have no built-in knowledge of, such as a newly installed custom resource, which is only possible because they query the cluster's discovery endpoints at runtime rather than relying solely on a compiled-in list of known types.

The Discovery Endpoints

Group and Version Enumeration

The root discovery endpoint enumerates every available API group and, for each, its supported versions and which version is currently preferred, giving a client a top-level map of the entire API surface before it needs to inspect any specific group in detail.

Resource Enumeration Within a Group Version

For each specific group and version, a further discovery request returns the list of resources available at that group version, including each resource's name, whether it is namespaced, its supported HTTP verbs, and its associated kind, giving a client everything needed to construct valid requests against that resource without prior hardcoded knowledge.

Aggregated Discovery

Modern Kubernetes versions support an aggregated discovery endpoint that combines what would otherwise require many separate requests, one per group version, into a single response, substantially reducing the number of round trips a client needs to perform a full discovery of the cluster's API surface.

OpenAPI Schema Discovery

Full Schema Publication

Beyond the coarse resource listing, the API server publishes a complete OpenAPI document describing the detailed field-level schema of every resource type, which tools use for client-side validation, generating typed client code, and providing interactive documentation or auto-completion.

OpenAPI v2 and v3 Coexistence

The API server has historically published OpenAPI v2 documents and has added support for OpenAPI v3, with v3 offering improved expressiveness, particularly around polymorphic types and more precise validation constraints, while v2 remains available for compatibility with older tooling still expecting that format.

The RESTMapper

Bridging Kind and Resource Names

Client libraries build a RESTMapper from discovery data, resolving a given kind, such as Deployment, to its correct GroupVersionResource and REST path, handling irregular pluralizations and group assignments that a purely mechanical name transformation would get wrong.

Caching and Refresh Behavior

Because querying full discovery data on every single request would be wasteful, client tooling typically caches discovery results locally, refreshing only periodically or when an operation against an unrecognized resource type fails, balancing responsiveness to newly installed resource types against unnecessary repeated discovery calls.

Discovery's Role in Extension Mechanisms

Custom Resources Appearing Automatically

When a Custom Resource Definition is registered, its corresponding resource and kind automatically appear in subsequent discovery responses without requiring any change to the API server's own code, which is precisely what allows generic tools to work with custom resources identically to how they work with built-in ones.

Aggregated API Servers and Discovery

An aggregated API server registered through the aggregation layer must itself implement the discovery protocol correctly, since the main API server proxies discovery requests for that group to the aggregated server, meaning discovery consistency is a requirement for any API server wishing to integrate properly into the cluster's overall API surface.

Practical Consumers of Discovery

kubectl's Reliance on Discovery

Commands such as kubectl api-resources and kubectl explain are thin, direct consumers of the discovery and OpenAPI endpoints, while more fundamentally, nearly every kubectl command resolving a short resource name or plural form to its actual API endpoint depends on discovery data under the hood.