The Anatomy of Kubernetes YAML

Kubernetes manifests aren't just configuration files—they're strict contracts with the API server. Every object, from a Pod to a Node to a NetworkPolicy, follows the same fundamental structure.

The Four Required Fields

Every Kubernetes object manifest requires these four top-level keys:

Field	Description	Mental Model
apiVersion	Specifies the API group and version (e.g., apps/v1, v1)	The API directory
kind	Defines the object type (e.g., Pod, Deployment)	The class or blueprint
metadata	Object identity: name, namespace, labels, annotations	The ID card
spec	The desired state—the actual configuration you want	Your order to the cluster

Example

apiVersion: apps/v1          # API group + version
kind: Deployment             # Object type
metadata:                    # Identity
  name: nginx
  namespace: production
spec:                        # Desired state
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25

Understanding GVK

When Kubernetes professionals refer to GVK, they mean the object's type identifier:

• Group: API group (apps, batch, networking.k8s.io; core APIs use empty group)
• Version: API version (v1, v1beta1, v2)
• Kind: Object type (Deployment, Pod, Service)

This GVK triplet uniquely identifies what type of object you're creating.

How GVK Maps to YAML

apiVersion: apps/v1    # Group = "apps", Version = "v1"
kind: Deployment       # Kind = "Deployment"

For core resources (Pod, Service, ConfigMap), the group is implicit:

apiVersion: v1         # Group = "" (core), Version = "v1"
kind: Pod              # Kind = "Pod"

The Fifth Field: Status

There's a fifth field you'll see but never write yourself:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  # ... your desired state
status:                      # Cluster-managed, read-only
  availableReplicas: 3
  conditions:
  - type: Available
    status: "True"
  # ... observed state

The Reconciliation Loop:

• spec = what you want (desired state)
• status = what you have (observed state)

Kubernetes runs a continuous reconciliation loop to make status match spec. This is the heart of Kubernetes' declarative model. Controllers constantly watch objects and take action to align reality with your specification.

Quick Reference

Minimum Valid Manifest

apiVersion: v1
kind: Pod
metadata:
  name: minimal-pod
spec:
  containers:
  - name: app
    image: nginx

Common API Versions

Resource	apiVersion	Group
Pod, Service, ConfigMap	v1	core (empty)
Deployment, ReplicaSet, StatefulSet	apps/v1	apps
Job, CronJob	batch/v1	batch
Ingress	networking.k8s.io/v1	networking.k8s.io
NetworkPolicy	networking.k8s.io/v1	networking.k8s.io

Key Takeaway

apiVersion + kind + metadata + spec are your four pillars. Master these, and you understand the foundation of every Kubernetes manifest you'll ever write. The cluster handles status automatically—you just declare what you want, and Kubernetes makes it happen.