How to use this guide

• Part 0 — The lab: a scripted Ubuntu VM on your Mac (Lima) that holds the whole project, plus a milestone runbook and a method for verifying this guide as you build.
• Part I — Containers & Docker (beginner → advanced): what a container really is (namespaces, cgroups, layered filesystems), the Docker toolchain, writing production Dockerfiles, networking, storage, Compose, security and supply chain, debugging. Ends with the whole system running under docker compose with local observability.
• Part II — Kubernetes core (beginner → intermediate): the control loop, a multi-node local cluster, Pods, Deployments, Services, config, storage, StatefulSets, Jobs. Ends with the system deployed from raw manifests.
• Part III — Production workloads (intermediate → advanced): resources and QoS, health checks, graceful shutdown, self-healing, scheduling, Gateway API + TLS, Kustomize and Helm, autoscaling (HPA, KEDA, VPA, Karpenter).
• Part IV — Observability: OpenTelemetry instrumentation, the Collector, Prometheus, Loki, Tempo, Grafana, SLOs and burn-rate alerting.
• Part V — Debugging: a symptom-driven playbook for every common failure, ephemeral debug containers, node-level debugging, profiling.
• Part VI — Security: RBAC, Pod Security, NetworkPolicy, secrets management, admission policy and image signature verification.
• Part VII — Delivery: CI with GitHub Actions, GitOps with Argo CD, canary releases with Argo Rollouts, database migrations.
• Part VIII — Reliability operations: backup and disaster recovery, chaos engineering, cost and capacity, moving to a managed cloud (EKS).
• Part IX — Capstone & reference: assemble and verify the full system, the production-readiness checklist, cheat sheets, pitfalls, and further reading.

Conventions:

• Commands run in a Linux shell: inside the lab VM (§0, Path A) or natively on macOS (Path B). Commands marked [mac] run on the Mac host. Native macOS differences are called out where they matter. $ is omitted from commands so you can copy them directly.
• Kubernetes examples target Kubernetes 1.33+ (native sidecars, preStop sleep action, Gateway API). Version-specific behavior is called out where it matters.
• Application code is Go (the language of Kubernetes itself and the most common choice for cloud services); a few snippets show Python for comparison.
• ⚠️ Caveat (verify) boxes mark content written from knowledge of the docs but not yet executed or checked against the latest release: chart value keys, CRD fields that move between versions, version-specific feature status, and metric names. Each box says how to check it. Treat everything without a box as believed correct but still untested until you run it in the lab (§0). The "how to verify this guide" checklist is in §0.6.
• Real-world example boxes ground a concept in something you will meet on the job. War story boxes describe a failure mode that has taken down real production systems. Best practice boxes are the rule you should default to unless you have a reason not to.
• This guide is the theory + build companion to k8s-docker-plan.md (the 90-day schedule). The plan tells you when; this guide tells you how and why.