5.5 Kubernetes Kind and Resource Model

Kubernetes Kind and Resource Model is the pairing of two related but distinct concepts within the API: the kind, which describes the schema and semantic type of an individual object, and the resource, which describes the API-addressable, pluralized collection through which objects of that kind are created, retrieved, and manipulated, together forming the basic typing system underlying every interaction with the cluster.

What a Kind Represents

Schema Identity

A kind, such as Pod, Deployment, or Namespace, identifies the structural schema an object conforms to, defining what fields are valid within its spec and what fields the system populates within its status, serving the same role a class or type definition plays in a programming language.

TypeMeta Fields

Every object declares its kind explicitly through the kind and apiVersion fields at the top level of its manifest, together forming what internal API machinery refers to as TypeMeta, allowing generic tooling and the API server itself to determine how to parse and validate the rest of the object body.

Kinds Are Not Always One-to-One With Resources

While most kinds correspond to exactly one resource, certain kinds exist purely as request or response shapes rather than as persisted, listable objects, such as Status, returned in error responses, or Scale, which represents a view onto multiple different underlying workload resources rather than being an independently stored object itself.

What a Resource Represents

The Addressable Collection

A resource, such as pods or deployments, is the pluralized name used to construct REST paths and is the unit against which HTTP verbs are actually applied; creating an object means issuing a POST to a resource's collection endpoint, not directly to a kind.

Resource Naming Conventions

Resource names are conventionally lowercase and pluralized, and the API server's RESTMapper maintains the authoritative mapping from each kind to its corresponding resource name, since pluralization is not always a mechanical transformation and can be explicitly overridden when a Custom Resource Definition is registered.

Short Names and Categories

Resources can declare short names, such as po for pods or deploy for deployments, used as convenient abbreviations in command-line tooling, and can also be grouped into categories, such as all, allowing a single command to operate across a curated set of related resource types.

List Kinds

The Companion List Type

For every kind representing an individual object, there is a corresponding list kind, such as PodList for Pod, returned when a client requests the full collection of objects for a resource, wrapping the individual items alongside collection-level metadata such as a shared resourceVersion for the list as a whole.

Watch Stream Event Kinds

When a client establishes a watch against a resource, the events streamed back are not raw objects of the resource's kind directly, but rather watch event envelopes containing a type, such as ADDED, MODIFIED, or DELETED, and the object itself, layering event semantics on top of the underlying kind and resource model.

The Object Reference Pattern

Referencing by Kind, Name, and Namespace

Many API objects reference other objects using an object reference structure that typically includes the target's kind, API version, name, and namespace, allowing loosely coupled relationships between objects, such as an OwnerReference linking a Pod to the ReplicaSet that created it, without requiring a rigid foreign-key-style schema.

OwnerReferences and Garbage Collection

OwnerReferences specifically use this kind-and-resource-aware reference pattern to establish ownership chains that the garbage collector controller walks when deciding whether a dependent object should be automatically deleted after its owner is removed.

Custom Resources Within the Same Model

Full Participation in the Model

A Custom Resource Definition registers both a new kind and its corresponding resource simultaneously, specifying the plural resource name, singular name, short names, and categories explicitly, ensuring custom types slot into the identical kind-and-resource model that built-in types use.

Schema Enforcement via OpenAPI

Custom resources define their kind's schema using an embedded OpenAPI v3 schema within the CustomResourceDefinition object itself, giving the API server the same structural validation capability for custom kinds that it has natively for built-in ones.

Why the Separation Matters

Decoupling Schema From Access Path

Separating the schema concept, kind, from the access path concept, resource, allows the same underlying schema to be exposed through different resource paths in specific cases, such as subresources, while keeping the conceptual type identity of the object consistent and unambiguous across the whole API.