Files

T

Jon Chery c3226192f5 docs(P02): complete kubernetes phase

---ci---
project: atelier
phase: 2
milestone: v0.2
status: complete
requirements:
  covered: [ATELIER-41, ATELIER-42, ATELIER-43, ATELIER-44, ATELIER-45, ATELIER-46, ATELIER-47]
  partial: []
---/ci---

2026-08-05 02:09:55 +00:00

2.8 KiB

Raw Blame History

Kubernetes — First Principles

1. The Principles

P1. Declarative Desired State

You declare the desired state; controllers reconcile current → desired. Imperative kubectl is for inspection and incident response, not for the steady state. The cluster's job is to make reality match the manifest.

P2. Pods are Mortal

A pod is born, runs, and dies. Never assume its identity, its IP, or its lifetime. Use controllers (Deployment, StatefulSet, DaemonSet), not bare pods. A bare pod has no recovery, no scaling, no rollback.

P3. Labels Select

Labels and selectors are the join mechanism of the platform — workloads to services, policies to workloads, workloads to nodes. Label by intent (app, tier, env), not by infrastructure (node-3, ip-10.0.0.5). Selectors compose; ad-hoc naming does not.

P4. Requests and Limits are Contracts

Resource requests drive scheduling; limits drive quality of service. A workload with no requests is BestEffort — first evicted under pressure. A workload with no limits is unbounded. Specifying requests is not optional in production.

P5. Probes Drive Health

Liveness, readiness, and startup probes are how the platform sees your workload. Without a readiness probe, traffic routes to a pod that is not ready. Without a liveness probe, a wedged container runs forever. The platform cannot heal what it cannot see.

P6. Namespaces Bound Blast Radius

Namespaces are the unit of quota, RBAC, network policy, and cleanup. A namespace is the boundary of "this thing and all its parts." Default namespace is for nothing in production; every workload gets a named namespace sized to its blast radius.

P7. RBAC by Intent, Not Identity

Bind roles to service accounts by the workload's purpose, not to user identities. Least privilege: the role grants the minimum the workload needs. cluster-admin is a smell, not a shortcut. Cross-link domains/security/authorization.md.

P8. Storage is Explicit

Storage is ephemeral by default. Persistence requires a PVC, a StorageClass, and a reclaim policy decision. emptyDir for state that must survive is a bug. The choice of reclaim policy (Retain, Delete) is a data-safety decision, not a default.

P9. Config and Secrets are Separate

ConfigMaps are non-sensitive configuration; Secrets are sensitive configuration. Both are injected at runtime, never baked into the image. A configuration change should not require a rebuild; a secret rotation should not require a redeploy of the image. Cross-link domains/security/secrets.md.

P10. Roll Forward, Roll Back

Every Deployment has a rolling update strategy and a rollout history. A deploy is reversible: kubectl rollout undo. A deploy without a tested rollback is a prototype. Canary and blue-green are the k8s expression of domains/devops/P5 Progressive Delivery.

2.8 KiB Raw Blame History