Kubernetes Object Definition

Kubernetes Object Definition is the precise characterization of a Kubernetes object as a persistent record within the cluster's API representing an intent or an observed state, uniquely identified, versioned, and structured according to a uniform schema shared by every kind of resource the cluster serves. Formally, an object is not the running process, container, or piece of infrastructure it describes; it is the durable API record that causes that process, container, or infrastructure to exist, be configured a certain way, or be observed in a certain condition.

Formal Structure

The Four Canonical Fields

Every object is defined by four top-level fields: apiVersion, identifying the API group and version the object's schema belongs to; kind, identifying the specific resource type; metadata, carrying identifying and administrative information common to all objects; and, for most kinds, spec, carrying the user-declared desired configuration specific to that kind.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: codartium-worker
  namespace: codartium-team
  uid: 3f8e9a2c-1b4d-4e7f-9c2a-8d6e5f4a3b21
  resourceVersion: "184023"
spec:
  replicas: 4

Spec and Status as Distinct Fields

Where present, spec and status are formally distinct: spec is written by the user or a higher-level controller to express intent, while status is written by the system to report the object's observed condition, and this separation holds regardless of which specific kind of object is being described.

Identity

Name and Namespace

Within a namespace, an object is uniquely identified by the pair of its kind and metadata.name; cluster-scoped objects are uniquely identified by kind and name alone, since no namespace applies. This name-based identity is chosen by the object's creator and must conform to defined naming constraints.

UID

Independently of name, every object receives a uid upon creation, a value generated by the system that remains globally unique for the lifetime of the cluster, even across the deletion and recreation of an object sharing the same name and namespace, allowing controllers to distinguish a genuinely persistent object from a same-named replacement.

Object Lifecycle

Creation

An object begins to exist the moment a valid creation request is accepted by the API server, validated against its schema, processed through admission control, and persisted to the state store, at which point it becomes visible to any client watching that resource type.

Modification

Modifying an object updates its persisted record and, formally, its resourceVersion, a value the API server increments on every change and uses to detect and reject writes based on stale reads, guaranteeing that concurrent modifications cannot silently overwrite one another.

Deletion

Deleting an object marks it for removal; if the object has a non-empty finalizers list, its actual removal from the state store is deferred until every finalizer has been cleared, a formally defined mechanism that allows controllers to perform necessary cleanup before an object's record is permanently erased.

kubectl get deployment codartium-worker -o yaml
kubectl delete deployment codartium-worker --cascade=foreground

Object Categories

Built-in vs. Custom Objects

An object's kind may be one defined natively within the Kubernetes source code, such as Pod or Service, or one registered dynamically through a Custom Resource Definition; both are objects in exactly the same formal sense, subject to the same structural conventions, the same identity rules, and the same lifecycle guarantees.

Namespaced vs. Cluster-Scoped Objects

An object's kind determines whether instances exist within the scope of a single namespace or independently of any namespace; this scoping is a property of the kind itself, fixed at the time that kind is defined, not something an individual object instance can override.

Object Ownership

ownerReferences

An object may declare one or more ownerReferences, formally linking it to another object responsible for its lifecycle; when an owner object is deleted, objects referencing it as owner are, by default, garbage collected in turn, a defined cascading behavior underlying how controllers manage the sets of dependent objects they create.

metadata:
  ownerReferences:
    - apiVersion: apps/v1
      kind: ReplicaSet
      name: codartium-worker-7d9f8c
      uid: 91a2b3c4-...
      controller: true

kubectl get all -n codartium-team --show-kind
kubectl get pods -o jsonpath='{.items[*].metadata.ownerReferences[*].name}'

Why the Object Definition Is Foundational

Because every entity the cluster manages, from a single container's placement instructions to a cluster-wide policy, is represented through this single, uniform object structure, generic tooling built to understand apiVersion, kind, metadata, spec, and status can operate correctly over any resource type the cluster serves, a property that follows directly from treating the object definition as a fixed, universal contract rather than something varying case by case.