Pods: Imperative vs Declarative & YAML

The pod is the unit you actually deploy, but there are two very different ways to create resources: quick imperative commands versus versionable declarative YAML. Choosing wrong leads to unrepeatable, undocumented infrastructure.

Solution: Define workloads declaratively in YAML and apply them, so the cluster reconciles to your desired state (prefer declarative over imperative one-offs).

You can run a dock two ways. You can stand on the pier barking each step at a dockworker, fast for a one-off, but nobody records what you asked or repeats it tomorrow. Or you can file a standing work order describing the end state you want, and the port keeps fulfilling it on its own, restoring it whenever reality drifts. Kubernetes mirrors this: imperative kubectl commands are the shouted steps, while a declarative YAML manifest is the standing order that Kubernetes continuously reconciles toward.

The same cluster entities appear in every day's notes; the diagram below shows where this day's topic fits.

Graph legend — each node maps to the nginx pod this day creates:

The smallest deployable unit in Kubernetes. A pod wraps one (or more) containers that share network (same IP) and storage.

Graph legend — each node maps to containers sharing one pod's network/storage:

• You usually run ONE main container per pod.
• Pods are ephemeral: they get replaced, not repaired.

Kubernetes accepts both styles: you can fire off imperative commands or hand it a declarative file describing the end state.

   IMPERATIVE  = tell K8s the exact COMMANDS to run (how)
   DECLARATIVE = give K8s a YAML of the desired STATE (what)

Quick one-off commands that create and inspect a pod without writing any YAML.

kubectl run nginx --image=nginx              # create a pod fast
kubectl get pods
kubectl get pods -o wide                      # node + pod IP
kubectl describe pod nginx                     # events & details
kubectl delete pod nginx

Here the desired state lives in a file you version-control and apply — the preferred way for real infrastructure.

pod.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    app: web
spec:
  containers:
    - name: nginx
      image: nginx:1.27
      ports:
        - containerPort: 80

kubectl apply -f pod.yaml      # create or update to match file
kubectl get pod nginx -o yaml  # full live spec
kubectl delete -f pod.yaml

Every Kubernetes manifest needs these four keys at the top.

   apiVersion:  which API group/version  (e.g. v1, apps/v1)
   kind:        object type              (Pod, Deployment...)
   metadata:    name, labels, namespace
   spec:        desired state of the object

Let kubectl write the boilerplate for you, then tweak the file instead of typing YAML from scratch.

# --dry-run=client builds the YAML WITHOUT creating anything
kubectl run nginx --image=nginx \
  --dry-run=client -o yaml > pod.yaml

When a pod misbehaves, these three commands surface events, logs, and a shell inside the container.

kubectl describe pod nginx       # see Events at the bottom
kubectl logs nginx               # container stdout/stderr
kubectl exec -it nginx -- bash   # shell inside

A handy workflow: generate a manifest from an imperative command, then manage it declaratively from then on.

Graph legend — each node maps to the generate-then-apply workflow for the nginx pod:

Imperative and declarative paths both converge on the same reconcile flow that ends in a running pod.

Graph legend — each node maps to the path both styles take to a running nginx pod:

• Pod = smallest unit; containers in it share IP + storage.
• Use imperative for speed, declarative for real infra.
• --dry-run=client -o yaml generates manifests fast (use it in the exam).

• [ ] Created a pod imperatively and declaratively
• [ ] Generated YAML with --dry-run=client -o yaml
• [ ] Used describe, logs, exec to inspect a pod