1.6 Kubernetes Object Definition
Kubernetes Object Definition explains how resources are structured and managed in a Kubernetes cluster.
Kubernetes Object Definition is the precise characterization of a Kubernetes object as a persistent record, stored by the API server, that represents the desired or observed state of some entity in the cluster, distinguished from a transient API request by the fact that it continues to exist and be acted upon after the request that created it has completed.
What Makes Something an Object
Persistence Beyond a Single Request
An object is defined by its persistence: once created, it is stored durably in the cluster's data store and remains addressable through the API until explicitly deleted, unlike a one-off command whose effect is not separately recorded as a standing entity.
A Record of Intent and Observation
Every object simultaneously records intent, through its spec, and observation, through its status, meaning an object is not merely a snapshot but an ongoing record that clients declare into and controllers report against over time.
Required Fields of an Object
apiVersion and kind
Every object must declare an apiVersion and kind, which together determine how the API server interprets and validates its structure; without these, a submitted document cannot be recognized as any particular type of object at all.
metadata
Every object carries metadata, including a name unique within its scope, and typically a namespace, uid, and resource version, which together allow the object to be uniquely identified and its history of changes to be tracked.
Namespaced vs. Cluster-Scoped Objects
Scope as Part of Definition
An object's definition includes whether it is namespaced, existing within a specific namespace and requiring that scope to be addressed, or cluster-scoped, existing independently of any namespace and visible cluster-wide.
Consequences of Scope
This distinction is not incidental: it determines how uniqueness of names is enforced, how access control policies apply, and how the object interacts with namespace-level governance such as ResourceQuotas.
Objects vs. Ephemeral API Constructs
Not Every API Interaction Creates an Object
Some API interactions, such as certain subresource actions or non-persistent queries, do not themselves create standing objects; the definition of an object specifically excludes transient constructs that exist only for the duration of a single request-response cycle.
Owner References and Object Relationships
Objects can reference one another through owner references, establishing dependent relationships where the deletion of an owning object triggers cleanup of the objects it owns, a relationship that only makes sense because both sides of it are persistent, addressable objects.