apiVersion, kind, metadata, spec, status: the shape of every object.

You write the first four. Kubernetes writes status to report what actually exists. The gap between spec and status is what controllers work on.

deployment.yaml

apiVersion: apps/v1            # API group and version
kind: Deployment                # what type of object
metadata:
  name: checkout
  namespace: shop
  labels: {app: checkout}
spec:                           # DESIRED state: you write this
  replicas: 3
  selector: {matchLabels: {app: checkout}}
  template:   # the Pod to create
    metadata: {labels: {app: checkout}}
    spec:
      containers:
      - {name: app, image: shopwave/checkout:1.4}
# status (written by the system): readyReplicas: 2

apiVersion + kind

Pick the exact API, such as apps/v1 + Deployment.

metadata

Identity: name, namespace, labels, annotations.

spec

The desired state. Most changes you make are edits to spec.

status

Observed state, written by controllers. Never apply it.

Every manifest has the same five-part shape

Every Kubernetes object, built in or custom, has the same skeleton. apiVersion and kind together tell the API server which schema to validate against, for example apps/v1 and Deployment. metadata gives the object an identity: a name that is unique within its namespace and kind, the namespace itself, labels that other objects use to find it, and annotations that carry non-identifying data for tools.

The two halves that matter most are spec and status. Spec is the desired state: you write it. Status is the observed state: controllers write it. A Deployment's spec says three replicas; its status says how many are ready right now. The reconciliation loop from the previous module is exactly the process of making status match spec.

This is why kubectl apply is safe to repeat. You submit the same desired state; if the system already matches, nothing changes. It is also why you should never edit status by hand and never include it in applied manifests.

Reveal the four explanations in order with the right arrow. Gotcha: indentation is meaning in YAML. A field at the wrong depth is either rejected by validation or silently ignored, so use kubectl apply --dry-run=server and a linter in CI.