# Kubernetes Fundamentals

> Kubernetes fundamentals taught from first principles (kubernetes-the-hard-way backbone). Use BEFORE reasoning from scratch about any Kubernetes internals: cluster bootstrap, the control plane (apiserver / controller-manager / scheduler), etcd, the PKI/TLS cert mesh and CN/O-to-RBAC mapping, kubeconfigs, kubelet / containerd / CRI, pod networking and CNI, kube-proxy, encryption at rest, the Node Authorizer, or CRDs and the Helioy v2 K8s-shaped endgame. Routes you into the verified curriculum at ~/.mdx/knowledge/kubernetes/. Trigger when: explaining or debugging Kubernetes internals, designing K8s-shaped infrastructure, reviewing cluster config, or onboarding to how the core components fit together.

- Skill: `srobinson/kubernetes-fundamentals` (Agent Skill)
- Install (CLI): `npx skillmds@latest add srobinson/kubernetes-fundamentals`
- Raw SKILL.md: https://api.skillmd.com/api/skills/srobinson/kubernetes-fundamentals/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: srobinson (https://skillmd.com/u/srobinson)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/srobinson/kubernetes-fundamentals

---


# Kubernetes Fundamentals

A verified knowledge curriculum lives at `~/.mdx/knowledge/kubernetes/`: an index plus 9 modules, original synthesis seeded from `kubernetes-the-hard-way` (v1.32 era), carrying 275 cited `file:line` references into the cloned repo at `~/Dev/LLM/DEV/helioy/REFS/kubernetes-the-hard-way`. The flagship `pki-and-identity.md` is two-model peer-reviewed.

When a task touches Kubernetes internals, read the relevant module BEFORE reasoning from memory. The modules are denser and more accurate than first-principles recall, and they cite the exact config/unit lines.

## Start here

Read `~/.mdx/knowledge/kubernetes/index.md` first: the 4-VM topology, the 13-step bootstrap arc, and the study order.

## Module map

| Module (`~/.mdx/knowledge/kubernetes/<slug>.md`) | Answers | Read when |
|---|---|---|
| `index` | topology, 13-step arc, study order | always first |
| `topology-and-bootstrap-model` | 4-VM layout, `machines.txt`, the forced dependency chain | cluster bring-up, ordering |
| `pki-and-identity` **(flagship)** | the CA, 8 certs, CN→user / O→group RBAC, SANs, apiserver↔kubelet reverse-trust | certs, identity, auth, 403s |
| `kubeconfig-and-authn` | cert-per-consumer, `--embed-certs`, server-URL choices | kubeconfig problems |
| `control-plane-internals` | apiserver / controller-manager / scheduler units, flags, which secrets each holds | control-plane behavior |
| `etcd-and-state` | single stateful member, plaintext-localhost shortcut vs prod TLS/quorum | datastore, state, backup |
| `worker-runtime-stack` | kubelet + containerd + runc + CRI, the cgroupDriver/SystemdCgroup contract | node/runtime failures |
| `networking-model` | pod /16-per-cluster /24-per-node, service CIDR, bridge CNI vs static routes, kube-proxy | networking, CNI, routing |
| `security-at-rest-and-rbac` | encryption provider ordering, apiserver-to-kubelet RBAC, SA token signing | secrets, RBAC, admission |
| `operations-and-failure-modes` | smoke-test matrix, systemd debug, gotchas catalogue (cross-links all siblings) | debugging, failure triage |

## How to use

- **Direct read** the module that matches the task. Each is self-contained.
- **Find a passage** with `md_search` / `md_keyword_search` (mdm) when you do not know which module: e.g. `md_search "cgroup driver containerd"` surfaces `worker-runtime-stack`.
- **Cite the module** in your answer (slug + the KTHW `file:line` it references), so the reasoning is traceable to ground truth.
- The `operations-and-failure-modes` gotchas catalogue is the fastest entry point when triaging a specific failure (403 on `logs/exec`, cgroup mismatch, missing SANs, pod cross-node unreachable).

## Provenance & boundaries

- Source: `kubernetes-the-hard-way`, dual-licensed (Apache-2.0 for `configs/`/`units/`/`ca.conf`, CC-BY-NC-SA-4.0 for prose). The modules are original synthesis, freely usable; quoted Apache snippets carry a notice.
- The curriculum is pinned to the **v1.32 era**. For a live cluster on a different version, treat the modules as the conceptual model and verify version-specific flags against the running cluster or upstream docs.
- A cm `reference` pointer (`global/project:helioy`) also routes here via `cx_recall`; the long-form synthesis essay is `~/.mdx/research/kelseyhightower-kubernetes-the-hard-way.md`.

## Rules

- **NEVER** reason about K8s internals from scratch when a module covers the topic. Read it first.
- **ALWAYS** read `index.md` before a multi-component question.
- **DO** extend this domain in place: new K8s knowledge (kubeadm, CKA, operators, CRDs) joins `~/.mdx/knowledge/kubernetes/` as new modules with their own `source`/`license` frontmatter, never a parallel home.