Architecture, workloads, and the commands you'll actually type

01 Cluster architecture

A cluster is a set of machines running containerized workloads, coordinated through a declarative API.

You describe the state you want; a set of controllers continuously works to make the actual state match it. Nodes split into two roles: control plane nodes make global decisions about the cluster and store all its state, while worker nodes run the actual application workloads, inside Pods.

                     ┌───────────────────────────────┐
                     │          Control Plane           │
                     │  kube-apiserver     etcd         │
                     │  kube-scheduler     controller-   │
                     │                     manager       │
                     └────────────────┬──────────────────┘
                                       │ HTTPS (API)
              ┌────────────────────────┼────────────────────────┐
              │                        │                        │
      ┌───────┴────────┐      ┌────────┴───────┐      ┌────────┴───────┐
      │  Worker Node 1  │      │  Worker Node 2  │      │  Worker Node N  │
      │  kubelet         │      │  kubelet         │      │  kubelet         │
      │  kube-proxy      │      │  kube-proxy      │      │  kube-proxy      │
      │  container       │      │  container       │      │  container       │
      │  runtime         │      │  runtime         │      │  runtime         │
      │  [Pod] [Pod]     │      │  [Pod] [Pod]     │      │  [Pod]           │
      └──────────────────┘      └──────────────────┘      └──────────────────┘

Every component talks to the API server; nothing talks to etcd directly except the API server itself. That makes it the single front door for reading or changing cluster state.

02 Control plane components

• kube-apiserver — the front door. Exposes the Kubernetes REST API, handles authentication/authorization and admission control, validates and persists objects. Everything else is a client of it.
• etcd — a distributed, consistent key-value store. The single source of truth for all cluster state.
• kube-scheduler — watches for Pods with no node assigned yet and picks one, based on resource requests, affinity/anti-affinity rules, taints/tolerations, and topology constraints.
• kube-controller-manager — runs the reconciliation loops (node controller, replication controller, endpoints controller, and more) that continuously watch actual state and drive it toward desired state.
• cloud-controller-manager — cloud-provider-specific logic (provisioning load balancers, labeling nodes with cloud metadata). Only present on managed clusters (EKS, GKE, AKS).

03 Worker node components

• kubelet — the agent on every node. Watches the API server for Pods assigned to its node and ensures the containers described in each Pod's spec are actually running and healthy.
• kube-proxy — maintains the network rules (iptables or IPVS) on each node that implement the Service abstraction, routing traffic sent to a Service's virtual IP to one of its backing Pods.
• Container runtime — the software that actually pulls images and runs containers (containerd, CRI-O), talked to by the kubelet through the Container Runtime Interface (CRI).

04 Cluster & kubeconfig

A cluster is one or more control plane nodes plus one or more worker nodes, operating as a single unit behind one API server (or a load-balanced set of API server replicas in production). Inside a cluster, namespaces let you logically partition resources (e.g. dev, staging, prod) without running separate clusters.

kubectl doesn't know which cluster to talk to on its own — it reads a kubeconfig file (default ~/.kube/config) holding one or more clusters, users (credentials), and contexts (a cluster + user + default namespace, bundled together and given a name you can switch to).

05 Image

A container image is an immutable, layered filesystem plus metadata (entrypoint/cmd, environment defaults, exposed ports), built once (typically from a Dockerfile) and pushed to a registry (Docker Hub, ECR, GCR, GHCR). Kubernetes pulls images by reference: registry/name:tag, optionally pinned to an exact @sha256:digest for full immutability.

06 Container

A container is a running instance of an image, isolated from the host and other containers via Linux namespaces (PID, network, mount, ...) and resource-limited via cgroups. In Kubernetes, containers never run standalone — they always run inside a Pod. A Pod can define:

• init containers — run to completion, in order, before any app container starts (common for setup/migrations).
• app containers — the long-running main process(es) of the Pod.
• sidecar containers — auxiliary containers that run alongside the app container for its whole lifetime (log shippers, proxies).

07 Pod

The Pod is the smallest deployable unit in Kubernetes: one or more containers always scheduled together on the same node, sharing a network namespace (same IP address, containers reach each other over localhost) and optionally storage volumes. Pods are ephemeral and not self-healing on their own — if a bare Pod's node fails or the Pod is deleted, nothing recreates it. That's why Pods are almost always created indirectly, through a controller like a Deployment or StatefulSet, rather than by hand.

apiVersion: v1
kind: Pod
metadata:
  name: nginx-pod
  labels:
    app: nginx
spec:
  containers:
    - name: nginx
      image: nginx:1.27
      ports:
        - containerPort: 80

08 ReplicaSet

A ReplicaSet ensures a specified number of identical Pod replicas are running at all times, using a label selector to identify which Pods it's responsible for. If a Pod it manages dies, it creates a replacement; if there are too many matching Pods, it deletes the excess. In practice you rarely create a ReplicaSet directly — a Deployment creates and manages one for you.

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: nginx-rs
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.27

09 Deployment

A Deployment is the standard way to run stateless applications. You describe the desired Pod template and replica count declaratively; the Deployment controller creates and owns a ReplicaSet, which in turn owns the Pods. Change the Pod template (e.g. a new image tag) and the Deployment performs a controlled rolling update — spinning up new Pods and retiring old ones gradually, governed by maxSurge/maxUnavailable — and you can roll it back with a single command if it goes wrong.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80

10 StatefulSet

A StatefulSet is for workloads that need stable, unique identity and stable storage per replica — databases, Kafka, ZooKeeper, anything where "replica 0" and "replica 1" aren't interchangeable. It differs from a Deployment in three ways:

• Pods get stable, predictable names — <name>-0, <name>-1, ... — instead of a random hash suffix.
• Pods are created and scaled in order by default (0, 1, 2, ... up; reverse order down), rather than all at once.
• Each replica gets its own PersistentVolumeClaim via volumeClaimTemplates, which survives Pod rescheduling — Pod -0 always reattaches to the same volume it had before.

A StatefulSet also needs a headless Service (clusterIP: None) so each Pod gets a stable DNS name: <pod-name>.<service-name>.<namespace>.svc.cluster.local.

apiVersion: v1
kind: Service
metadata:
  name: postgres-headless
spec:
  clusterIP: None
  selector:
    app: postgres
  ports:
    - port: 5432
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
spec:
  serviceName: postgres-headless
  replicas: 3
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:16
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

11 Liveness & readiness probes

All three support the same check mechanisms — httpGet, tcpSocket, or exec — and the same tuning fields: initialDelaySeconds, periodSeconds, timeoutSeconds, successThreshold, failureThreshold.

containers:
  - name: web
    image: myapp:1.4
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080
      initialDelaySeconds: 10
      periodSeconds: 10
      failureThreshold: 3
    readinessProbe:
      httpGet:
        path: /ready
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 5
      failureThreshold: 2

12 kubectl cheat sheet

cluster & context

namespaces

pods

deployments

replicasets & statefulsets

services

manifests & labels

debugging & config objects