Architecture

# ===== Two halves =====
# Control plane: makes decisions (scheduling, reconciliation)
# Data plane:    runs the workloads (your pods)

# ===== Control plane components =====
# kube-apiserver
#   The single entry point. Every kubectl / controller / kubelet call hits it.
#   Validates + persists desired state to etcd.
#
# etcd
#   Distributed key-value store; the source of truth for cluster state.
#   Sized for control plane (small + fast); not for app data.
#
# kube-scheduler
#   Picks a node for each new pod (based on resources, taints, affinity).
#
# kube-controller-manager
#   Runs controllers (Deployment, ReplicaSet, Node, Endpoint, Job, ...).
#   Each controller reconciles desired state -> actual state.
#
# cloud-controller-manager (managed K8s)
#   Integrates with the cloud provider (load balancers, volumes, nodes).

# ===== Data plane (per node) =====
# kubelet
#   Talks to apiserver; ensures pods on this node match the spec.
#   Reports node + pod status back.
#
# kube-proxy
#   Maintains iptables / IPVS rules so Services route to pods.
#
# container runtime (containerd, CRI-O)
#   Actually starts containers via the Container Runtime Interface (CRI).
#
# CNI plugin (Calico, Cilium, Flannel, AWS VPC CNI)
#   Sets up pod networking (each pod gets an IP routable across the cluster).

# ===== Request flow: kubectl apply -f deploy.yaml =====
# 1. kubectl -> apiserver (auth + validate)
# 2. apiserver -> etcd (persist Deployment spec)
# 3. Deployment controller sees new Deployment -> creates ReplicaSet
# 4. ReplicaSet controller -> creates Pods
# 5. Scheduler picks nodes for Pods
# 6. kubelet on each node pulls images + starts containers via CRI
# 7. kube-proxy + CNI route traffic via Services

# ===== Add-ons (NOT core but typically present) =====
# CoreDNS                in-cluster DNS
# Metrics Server         CPU / memory metrics (for HPA)
# Ingress controller     nginx, Traefik, Contour, ALB ingress
# CSI drivers            persistent volumes (EBS, NFS, ...)
# Network policies       Calico / Cilium enforce traffic rules

# ===== Managed K8s differences =====
# EKS / GKE / AKS run the control plane FOR you.
# You manage worker nodes + workloads.
# Different add-ons + IAM integration per provider.

# ===== Multi-tier mental model =====
# Cluster = control plane + nodes
# Namespace = logical grouping
# Workload = Deployment / StatefulSet / DaemonSet / Job
# Pod = 1+ containers sharing network + storage
# Container = your process

# ===== Patterns to internalise =====
# - Everything is desired state in etcd; controllers reconcile
# - apiserver is the only door — every component talks to it
# - kubelet is the node-side agent; treat it as untouchable
# - Add-ons (CoreDNS, metrics, ingress) are not optional in real clusters

# ===== Pitfalls =====
# - Modifying etcd directly (almost always wrong)
# - Self-managing the control plane when managed K8s would do
# - Skipping CNI choice -> network policy + perf surprises
# - Treating kube-proxy as a load balancer (it's a routing rules manager)

# Control plane: api-server, etcd, scheduler, controller-manager.
# Nodes: kubelet + kube-proxy + container runtime.