Kubernetes Architecture and Pods Explained for Beginners

Try this on any practice cluster. Create a single Pod, then delete it. It vanishes and stays gone, which feels odd for a system whose reputation is keeping things running. Now do the same to a Pod owned by a Deployment and a replacement appears within seconds. The difference between those two outcomes is the entire architecture of Kubernetes in miniature, and understanding it will save you hours of confusion.

The cluster: a brain and a fleet of workers

A Kubernetes cluster has two halves. The control plane makes decisions. The worker nodes (machines, virtual or physical) run your containers. You never tell Kubernetes "start this container on that machine". You tell it what you want to be true, and the control plane works out how.

Managed offerings such as EKS, GKE and AKS run the control plane for you. You still see and reason about the same objects. Locally, tools like kind and minikube squeeze everything into one machine so you can practise.

Declarative state and the reconciliation loop

You submit a manifest describing desired state: "one Pod named tide-board running this image". The API server validates it and stores it in etcd. Controllers and the scheduler watch the API for changes. The scheduler notices an unassigned Pod and binds it to a node. That node's kubelet notices a Pod assigned to it and asks the runtime to start the containers. Throughout, controllers keep comparing what exists against what you asked for. This compare-and-correct cycle is called reconciliation, and it is why Kubernetes can heal itself: if reality drifts, a loop notices and fixes it.

kubectl apply -f pod.yaml
    |
    v
 kube-apiserver --> validate --> store in etcd
    |
    +--> kube-scheduler: "Pod has no node" -> picks node-2
    |
    +--> kubelet on node-2: "new Pod for me"
            |
            +--> runtime pulls image, starts containers
            +--> kubelet reports status back to apiserver

The Pod: the smallest thing you can run

Kubernetes does not schedule bare containers. It schedules Pods, a wrapper around one or more containers that always land on the same node and share a network identity (one IP address, one set of ports) and optionally storage volumes. Most Pods hold a single container. A second container is justified only when the two are tightly coupled, such as a log shipper or a helper that refreshes a file the main container serves. Here is a minimal manifest for a harbour tide-board service.

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

kubectl apply -f pod.yaml
kubectl get pods
kubectl describe pod tide-board
kubectl logs tide-board
kubectl delete pod tide-board

pod/tide-board created

NAME         READY   STATUS    RESTARTS   AGE
tide-board   1/1     Running   0          20s

The READY 1/1 column means one of one containers passed its readiness check. describe is the command you will use most when debugging, since its Events section tells the story of what the scheduler and kubelet did. The AGE value and any generated names differ on your cluster.

Two containers, one Pod: sharing a volume

Containers in the same Pod share a network namespace, so they reach each other on localhost, and they can mount the same volume. The next manifest runs a small writer that refreshes a timestamp file every 30 seconds, and an nginx container that serves that directory read-only. The emptyDir volume lives as long as the Pod does.

apiVersion: v1
kind: Pod
metadata:
  name: tide-board-pair
spec:
  volumes:
    - name: board
      emptyDir: {}
  containers:
    - name: writer
      image: busybox:1.36
      command: ["sh", "-c", "while true; do date +%H:%M > /data/updated.txt; sleep 30; done"]
      volumeMounts:
        - name: board
          mountPath: /data
    - name: web
      image: nginx:1.27-alpine
      ports:
        - containerPort: 80
      volumeMounts:
        - name: board
          mountPath: /usr/share/nginx/html
          readOnly: true

kubectl apply -f tide-board-pair.yaml
kubectl port-forward pod/tide-board-pair 8080:80 &
curl http://localhost:8080/updated.txt
kubectl logs tide-board-pair -c web

14:05

The time printed is simply the current time on your node. Note -c web: when a Pod has several containers you must say which one's logs you want. port-forward tunnels a local port to the Pod and is a debugging tool, not a way to expose an app.

Common mistakes and the symptoms they cause

• Treating Pods as permanent. Symptom: you hand-edit a running Pod, it is rescheduled, and your change is gone; Pod IP addresses you hard-coded stop working. Fix: change the manifest, and talk to Services, never to Pod IPs.
• Wrong `apiVersion` or `kind`. Symptom: error: unable to recognize "pod.yaml": no matches for kind followed by a kind and version. Fix: check kubectl api-resources and kubectl explain pod.
• YAML indentation errors. Symptom: error converting YAML to JSON with a line number, or unknown field warnings for misplaced keys. Fix: use spaces, align list items, and run kubectl apply --dry-run=client -f file.yaml.
• Looking in the wrong namespace. Symptom: No resources found in default namespace although you just deployed. Fix: add -n <namespace> or -A.
• Forgetting `-c` on multi-container Pods. Symptom: logs show a message about choosing a container, or you read the wrong container's output.

How this shows up in real projects and interviews

Interviewers love "what happens when you run kubectl apply?" because it exposes whether you know the API server, etcd, scheduler and kubelet roles. Expect follow-ups such as "why would you put two containers in one Pod?" (tight coupling, shared lifecycle, shared network) and "what happens if a node dies?" On a team you will rarely write bare Pods, but you will read Pod specs constantly, because every higher-level object contains one inside its template.