Kubernetes API Group Model

Kubernetes API Group Model is the organizational scheme that partitions the Kubernetes API into named collections of related resource types, each identified by a group name and independently versioned, allowing the overall API surface to grow, evolve, and be extended by third parties without every resource type being forced to share a single flat namespace or a single version lifecycle. Rather than exposing hundreds of resource types as one undifferentiated list, the API group model gives each coherent area of functionality — workloads, networking, storage, policy, extension mechanisms — its own group boundary with its own versioning cadence.

The Structure of an API Group

Group, Version, Resource

Every API request in Kubernetes is addressed by a combination commonly abbreviated as GVR — group, version, and resource — with the URL path taking the form /apis/{group}/{version}/{resource} for most groups, or the historical /api/{version}/{resource} form reserved specifically for the core group.

The Core (Legacy) Group

The core group, sometimes called the legacy group, contains foundational types such as Pod, Service, Namespace, Node, and ConfigMap, and is the one group that predates the general group mechanism, which is why it is addressed without an explicit group name in its URL path and why its apiVersion field in manifests is written simply as v1 rather than somegroup/v1.

Named Groups

Named groups follow the general pattern, such as apps (containing Deployment, StatefulSet, DaemonSet, ReplicaSet), batch (containing Job and CronJob), networking.k8s.io (containing Ingress and NetworkPolicy), and rbac.authorization.k8s.io (containing Role and ClusterRole), each collecting resource types that share a coherent functional domain.

Independent Versioning per Group

Why Independent Versioning Matters

Because each group version advances independently, the apps group can promote a new field from alpha to stable without any coordination required from the batch or networking.k8s.io groups, and a cluster can simultaneously support multiple versions of the same group (such as both v1beta1 and v1 of a given type) during a migration window, which would be far harder to manage under a single monolithic API version.

Conversion Between Versions

When a group offers multiple versions of the same Kind, the API server is responsible for converting objects between versions transparently to the client, using a designated storage version internally while still serving and accepting requests in whichever version a particular client requests, which is what allows older clients and newer clients to interact with the same underlying objects without either being forced to upgrade in lockstep.

Discovery of Groups and Resources

The Discovery API

The API server exposes a discovery mechanism — endpoints such as /apis and /apis/{group}/{version} — that clients can query to learn which groups, versions, and resources a given cluster actually supports, which is essential because not every cluster enables every optional API group, and third-party or cluster-specific groups vary from installation to installation.

How kubectl Uses Discovery

Generic clients such as kubectl rely on this discovery information to resolve short names, determine whether a resource is namespaced, and route requests to the correct group and version automatically, which is why kubectl can operate uniformly across resource types it has no built-in, type-specific knowledge of.

Extending the Group Model

Custom Resource Definitions and New Groups

When a CustomResourceDefinition is registered, it is always registered under some API group — either an existing one, when extending established functionality, or, far more commonly, a new group name chosen by whoever defines the CRD, typically namespaced under a domain the definer controls, which avoids collisions between unrelated extensions defining resources with the same short name.

Aggregated API Servers and Group Ownership

For extensions implemented as aggregated API servers rather than CRDs, the extending component registers ownership of an entire group and version pair with the main API server, which then transparently proxies matching requests to the extension server, meaning the group model extends not just to what resource types exist but to which backend implementation is authoritative for serving them.

Practical Implications for Manifests

apiVersion as Group Plus Version

The apiVersion field present in every Kubernetes manifest is a direct encoding of the group model, combining group and version as group/version (or bare version for the core group); getting this field wrong is one of the most common sources of "no matches for kind" errors, since it reflects the exact GVR the API server's discovery mechanism must be able to resolve.