Kubernetes API Discovery Model

Kubernetes API Discovery Model is the set of endpoints and metadata the API server exposes to let clients learn, at runtime, exactly which API groups, versions, and resources a given cluster supports, including per-resource details such as whether a type is namespaced and which operations it allows, without any of that information needing to be hardcoded into the client beforehand. Because not every cluster runs the same set of API groups — optional features, CustomResourceDefinitions, and aggregated APIs vary from installation to installation — discovery is what allows generic tooling like kubectl to work correctly and safely against clusters whose exact API surface it has no prior knowledge of.

The Discovery Endpoints

Root Discovery

A request to /api returns the versions available under the core (legacy) group, while /apis returns the full list of named API groups the cluster serves along with their available versions, giving a client the top-level map of everything it could potentially interact with before drilling into any specific group.

Group-Version Resource Lists

For a specific group and version, a request to /apis/{group}/{version} (or /api/{version} for the core group) returns the list of resources available under that group-version, including each resource's name, whether it is namespaced, its supported verbs, its short names, and its associated Kind — everything a generic client needs to construct valid requests against that resource without type-specific code.

Aggregated Discovery

The Performance Problem With Per-Group Requests

In large clusters with many API groups, particularly those with numerous CustomResourceDefinitions each contributing their own group, retrieving full discovery information by querying every group-version endpoint individually can be slow, since it requires one HTTP round trip per group-version combination.

The Aggregated Discovery Endpoint

To address this, Kubernetes introduced an aggregated discovery document served from a single endpoint that returns discovery information for all groups and versions in one response, dramatically reducing the number of round trips a client needs to build a complete picture of the cluster's API surface, particularly beneficial for clients like kubectl that perform discovery routinely.

OpenAPI Schema Discovery

Beyond Resource Lists to Full Schemas

In addition to the lightweight discovery documents describing what resources exist, the API server exposes a full OpenAPI specification (available in both v2 and v3 forms depending on client needs) describing the complete schema for every type, including field names, types, descriptions, and validation constraints, which is what powers client-side validation, schema-aware editors, and tools that generate strongly typed client code from a live cluster's actual API surface.

OpenAPI v3 Per-Group-Version Documents

Rather than a single monolithic schema document, OpenAPI v3 discovery is split into per-group-version documents, retrievable individually, which keeps each document's size manageable and allows a client to fetch detailed schema information only for the specific types it actually needs to work with.

How Clients Use Discovery

kubectl's Reliance on Discovery

kubectl uses discovery extensively to resolve short names and Kind names typed by a user into the correct GroupVersionResource, to determine whether a given resource is namespaced (and therefore whether a -n flag is meaningful), and to validate manifest content against the live schema before submission, none of which requires kubectl to ship with hardcoded knowledge of every possible resource type, including custom ones defined only in a specific cluster.

Discovery Caching

Because discovery information changes relatively infrequently compared to object data, client libraries and kubectl typically cache discovery results locally with a modest expiration, refreshing only periodically or when a request fails in a way suggesting the cached discovery information may be stale, balancing responsiveness against the overhead of querying discovery endpoints on every single operation.

Discovery for RESTMapper Construction

Mapping User Input to API Requests

Discovery information is the direct input to building a RESTMapper, the component responsible for translating a Kind name (as written by a user in a manifest) into the correct GroupVersionResource and namespaced-or-cluster-scoped routing needed to construct an actual API request, meaning discovery is not merely informational but a functional prerequisite for any generic client to operate correctly against a given cluster.