Pods: Imperative vs Declarative & YAML

This course is built around the public HelixWorks Kubernetes Lab monorepo. The excerpt below is runnable source, not pseudocode.

Source: app/Dockerfile

FROM nginx:1.29-alpine

COPY index.html /usr/share/nginx/html/index.html

EXPOSE 80

Code to reality

Declared intent

Package the first web workload with one repeatable runtime and HTTP port.

Interpreter

The Docker builder executes each instruction and records an immutable image layer.

Software effect

The image contains the HelixWorks page at the nginx document root and declares port 80.

Hardware effect

A running container consumes host CPU, memory, storage layers, and a network namespace.

Observable evidence

docker image inspect and an HTTP request to the running container identify the image and response.

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:

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