5.3 Kubernetes API Group Model

Kubernetes API Group Model is the organizational scheme that partitions the entirety of the Kubernetes API surface into named collections of related resource types, each identified by a group name and a set of supported versions, providing the structural backbone that allows the API to grow, evolve, and be extended without every resource type competing within a single flat namespace.

The GroupVersionKind and GroupVersionResource Triples

Identifying an API Type

Every object type in Kubernetes is uniquely identified by a GroupVersionKind, or GVK, consisting of the API group it belongs to, the specific version within that group, and the kind name itself, such as apps/v1/Deployment, giving a fully qualified coordinate for any type across the entire API.

Identifying a Resource Endpoint

Correspondingly, a GroupVersionResource, or GVR, identifies the pluralized, addressable API endpoint for a type, such as apps/v1/deployments, which is the coordinate actually used when constructing REST paths or dynamic client requests against the API server.

Mapping Between Kinds and Resources

The API server's RESTMapper component maintains the mapping between GVKs and GVRs, since a kind's plural resource name is not always a simple, mechanical pluralization, and some kinds map to resources with different casing or naming conventions entirely.

The Core Group

Historical Origin

The core group, sometimes called the legacy group, contains foundational types such as Pod, Service, Namespace, and ConfigMap, and is addressed without any group name prefix in the API path, using just /api/v1/ rather than the /apis/<group>/<version>/ pattern used by every other group.

Why It Remains Unnamed

The core group predates the introduction of formal API grouping in Kubernetes' early development, and rather than migrating these foundational types into a named group, which would have broken compatibility for every existing client, the project preserved the unnamed core group permanently.

Named API Groups

Naming Convention

Named groups typically use a reverse-DNS-style naming convention, such as apps, batch, networking.k8s.io, or rbac.authorization.k8s.io, with built-in Kubernetes groups often using a bare word or a k8s.io suffixed domain, while extension groups commonly use a domain the extending organization controls.

Grouping by Functional Domain

Resources are grouped according to functional domain rather than by which controller happens to manage them, so apps contains workload controllers like Deployment, StatefulSet, and DaemonSet, while networking.k8s.io contains Ingress and NetworkPolicy, keeping related concepts discoverable together.

Multiple Versions Within a Group

A single group frequently exposes multiple versions simultaneously during a migration period, such as a resource being available at both v1beta1 and v1, allowing existing clients time to migrate to a newer, more stable version before the older one is eventually removed.

Group Priority and Discovery

Discovery Document Structure

The API server's discovery endpoints organize their output by group, listing each group's name, its available versions, and which version is currently considered the group's preferred version, information that clients use to select a sensible default version when none is explicitly specified.

Preferred Version Selection

Group priority values influence how tools like kubectl present or default to a particular version when a user does not specify one explicitly, generally favoring the most stable available version over alpha or beta releases within the same group.

Extension Groups for Custom Resources

Custom Resource Definition Group Assignment

When a Custom Resource Definition is registered, its author chooses a group name, conventionally a domain the author controls, such as example.com, preventing naming collisions with built-in groups or with custom resources defined by unrelated projects.

Aggregated API Server Groups

Groups served by an aggregated API server, rather than by CRDs stored directly in the main API server's etcd, appear identically within the discovery and grouping model from a client's perspective, even though the actual implementation and storage backend differ substantially.

Practical Effects of the Group Model

RBAC Scoping

Kubernetes RBAC rules specify permissions using API groups alongside resource names, allowing policy authors to grant or restrict access at the granularity of an entire group, such as permitting all operations within batch, or scoping down to individual resources within a group.

Client Library Organization

Generated client libraries, such as the Go client-go library, typically mirror the group structure directly in their package organization, so that working with Deployments involves the apps/v1 client package while working with Jobs involves the batch/v1 client package, reflecting the underlying API group model in code structure.