API Flows and Sequence Diagrams — Overview

Purpose

This section documents the internal request flows and component interactions within a Kubernetes cluster as ASCII sequence diagrams. Each file traces a specific operation end-to-end — from the API client call through every component that participates, to the final observed state.

These diagrams complement the component reference sections (01–02) by showing temporal behaviour: what calls what, in what order, and what state is persisted at each step.

Index

#	File	Flow	Key components
01	pod-creation-flow.md	`kubectl apply` → running pod	API server, etcd, scheduler, kubelet, CRI
02	service-account-token.md	Pod token request → mounted JWT	API server, TokenRequest, projected volume
03	admission-flow.md	API request → admission chain	Authn, Authz, MutatingWebhook, ValidatingWebhook
04	scheduler-flow.md	Unscheduled pod → node binding	Scheduler filter/score/bind cycle
05	rolling-update-flow.md	Image bump → all pods updated	Deployment controller, ReplicaSet, kubelet
06	hpa-flow.md	Metric spike → scale out	HPA controller, metrics-server, Deployment
07	csi-flow.md	PVC create → pod mounts volume	CSI controller, node plugin, VolumeAttachment
08	network-policy-flow.md	NetworkPolicy create → eBPF rules	API server, CNI plugin, node datapath
09	rbac-flow.md	kubectl → RBAC decision	Authn, Authz RBAC, audit log
10	garbage-collection.md	Owner deleted → cascade delete	GC controller, ownerReferences, finalizers
11	leader-election.md	Controller startup → active leader	Lease API, controller-manager leader election
12	webhook-flow.md	Admission webhook invocation	API server → webhook server → response
13	cni-setup-flow.md	Pod sandbox → network namespace wired	kubelet, CNI plugin, IPAM
14	volume-attach-flow.md	PVC bound → volume mounted in pod	attach-detach controller, kubelet, CSI node

How to Read These Diagrams

Participant notation:
  Client        — kubectl, API client, controller
  API Server    — kube-apiserver (all requests go through here)
  etcd          — persistent store (only API server talks to etcd)
  Controller    — specific controller (scheduler, HPA, GC, etc.)
  kubelet       — node agent (watches API server, drives containers)
  CRI           — Container Runtime Interface (containerd, CRI-O)

Arrow notation:
  ──►   synchronous call (caller waits for response)
  --►   asynchronous / watch event (fire and forget)
  ══►   persisted state change (write to etcd)
  ···►  background polling / reconcile loop

Component Interaction Principles

Five rules govern every flow in Kubernetes:

1. Everything goes through the API Server

No component calls another directly. The scheduler does not call kubelet. kubelet does not call etcd. All state is read from and written to the API server. This hub-and-spoke model means the API server is the source of truth.

2. Controllers watch, not poll

Controllers use the watch API (long-lived HTTP/2 streaming connection). When an object changes, the API server pushes the event to all watchers. The local informer cache makes reads free; only writes go to the API server.

3. etcd is only touched by the API server

Controllers, kubelets, and all clients communicate with the API server via REST or gRPC. The API server translates these to etcd operations. Nothing else writes to etcd directly.

4. State drives action (level-triggered, not edge-triggered)

Controllers reconcile desired state vs actual state, not events. If a controller restarts mid-operation, it re-reads the current state from the API server and continues from there. This makes all controllers idempotent.

5. Finalizers prevent premature deletion

When an object has finalizers, kubectl delete only sets deletionTimestamp. The object is not removed from etcd until all controllers have removed their finalizer entries. This ensures cleanup logic runs before garbage collection.

Watch and Informer Architecture

API Server
    │
    │  GET /api/v1/pods?watch=true&resourceVersion=12345
    │  (HTTP/2 streaming — stays open)
    │
    ▼
Controller / kubelet
    └─► Informer (client-go)
          ├─ ListWatch:    initial List + streaming Watch
          ├─ Local cache:  in-memory store of all objects
          ├─ Event queue:  Added / Modified / Deleted events
          └─ Handler:      reconcile function called per event

Benefits:
  - Reads from local cache (zero API server load)
  - Watch reconnects automatically on disconnect
  - ResourceVersion prevents replaying old events

01 — Control Plane — component reference
02 — Node Components — kubelet and CRI
03 — Networking — CNI and network primitives
04 — Storage — PV/PVC/CSI