5.6 Kubernetes Object Structure

Kubernetes Object Structure is the standardized top-level field layout that every persistent API object follows, consisting of type identification, metadata, a desired-state specification, and an observed-state status, providing a consistent shape that generic tooling, controllers, and human operators can all rely on regardless of which specific kind of object they are working with.

The Four Top-Level Sections

apiVersion and kind

Every object begins with apiVersion and kind fields, together identifying the object's GroupVersionKind and instructing the API server how to interpret, validate, and route the remainder of the manifest, functioning as the object's declared type at the very top of its structure.

metadata

The metadata field carries identifying and organizational information about the object itself, distinct from the object's actual configuration, including its name, namespace, labels, annotations, and a collection of system-managed bookkeeping fields.

spec

The spec field, present on nearly all objects representing something a user or controller intends to exist or happen, captures the desired state, written by whichever actor, human or controller, is expressing intent for that object.

status

The status field captures the observed, actual state of the object as determined by the controller responsible for reconciling it, and is conventionally treated as a distinct subresource with separate update permissions from spec.

Inside metadata

Identity Fields

name uniquely identifies an object within its namespace (or cluster-wide for cluster-scoped resources), while namespace scopes namespaced objects, and uid provides a globally unique identifier assigned by the API server at creation time that never changes even if the object is deleted and a new object with the same name is later created.

Labels

labels are key-value pairs intended for identifying and grouping objects for selection purposes, consumed by Services, controllers, and NetworkPolicies through label selectors, and are expected to hold values meaningful for organizing and querying sets of related objects.

Annotations

annotations are also key-value pairs but are intended for attaching arbitrary, non-identifying metadata, such as build information, tooling-specific configuration, or descriptive notes, and unlike labels, annotations are not used for selection and can hold larger or more free-form values.

System-Managed Fields

resourceVersion, generation, creationTimestamp, managedFields, and ownerReferences are populated and maintained by the API server and controllers rather than by the object's author, tracking concurrency state, change history, creation time, field ownership for server-side apply, and ownership relationships to other objects respectively.

The Desired-Versus-Observed Pattern

Why Spec and Status Are Separated

Splitting desired state from observed state is the structural foundation of the controller pattern: a user or higher-level controller writes intent into spec, and a dedicated controller continuously works to make reality match that intent, recording what it actually observed and achieved into status, without ever needing to overwrite the original expressed intent.

Status as a Subresource

For most built-in kinds, status is exposed as a distinct API subresource, meaning a client with permission to update spec does not automatically have permission to update status, and vice versa, which prevents a workload author from accidentally or maliciously fabricating a false observed state.

Objects Without a Spec or Status

Configuration-Only Objects

Some object types, such as ConfigMap and Secret, do not follow the spec-and-status pattern at all, since they represent static configuration data rather than something to be reconciled toward a goal, and instead expose their data directly as top-level fields like data and stringData.

Event Objects

Event objects similarly diverge from the standard pattern, representing a discrete occurrence rather than an entity with ongoing desired and observed state, and instead carry fields describing what happened, when, and which object it concerns.

Nested Structure Within Spec

Composability of Spec Fields

Within spec, structure varies significantly by kind, but common patterns recur across the ecosystem, such as embedding a full PodTemplateSpec within a Deployment's spec.template, allowing higher-level workload controllers to reuse the same Pod specification structure that a standalone Pod object would use directly.

Selector Fields

Many workload and networking resources include a selector field within spec, using label selector syntax to establish which other objects, typically Pods, the resource applies to or manages, forming the primary mechanism by which loosely coupled objects in the object structure relate to one another.