Kubernetes Kind and Resource Model

Kubernetes Kind and Resource Model is the specific naming and mapping convention that connects a type's schema identity, its Kind, to the URL path clients actually use to interact with instances of that type, its resource, along with the rules that govern how these two identifiers relate to each other when a Kind is exposed in more than one way. While closely related to the broader API resource model, this distinction specifically addresses the mechanics of how the API server and client tooling translate between "what type of object is this" and "what HTTP path do I use to manage it," which is not always a simple one-to-one relationship.

Kind as Schema Identity

GroupVersionKind

A Kind, combined with its API group and version, forms a GroupVersionKind (GVK) triple that uniquely identifies a specific schema — for instance, apps/v1, Kind=Deployment — and this triple is what appears in an object's apiVersion and kind fields, serving as the object's self-declared type identity independent of any particular URL it might be accessed through.

Kind Naming Conventions

Kind names follow PascalCase, singular naming (Pod, not pods or Pod plural), and by convention are chosen to read naturally as a noun describing a single instance, which is why manifests read as declarations of one Pod, one Deployment, or one Service, even though the underlying storage and API paths are collection-oriented.

Resource as URL Identity

GroupVersionResource

A resource, combined with its group and version, forms a GroupVersionResource (GVR) triple — such as apps/v1, Resource=deployments — and this is what appears in the actual REST path clients send requests to; resources are conventionally lowercase and plural, reflecting that the path addresses a collection which individual named objects live within.

The RESTMapper

The API server (and client libraries built against it) maintains a mapping, often called a RESTMapper, translating between GVK and GVR in both directions, which is what allows a client that only knows a Kind name (as written in a YAML manifest) to determine the correct URL path to submit that object to, and vice versa when interpreting a response.

Non-Trivial Kind-to-Resource Relationships

Subresources Sharing a Kind

A single Kind can be associated with multiple resource paths through subresources — a Pod's main resource path returns and accepts a full Pod object, while its status subresource path operates on the same Kind but restricts what fields can be meaningfully written, and its log subresource returns an entirely different, non-object payload despite being nested under the same resource.

Scale Subresource as a Distinct View

The scale subresource, present on Deployments, ReplicaSets, StatefulSets, and other scalable types, exposes a deliberately reduced view (essentially just a replica count and selector) rather than the full Kind's schema, which allows generic tooling such as the Horizontal Pod Autoscaler to read and adjust replica counts across many different Kinds through one uniform, minimal interface rather than needing type-specific logic for each scalable Kind.

Short Names and Categories

Short Names

Many resources register one or more short names — such as po for pods or svc for services — purely as a convenience recognized by kubectl and resolved through the same discovery mechanism as the canonical resource name, reducing typing without introducing an alternate canonical identity for the type.

Categories

Resources can also be grouped into categories, such as all, which kubectl get all uses to retrieve objects across many resource types in a single command; categories are a convenience grouping layered on top of the Kind and resource model rather than a structural part of any individual type's identity.

Implications for CustomResourceDefinitions

Declaring Kind and Resource Together

When registering a CustomResourceDefinition, the author explicitly declares both the Kind name and the plural resource name (along with optional short names), and the API server derives the GVK-to-GVR mapping from this declaration exactly as it does for built-in types, meaning custom types participate in the same kind/resource conventions, discovery mechanisms, and RESTMapper resolution as any type shipped with Kubernetes itself.