Kubernetes

01What problems Kubernetes solves

With a few containers on one server, Docker Compose is enough. With dozens of services on twenty machines, new questions appear. Which machine has room for this container (scheduling)? Who restarts it when it crashes, or moves it when the machine dies (self-healing)? How do we add copies when traffic grows (scaling)? How do we release a new version without downtime and roll back if it fails (rolling updates)? How do services find each other when their addresses keep changing (service discovery)? Kubernetes answers all of these with one idea: you declare the desired state, for example three replicas of web version 1.4.2, and controllers continuously compare the actual state with it and act to close the gap. This reconciliation loop is the heart of Kubernetes.

• Control plane: API server, scheduler, controllers, etcd (the cluster's database).
• Worker nodes: kubelet runs pods; a container runtime runs containers.
• Everything is an API object you create, read and update with kubectl or GitOps tools.

02Pods and Deployments

A Pod is the smallest unit Kubernetes runs: one or more containers that share a network address and can share volumes. Pods are disposable; they get new names and IPs when replaced, so you almost never create them directly. A Deployment manages pods for you: it keeps the requested number of replicas running and performs rolling updates when you change the image. Two health checks matter. A readiness probe tells Kubernetes when a pod can receive traffic; a liveness probe tells it when a pod is stuck and must be restarted. Resource requests tell the scheduler how much CPU and memory to reserve; limits cap usage. Without requests, scheduling and autoscaling make poor decisions.

1apiVersion: apps/v1
2kind: Deployment
3metadata: { name: web }
4spec:
5  replicas: 3
6  selector: { matchLabels: { app: web } }
7  template:
8    metadata: { labels: { app: web } }
9    spec:
10      containers:
11        - name: web
12          image: registry.example.com/web:1.4.2
13          ports: [{ containerPort: 3000 }]
14          readinessProbe: { httpGet: { path: /healthz, port: 3000 } }
15          resources:
16            requests: { cpu: 250m, memory: 256Mi }
17            limits: { memory: 512Mi }

03Services, configuration and autoscaling

A Service gives a stable name and virtual IP to a changing set of pods, selected by labels, and load-balances across the ready ones. Other pods reach it by DNS, for example http://web. ClusterIP services are internal only; LoadBalancer services ask the cloud for an external load balancer. Configuration is kept out of images: a ConfigMap holds non-secret settings, a Secret holds passwords and keys. Note that Secrets are only base64-encoded by default, so enable encryption at rest and restrict who can read them, or sync them from an external secret manager. A HorizontalPodAutoscaler (HPA) adjusts the replica count based on CPU, memory or custom metrics, within the minimum and maximum you set.

1apiVersion: v1
2kind: Service
3metadata: { name: web }
4spec:
5  selector: { app: web }
6  ports: [{ port: 80, targetPort: 3000 }]
7---
8apiVersion: autoscaling/v2
9kind: HorizontalPodAutoscaler
10metadata: { name: web }
11spec:
12  scaleTargetRef: { apiVersion: apps/v1, kind: Deployment, name: web }
13  minReplicas: 3
14  maxReplicas: 10
15  metrics:
16    - type: Resource
17      resource: { name: cpu, target: { type: Utilization, averageUtilization: 70 } }

04How a request reaches a pod

Follow one request. The browser resolves app.example.com through DNS to the address of a cloud load balancer. The load balancer forwards to the cluster's edge proxy, which is either an Ingress controller or, increasingly, a Gateway API implementation. That proxy reads routing rules (host and path) and sends the request to the matching Service. The Service, implemented on each node by kube-proxy or an eBPF data plane such as Cilium, picks one ready pod from its endpoints and forwards the request to the pod's IP and port. Only pods passing their readiness probe are in that list, which is how rolling updates avoid sending traffic to containers still starting. Note that the popular community ingress-nginx controller was retired in March 2026; new clusters should use Gateway API or a maintained controller.

1apiVersion: gateway.networking.k8s.io/v1
2kind: HTTPRoute
3metadata: { name: web }
4spec:
5  parentRefs: [{ name: public-gateway }]
6  hostnames: ["app.example.com"]
7  rules:
8    - matches: [{ path: { type: PathPrefix, value: / } }]
9      backendRefs: [{ name: web, port: 80 }]

05Helm and managed Kubernetes

Real applications need many YAML files that differ slightly between staging and production. Helm packages them into a chart: templates plus a values file, so you install or upgrade a whole application with one command and can roll back to a previous release. Many third-party tools (databases, monitoring, cert-manager) ship as Helm charts. Kustomize is a template-free alternative built into kubectl, using overlays per environment. Running the control plane yourself is hard, so most teams use managed Kubernetes: Amazon EKS, Google GKE, Azure AKS or DigitalOcean DOKS. The provider runs and upgrades the control plane; you still manage node pools, upgrades of your workloads, networking add-ons, security policies and cost. Expect to upgrade the Kubernetes version regularly, since each minor release is supported for roughly a year upstream.

1helm install web ./charts/web -f values.prod.yaml -n prod --create-namespace
2helm upgrade web ./charts/web -f values.prod.yaml -n prod --atomic --wait
3helm history web -n prod
4helm rollback web 3 -n prod
5kubectl rollout status deployment/web -n prod

06When Kubernetes is overkill, and what to use instead

Kubernetes brings a lot: networking plugins, ingress or gateways, certificates, secrets, RBAC, monitoring, upgrades, and YAML for everything. For a team of a few developers running one product, that platform work can cost more than the product's actual infrastructure. If your app fits on one or two servers, Docker Compose with good backups and monitoring is simpler, cheaper and easier to debug. If you want containers with less operational work, managed container services such as AWS ECS with Fargate, Google Cloud Run or Fly.io handle scheduling and scaling without a cluster to manage. Tools like Kamal deploy containers to plain servers with zero-downtime switching. Choose Kubernetes when you have many services, real scaling needs and people who can own the platform.

• One or two servers: Docker Compose.
• Containers without cluster ops: ECS/Fargate, Cloud Run, Fly.io.
• Simple multi-server deploys: Kamal, Docker Swarm, Nomad.

07Inside the control plane: API server, etcd and watches

Every component in Kubernetes talks only to the API server; nothing talks to etcd or to each other directly. The API server authenticates the request, checks RBAC, runs admission controllers (mutating ones can add defaults or sidecars, validating ones can reject objects that break policy), and stores the object in etcd, a consistent key-value store that uses the Raft protocol. etcd needs a majority of members to accept writes, which is why clusters run three or five members: three tolerate one failure, five tolerate two. Controllers do not poll; they open long-lived watches and receive a stream of changes, keep a local cache, and reconcile. The scheduler watches for pods without a node, filters nodes that cannot fit them, scores the rest and writes its choice back. The kubelet on that node watches for pods assigned to it and starts their containers through the container runtime.

• Admission: mutating webhooks, then validating webhooks and policies.
• etcd quorum: 3 members tolerate 1 failure, 5 tolerate 2.
• Back up etcd, or rely on the managed provider to do it.

08Requests, limits, QoS classes and CPU throttling

Requests are what the scheduler reserves; limits are what the kernel enforces. Together they place each pod in a quality-of-service class. Guaranteed: every container has requests equal to limits for CPU and memory. Burstable: some requests or limits are set. BestEffort: nothing set. When a node runs short of memory, the kubelet evicts BestEffort pods first, then Burstable pods that exceed their requests. Memory over the limit is not negotiable: the container is OOM-killed, shows exit code 137 and reason OOMKilled, and restarts. CPU over the limit is throttled instead, through the kernel's CFS quota, and throttling can add large latency spikes to a busy service even when the node has idle CPU. That is why many teams set a memory limit equal to the memory request, set CPU requests carefully, and leave CPU limits off for latency-sensitive services, while namespace quotas keep the total in check.

1resources:
2  requests: { cpu: 500m, memory: 512Mi }
3  limits:   { memory: 512Mi }       # no CPU limit: avoid throttling
4 
5# diagnose
6# kubectl describe pod web-7d9f -n prod | grep -A3 "Last State"
7# kubectl top pod -n prod --containers

09Graceful shutdown and voluntary disruptions

When a pod is deleted, during a rollout, a scale-down or a node drain, two things start at the same time: the kubelet sends SIGTERM to the containers, and the endpoint controller removes the pod from Service endpoints. Proxies and load balancers learn about the removal a moment later, so for a second or two traffic can still arrive at a process that is already shutting down. A short preStop sleep delays SIGTERM until routing has caught up. The app must then stop accepting new work, finish in-flight requests and exit within terminationGracePeriodSeconds, 30 by default, after which it is killed. For planned events like node upgrades, a PodDisruptionBudget tells Kubernetes how many replicas may be down at once, and drains respect it. Topology spread constraints keep replicas on different nodes and zones, so one failure never takes all of them.

1spec:
2  terminationGracePeriodSeconds: 45
3  topologySpreadConstraints:
4    - maxSkew: 1
5      topologyKey: topology.kubernetes.io/zone
6      whenUnsatisfiable: ScheduleAnyway
7      labelSelector: { matchLabels: { app: web } }
8  containers:
9    - name: web
10      lifecycle:
11        preStop: { exec: { command: ["sleep", "5"] } }
12---
13apiVersion: policy/v1
14kind: PodDisruptionBudget
15metadata: { name: web }
16spec: { minAvailable: 2, selector: { matchLabels: { app: web } } }

10A security baseline: Pod Security, RBAC and NetworkPolicy

By default a Kubernetes cluster is permissive: any pod can talk to any other pod, and a pod can run as root with broad privileges. Three built-in mechanisms tighten it. Pod Security Admission enforces the Pod Security Standards per namespace through labels: privileged, baseline or restricted. Restricted requires non-root, no privilege escalation, dropped capabilities and a seccomp profile, and it is a good target for application namespaces. RBAC should follow least privilege: namespaced Roles rather than ClusterRoles where possible, no wildcard verbs, and disable automatic service account token mounting for pods that never call the API. NetworkPolicy is a firewall for pods: start each namespace with a default deny, then allow only the flows you need, such as ingress from the gateway and egress to the database and DNS. NetworkPolicies are enforced only if the CNI plugin supports them, as Calico and Cilium do.

1apiVersion: v1
2kind: Namespace
3metadata:
4  name: prod
5  labels:
6    pod-security.kubernetes.io/enforce: restricted
7---
8apiVersion: networking.k8s.io/v1
9kind: NetworkPolicy
10metadata: { name: default-deny, namespace: prod }
11spec:
12  podSelector: {}
13  policyTypes: [Ingress, Egress]