Understanding Kubernetes Architecture

Kubernetes makes far more sense once you accept its central premise: you never tell it to do anything. You write down the desired state, and a collection of controllers spends forever reducing the gap between that and reality.

kube-apiserver is the only component that talks to storage. Everything else, including kubectl, reads and writes through its REST API. Authentication, authorisation, and admission all happen here.

etcd holds the entire cluster state in a consistent key-value store. Run an odd number of members, back it up, and treat its disk latency as sacred, because a slow etcd manifests as a mysteriously unresponsive cluster.

kube-scheduler decides which node a new Pod lands on, filtering by resource requests, taints, affinity, and topology constraints, then scoring what survives.

kube-controller-manager runs the reconciliation loops. The Deployment controller notices it has two replicas instead of three and creates one. Nothing pushed that instruction; a loop observed a difference.

kubelet watches the API server for Pods assigned to its node and instructs the container runtime to make them exist. It also reports health back, which is how failures become visible.

kube-proxy or a CNI-based dataplane implements Service routing, turning a stable virtual IP into a distribution across healthy Pod endpoints.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
  selector:
    matchLabels: { app: api }
  template:
    metadata:
      labels: { app: api }
    spec:
      containers:
        - name: api
          image: registry.example.com/api@sha256:9f2c...
          resources:
            requests: { cpu: 100m, memory: 256Mi }
            limits:   { memory: 512Mi }
          readinessProbe:
            httpGet: { path: /ready, port: 8080 }
            periodSeconds: 5
          livenessProbe:
            httpGet: { path: /healthz, port: 8080 }
            initialDelaySeconds: 20

Requests drive scheduling; limits enforce a ceiling. Setting a CPU limit too tight causes throttling that looks exactly like application slowness, which is why many teams set memory limits but leave CPU unlimited.

• No resource requests. The scheduler assumes near zero, overpacks the node, and the kernel starts killing processes.
• Confusing the probes. Readiness removes a Pod from Service endpoints; liveness restarts the container. Pointing liveness at a dependency check creates restart cascades during a downstream incident.
• No PodDisruptionBudget. A routine node drain takes all your replicas down at once.
• Mutable image tags. Deploying :latest means two Pods of the same Deployment can run different code.
• Treating it as a black box. When something breaks, kubectl describe and the events list explain almost everything. Read them before searching.

Declare intent, let controllers converge, and expect eventual rather than instant consistency. Once that clicks, the debugging question is always the same: which controller is unable to reconcile, and what is it complaining about in its events?