1.7 Kubernetes Metadata Definition
Kubernetes Metadata Definition describes data used to label and describe Kubernetes objects, enabling resource management and orchestration within clusters.
Kubernetes Metadata Definition is the precise characterization of the metadata field carried by every Kubernetes object, defined as the set of identifying and organizational information, including name, namespace, unique identifier, labels, and annotations, that is distinct from an object's spec and status because it describes what the object is rather than what it should do or what state it is in.
Metadata as a Distinct Category
Neither Desired Nor Observed State
Metadata is defined by exclusion as much as by inclusion: it is neither the desired state expressed in an object's spec, nor the observed state reported in its status, but rather the identifying and descriptive information that exists independently of both.
Present on Every Object Uniformly
Every Kubernetes object, regardless of its kind or API group, carries the same metadata structure, making it one of the few parts of the object model that is entirely uniform across the whole API surface.
Required Identity Fields
Name and Namespace
An object's name, combined with its namespace when applicable, forms the basis of its identity within the cluster, and this combination must be unique, since the API server relies on it to distinguish one object from another of the same kind.
uid and resourceVersion
Beyond name and namespace, the API server assigns a uid, a value guaranteed unique across the entire lifetime of the cluster, and a resourceVersion, which changes with every update, allowing clients to detect concurrent modifications rather than blindly overwriting each other's changes.
Labels as Defined Metadata
Identification, Not Description
Labels are metadata specifically defined for identification and selection; they are intentionally kept short and structured as key-value pairs precisely because they are meant to be matched against by selectors, not read as free-form descriptive text.
Mutability of Labels
Labels are mutable and can be added, changed, or removed after an object is created, which is central to their role, since dynamic selector matching depends on the ability for an object's label set to change independently of its spec.
Annotations as Defined Metadata
Descriptive, Non-Selecting Metadata
Annotations are metadata defined for attaching arbitrary, non-identifying information, such as build provenance or tooling-specific configuration, and are explicitly excluded from participating in label selector matching.
Larger and Less Structured Than Labels
Because annotations are not used for selection, they are permitted to hold larger and less structured values than labels, reflecting their different intended purpose within the metadata definition.