The Docker and Kubernetes Picture Book
Cluster · nodes (machines) web api db cache queue web api Same box, runs anywhere Docker packs it · Kubernetes runs lots of them
PLATE 0 — A container is a standard box. Kubernetes is the port that manages thousands.
A picture book for grown-ups · with commands

Docker and Kubernetes, Unboxed

Nine spreads. Each has a picture, the idea, and the commands and YAML you'd actually use, from your first container to a running cluster.

Say it like a pro

"We package the app as an immutable image, and Kubernetes keeps the desired number of replicas running, healthy, and reachable."

Use the tabs or the ← → keys to turn pages.

Virtual machines app Aguest OS app Bguest OS Hypervisor Host hardware Containers app A app B app C Container engine Host OS + kernel What makes a container namespaces: its own view of processes, network, files cgroups: limits on CPU and memory image layers: read-only, shared, cached starts in under a second · megabytes, not gigabytes "works on my machine" → works on every machine
PLATE 1 — Containers share the host's kernel, so they're light and fast.
Chapter 1 · Why containers

Ship the app and everything it needs

A container is an ordinary process with walls around it. An image is the recipe and files; a container is a running instance of an image, like a program versus a process.

Your first containers
$ docker version
$ docker run hello-world
$ docker run -d -p 8080:80 --name web nginx   # host 8080 → container 80
$ curl localhost:8080
$ docker ps ; docker ps -a
$ docker logs -f web
$ docker exec -it web sh                  # shell inside it
$ docker stop web ; docker rm web
image
read-only template, built in layers
registry
image storage: Docker Hub, GHCR, ECR
-d / -p / --rm
background / publish a port / delete on exit
Say it like a pro

"Containers are isolated processes sharing the host kernel, not tiny VMs."

FROM node:20-slim WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . USER node CMD ["node","server.js"] build CMD · metadata app source (changes often) node_modules (cached) node:20-slim (cached) Order matters for speed put rarely-changing steps first (deps), often-changing last (code) a changed layer invalidates every layer after it
PLATE 2 — Each instruction is a layer. Docker reuses layers it has already built.
Chapter 2 · Building images

The Dockerfile: a recipe for your app

Dockerfile
FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ENV NODE_ENV=production
EXPOSE 3000
USER node
HEALTHCHECK CMD node -e "fetch('http://localhost:3000/health').then(r=>process.exit(r.ok?0:1))"
CMD ["node", "server.js"]
.dockerignore
node_modules
.git
.env
*.log
$ docker build -t myapp:1.0 .
$ docker images ; docker history myapp:1.0
$ docker run --rm -p 3000:3000 --env-file .env myapp:1.0
$ docker tag myapp:1.0 ghcr.io/you/myapp:1.0 ; docker push ghcr.io/you/myapp:1.0
multi-stage
build in a big image, copy only the output into a small one
never
bake secrets into an image. Pass them at runtime.
Say it like a pro

"Small base image, non-root user, deps cached before code, and no secrets in layers."

db container volume: pgdata data survives container removal network: appnet api db api reaches "db:5432" by name Three ways to keep or share files volume managed by Docker · best for databases bind a host folder mounted in · best for dev code tmpfs memory only · temporary secrets containers are disposable: anything not in a volume is lost
PLATE 3 — Treat containers as disposable. Keep the state outside.
Chapter 3 · Data & networking

Volumes keep data, networks let containers talk

$ docker volume create pgdata
$ docker network create appnet
$ docker run -d --name db --network appnet \
    -e POSTGRES_PASSWORD=devpass -v pgdata:/var/lib/postgresql/data postgres:16
$ docker run -d --name api --network appnet -p 3000:3000 \
    -e DATABASE_URL=postgres://postgres:devpass@db:5432/postgres myapp:1.0
$ docker run -v "$PWD":/app -p 3000:3000 myapp:dev   # bind mount for live edits
$ docker volume ls ; docker network ls ; docker inspect api
DNS by name
on a user-defined network, db resolves to its container
-p 3000:3000
only publish ports that the outside world needs
cleanup
docker system prune removes stopped containers and dangling images
Say it like a pro

"State lives in volumes, services find each other by name, and only the edge is published."

services: web: build: ./web api: build: ./api db: image: postgres volumes: pgdata: $ docker compose up web api db pgdata Great for local dev and small deployments one file describes the whole stack · one command starts it for many machines and self-healing, graduate to Kubernetes
PLATE 4 — A stack as a file: write it once, start it anywhere.
Chapter 4 · Docker Compose

Run a whole app with one command

compose.yaml
services:
  web:
    build: ./web
    ports: ["8080:80"]
    depends_on: [api]
  api:
    build: ./api
    environment:
      DATABASE_URL: postgres://postgres:${DB_PASSWORD}@db:5432/app
    depends_on:
      db: { condition: service_healthy }
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: app
    volumes: [pgdata:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
volumes:
  pgdata:
$ docker compose up -d --build ; docker compose ps
$ docker compose logs -f api
$ docker compose down            # add -v to also delete volumes
Say it like a pro

"Compose for local dev and CI, with secrets in a .env file that never gets committed."

Control plane (the brain) API serverfront door etcdstate store schedulerpicks a node controllersmake it so Worker node 1 kubelet kube-proxy pod pod Worker node 2 kubelet kube-proxy pod you tell it the desired state · controllers close the gap
PLATE 5 — Declare what you want. Kubernetes works out how to get there and keeps it there.
Chapter 5 · Kubernetes architecture

A cluster that heals itself

Docker runs containers on one machine. Kubernetes (K8s) runs them across many: scheduling, restarting, scaling, and routing traffic. You describe the desired state in YAML, and it reconciles reality to match.

pod
smallest unit: one or more containers sharing an IP
node
a machine (VM or physical) that runs pods
API server
every command, including kubectl, goes through it
etcd
the cluster's source of truth
kubelet
node agent that starts and watches containers
A local cluster to learn on
$ kind create cluster          # or: minikube start
$ kubectl cluster-info
$ kubectl get nodes
$ kubectl get pods -A          # -A = all namespaces
$ kubectl config get-contexts  # which cluster am I pointing at?
Say it like a pro

"It's a control loop: observe actual state, compare with desired state, act."

Deployment · replicas: 3 ReplicaSet pod · v1 pod · v1 pod · v1 Rolling update to v2 v2 ✔ v2 ✔ v1 → v2… a pod dies? the ReplicaSet starts another. Bad release? rollout undo.
PLATE 6 — You never run pods by hand. A Deployment keeps the right number alive and updates them gradually.
Chapter 6 · Deployments

Run N copies, update without downtime

deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels: { app: myapp }
  template:
    metadata:
      labels: { app: myapp }
    spec:
      containers:
        - name: myapp
          image: ghcr.io/you/myapp:1.0
          ports: [{ containerPort: 3000 }]
          resources:
            requests: { cpu: 100m, memory: 128Mi }
            limits:   { memory: 256Mi }
          readinessProbe:
            httpGet: { path: /health, port: 3000 }
          livenessProbe:
            httpGet: { path: /health, port: 3000 }
$ kubectl apply -f deployment.yaml
$ kubectl get deploy,pods -l app=myapp
$ kubectl scale deploy myapp --replicas=5
$ kubectl set image deploy/myapp myapp=ghcr.io/you/myapp:1.1
$ kubectl rollout status deploy/myapp ; kubectl rollout undo deploy/myapp
Say it like a pro

"Three replicas, resource requests, readiness and liveness probes, and a rolling update with one-command rollback."

Users Ingresshost / path rules Service webstable IP+DNS Service apistable IP+DNS pods pods Why Services exist pods come and go and change IPs; a Service gives them one stable address ClusterIP inside the cluster only (default) NodePort a port on every node LoadBalancer cloud-provided public IP Ingress one entry point, many sites by host or path
PLATE 7 — Pods are temporary. Services and Ingress are the permanent doors.
Chapter 7 · Services & Ingress

Stable addresses for moving targets

service.yaml + ingress.yaml
apiVersion: v1
kind: Service
metadata: { name: myapp }
spec:
  selector: { app: myapp }          # matches pod labels
  ports: [{ port: 80, targetPort: 3000 }]
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata: { name: myapp }
spec:
  ingressClassName: nginx
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service: { name: myapp, port: { number: 80 } }
$ kubectl get svc,ingress
$ kubectl port-forward svc/myapp 8080:80   # test locally
$ kubectl run tmp --rm -it --image=busybox -- wget -qO- myapp
labels
key/value tags; Services find pods by matching them
DNS
myapp.default.svc.cluster.local, or just myapp in the same namespace
Say it like a pro

"Ingress routes by host and path to ClusterIP Services, which select pods by label."

ConfigMap Secret PVC Pod env: LOG_LEVEL=info env: DB_PASSWORD=•••• mount: /var/lib/data Same image everywhere, different config per environment Secrets are base64, not encrypted by default: restrict RBAC, enable encryption at rest, or use an external secrets manager StatefulSet for databases that need stable identity + storage
PLATE 8 — Keep config and state out of the image.
Chapter 8 · Config, secrets & storage

One image, many environments

$ kubectl create configmap app-config --from-literal=LOG_LEVEL=info
$ kubectl create secret generic db-secret --from-literal=password='s3cr3t'
$ kubectl get secret db-secret -o yaml      # base64 ≠ encryption
Use them in a pod spec
containers:
  - name: myapp
    image: ghcr.io/you/myapp:1.0
    envFrom:
      - configMapRef: { name: app-config }
    env:
      - name: DB_PASSWORD
        valueFrom:
          secretKeyRef: { name: db-secret, key: password }
    volumeMounts:
      - { name: data, mountPath: /var/lib/data }
volumes:
  - name: data
    persistentVolumeClaim: { claimName: app-data }
namespace
a virtual cluster section: dev, staging, prod
HPA
autoscaler: kubectl autoscale deploy myapp --min=3 --max=10 --cpu-percent=70
Helm
package manager that templates YAML for you
Say it like a pro

"Config in ConfigMaps, secrets from a vault, persistent data on PVCs, and an HPA for load."

Pendingcan't be scheduled → describe pod: not enough CPU/memory, or PVC unbound ImagePullBackOffwrong image name/tag, or missing registry credentials CrashLoopBackOffthe app exits → logs --previous shows why Running · 0/1 Readyreadiness probe failing → wrong path/port, or slow start OOMKilledout of memory → raise the limit or fix the leak
PLATE 9 — The status word tells you where to look first.
Chapter 9 · Debugging

Describe, then logs, then events

$ kubectl get pods -o wide
$ kubectl describe pod myapp-7d9f-abc12     # read the Events at the bottom
$ kubectl logs myapp-7d9f-abc12
$ kubectl logs myapp-7d9f-abc12 --previous  # the crashed container
$ kubectl logs -l app=myapp -f --tail=50
$ kubectl exec -it myapp-7d9f-abc12 -- sh
$ kubectl get events --sort-by=.lastTimestamp
$ kubectl top pods                          # needs metrics-server
$ kubectl get endpoints myapp               # empty? labels don't match
$ kubectl delete pod myapp-7d9f-abc12        # Deployment recreates it
  1. Which layer? Pod, Service, Ingress, or the node itself.
  2. Describe shows scheduling and event errors.
  3. Logs show the application's side of the story.
  4. Endpoints empty means the Service selector doesn't match any ready pod.
  5. Reproduce in Docker locally if the image itself is suspect.
next steps
Helm, GitOps (Argo CD / Flux), RBAC, network policies, then CKA/CKAD
Say it like a pro

"Describe the pod, check previous logs, verify the Service has endpoints, and compare against the same image under plain Docker."