Introduction to Kubernetes

Kubernetes (often abbreviated as K8s) is a production-grade, open-source platform for automating deployment, scaling, and management of containerised applications. It provides a uniform, declarative API surface that abstracts away the underlying infrastructure so engineers can focus on expressing what they want rather than how to achieve it.

1 · What is Kubernetes?

At its core Kubernetes is a distributed systems operating system. Just as a single-machine OS (Linux, Windows) schedules processes, manages memory, handles I/O, and provides system-call abstractions, Kubernetes performs the equivalent tasks across a fleet of machines for containerised workloads.

Unlike a traditional OS, Kubernetes is cluster-wide: the unit of resource is a node (physical or virtual machine), and workloads are transparently distributed across all nodes by the scheduler.

Official definition (project README)

"Kubernetes is an open-source system for automating deployment, scaling, and management of containerized applications. It groups containers that make up an application into logical units for easy management and discovery."

Broader production definition

For platform engineers, Kubernetes is also:

• A declarative configuration API – you describe desired state in YAML/JSON; the system converges reality toward that state.
• A self-healing runtime – components watch for drift and correct it automatically, without human intervention.
• A control plane for your entire infrastructure – networking, storage, compute, certificates, and secrets are all first-class API resources.
• An extensibility framework – CRDs, webhooks, and the aggregation layer let you extend the API to model any domain concept.
• A standard layer – the same manifests run on bare metal in your own data centre, AWS, GCP, Azure, Raspberry Pi, or a laptop.

2 · Why Kubernetes Exists

To understand why Kubernetes exists, you must understand the problems that preceded it. The evolution goes through three distinct eras:

When Docker popularised containers in 2013, organisations quickly ran into the "container sprawl" problem: running hundreds of containers manually across dozens of hosts is operationally impossible. You need:

• Automatic placement of containers onto healthy nodes
• Restart of containers that crash
• Scaling up or down based on demand
• Rolling updates with zero downtime
• Service discovery – how does container A find container B?
• Load balancing across replicas
• Secret and configuration management
• Resource accounting and fair-share scheduling
• Storage lifecycle management
• Health checking and eviction

Google had already solved this problem internally with Borg (2003) and later Omega. Kubernetes (2014) is the open-source, redesigned-for-community successor that incorporates a decade of Google's production learnings. See 01 · History for the full timeline.

3 · Problems Kubernetes Solves

3.1 Scheduling and Placement

Manually deciding which server runs which container is error-prone and doesn't scale. The kube-scheduler evaluates every node's available CPU/memory, hardware topology, affinity rules, taints, and policies to place each Pod on the optimal node — automatically, in under a millisecond at moderate scale.

3.2 Self-Healing

Controllers run reconciliation loops: they compare desired state (stored in etcd) with observed state (reported by the kubelet) and take corrective actions — restarting crashed containers, replacing failed nodes, rescheduling evicted Pods — without paging anyone.

// Simplified reconciler pattern (every controller implements this)
func (r *DeploymentController) Reconcile(ctx context.Context, req Request) (Result, error) {
    // 1. Fetch desired state from API server
    desired := r.Get(req.NamespacedName)

    // 2. Fetch current state from cluster
    current := r.ListPods(desired.Spec.Selector)

    // 3. Diff
    missing := desired.Replicas - len(current.Running)

    // 4. Act
    if missing > 0 {
        r.CreatePods(missing, desired.Template)
    } else if missing < 0 {
        r.DeletePods(-missing)
    }

    // 5. Update status
    r.UpdateStatus(desired, current)
    return Result{}, nil
}

3.3 Horizontal Scaling

The Horizontal Pod Autoscaler reads metrics (CPU, memory, custom) from the Metrics Server or Prometheus Adapter and adjusts the replicas field of a Deployment/ReplicaSet automatically. Cluster Autoscaler then provisions or deprovisions nodes as the pod demand changes.

3.4 Rolling Updates and Rollbacks

Deployments orchestrate rolling updates: it spins up new Pods with the new image, waits for them to become Ready, then terminates old Pods — ensuring zero downtime. A single kubectl rollout undo reverts to the previous ReplicaSet revision.

# Trigger a rolling update
kubectl set image deployment/web app=myimage:v2

# Watch rollout progress
kubectl rollout status deployment/web

# Undo if something is wrong
kubectl rollout undo deployment/web

# Rollout history
kubectl rollout history deployment/web

3.5 Service Discovery and Load Balancing

A Service object gives a stable virtual IP (ClusterIP) and DNS name to a dynamic set of Pods. kube-proxy programs iptables/IPVS rules so that traffic to the ClusterIP is load-balanced across all healthy Pod endpoints. The Pods themselves can be rescheduled and get new IPs — the Service absorbs that churn transparently.

3.6 Configuration and Secret Management

ConfigMaps store non-sensitive configuration (environment variables, config files). Secrets store sensitive data (passwords, TLS certs, tokens) encrypted at rest in etcd and mounted into Pods as environment variables or files. External secret stores (Vault, AWS Secrets Manager) can integrate via CSI Secret Store or External Secrets Operator.

3.7 Storage Lifecycle

The CSI (Container Storage Interface) plugin model decouples storage drivers from the Kubernetes release cycle. PersistentVolume and PersistentVolumeClaim objects model the storage lifecycle: claim, bind, mount, unmount, release, and (optionally) reclaim. Storage Classes enable dynamic provisioning — Pods get volumes without pre-provisioned PVs.

3.8 Environment Parity

The same container image and manifest that runs on a developer's laptop (kind, minikube, k3s) runs identically in production. The CRI, CNI, and CSI plugin model means only the plugin implementations differ — the API is identical everywhere.

4 · Traditional Systems vs Kubernetes

5 · The Kubernetes Mental Model

Before diving into internals, you need the right mental model. There are three key ideas that unlock everything else:

5.1 Desired State vs. Observed State

Every Kubernetes resource object has two logical halves:

• spec — what you want (desired state). You write this.
• status — what the cluster has (observed state). The system writes this.

Controllers are the agents that continuously work to make status match spec. This is the control loop, and it is the fundamental pattern behind every Kubernetes component.

5.2 Everything is an API Object

Kubernetes exposes a RESTful API. Every resource — Pod, Node, Service, ConfigMap, CRD instance — is an object with a versioned API group, a Kind, metadata (name, namespace, labels, annotations), spec, and status.

# Anatomy of a Kubernetes resource object
apiVersion: apps/v1         # <group>/<version> — "core" group uses just "v1"
kind: Deployment            # Object type
metadata:
  name: web                 # Unique name within namespace
  namespace: production     # Logical partition
  labels:                   # Key/value pairs — used by selectors
    app: web
    version: v3
  annotations:              # Non-identifying metadata — arbitrary data
    deployment.kubernetes.io/revision: "3"
spec:                       # DESIRED STATE — you write this
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
      - name: app
        image: myapp:v3
        resources:
          requests:
            cpu: "250m"
            memory: "128Mi"
          limits:
            cpu: "500m"
            memory: "256Mi"
status:                     # OBSERVED STATE — system writes this
  replicas: 3
  readyReplicas: 3
  availableReplicas: 3
  conditions:
  - type: Available
    status: "True"

5.3 Watch, Not Poll

The API server supports long-lived watch connections (HTTP chunked streaming, WebSocket, or gRPC depending on client). Every controller, kubelet, and kubectl informer uses watch to receive change events immediately instead of polling. This is what makes Kubernetes highly responsive — a controller reacts in milliseconds to a state change, not after a 30-second poll interval.

# Watching all Pod events in real time (same mechanism controllers use internally)
kubectl get pods --watch

# Watch a specific resource version (raw API)
curl -k https://<apiserver>/api/v1/pods?watch=1&resourceVersion=12345 \
  -H "Authorization: Bearer <token>"

6 · Cluster Architecture Overview

A Kubernetes cluster consists of two logical planes:

• Control Plane — the brain: API server, etcd, scheduler, controller manager, cloud-controller-manager.
• Data Plane (worker nodes) — the muscle: kubelet, kube-proxy, container runtime, CNI plugin.

6.1 Control Plane Components

The control plane is typically run on dedicated nodes (control plane nodes, formerly called masters). In a production HA cluster you have 3 or 5 control plane nodes.

6.2 Worker Node Components

7 · The Declarative Model in Depth

The declarative model is Kubernetes' most important design decision. Contrast it with the imperative alternative:

## IMPERATIVE (old way — scripting)
# Create a container
docker run -d --name web -p 80:8080 --restart=always myapp:v1

# Scale it (manual loop)
for i in 2 3; do
  docker run -d --name web-$i -p 808$i:8080 myapp:v1
done

# Update it (manual, risky)
docker stop web; docker rm web
docker run -d --name web -p 80:8080 myapp:v2

# Problems:
# - State is in your head / scripts
# - Not idempotent
# - No audit trail
# - Does not self-heal

## DECLARATIVE (Kubernetes way)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels: {app: web}
  template:
    metadata:
      labels: {app: web}
    spec:
      containers:
      - name: app
        image: myapp:v1
        ports:
        - containerPort: 8080
---
# Benefits:
# - Apply is idempotent (kubectl apply is safe to run repeatedly)
# - State is in version control (GitOps)
# - Any drift is auto-corrected by controllers
# - Rolling update = change image: myapp:v2, reapply

When you run kubectl apply -f deployment.yaml, here is what happens internally:

1. kubectl serialises the object to JSON and sends an HTTP PATCH (or POST for new objects) to the API server.
2. The API server authenticates and authorises the request, runs admission webhooks, validates the schema, and persists the object to etcd.
3. The relevant controller (e.g., Deployment controller) receives a watch event for the changed object.
4. The controller computes the diff and makes further API calls (e.g., creates a new ReplicaSet).
5. The scheduler sees the unscheduled Pods and binds them to nodes.
6. The kubelet on each target node sees the Pod binding and asks the CRI to pull the image and start containers.
7. The kubelet reports Pod status back to the API server, which stores it in etcd.

The entire chain from kubectl apply to running containers typically completes in 2–30 seconds, depending on image pull time.

8 · The API Object Model

8.1 API Groups and Versions

Kubernetes organises resources into API groups that evolve independently.

8.2 Resource Naming and Namespacing

Resources are either cluster-scoped (Nodes, PersistentVolumes, ClusterRoles, Namespaces) or namespace-scoped (Pods, Deployments, Services, Secrets). A fully-qualified resource reference is: <apiVersion>/<kind>/<namespace>/<name> for namespace-scoped, <apiVersion>/<kind>/<name> for cluster-scoped.

8.3 Labels, Annotations, and Selectors

Labels are key/value pairs used for grouping and selection. Selectors are queries over labels — Services, ReplicaSets, and NetworkPolicies all use label selectors to identify target Pods.

Annotations carry arbitrary non-identifying metadata — tool configuration, audit information, last-applied config. They are not queryable as selectors.

metadata:
  labels:
    app: web
    env: production
    tier: frontend
    version: v3.2.1
  annotations:
    # Ingress controller config
    nginx.ingress.kubernetes.io/rewrite-target: /
    # GitOps metadata
    argocd.argoproj.io/managed-by: argocd
    # Deployment tooling
    kubectl.kubernetes.io/last-applied-configuration: |
      {...}

9 · Core Concepts Glossary

10 · Platform Personas — Who Uses Kubernetes and How

Kubernetes serves many different engineering roles. Understanding which persona you are helps you focus on the right sections of this documentation.

11 · Quick Reference: Essential kubectl Commands

# ---- Cluster Info ----
kubectl cluster-info                      # API server URL and CoreDNS
kubectl get nodes -o wide                 # All nodes with IPs, OS, kernel
kubectl describe node <node-name>         # Node capacity, allocatable, events
kubectl get componentstatuses             # etcd, scheduler, controller-manager health (deprecated 1.20+)
kubectl get --raw /healthz                # API server health check
kubectl get --raw /metrics | head -40     # Prometheus metrics from API server

# ---- Namespace management ----
kubectl get namespaces
kubectl create namespace prod
kubectl config set-context --current --namespace=prod

# ---- Pod operations ----
kubectl get pods -A -o wide               # All pods, all namespaces, node info
kubectl describe pod <name>              # Full event stream, status, volumes
kubectl logs <pod> -c <container> --previous  # Previous container's logs
kubectl exec -it <pod> -- bash           # Interactive shell
kubectl port-forward pod/<name> 8080:80  # Local port tunnel

# ---- Deployment operations ----
kubectl apply -f manifest.yaml           # Declarative apply (idempotent)
kubectl diff -f manifest.yaml            # Preview changes before apply
kubectl rollout status deployment/<name> # Watch rollout progress
kubectl rollout history deployment/<name> # See revision history
kubectl rollout undo deployment/<name>   # Rollback to previous revision
kubectl scale deployment/<name> --replicas=5

# ---- Debugging ----
kubectl get events --sort-by=.lastTimestamp
kubectl top nodes                        # CPU/Memory usage (needs metrics-server)
kubectl top pods -A --sort-by=memory
kubectl debug node/<node> -it --image=busybox  # Debug node with privileged pod
kubectl auth can-i create pods --as=serviceaccount:default:mysa  # RBAC check

# ---- Raw API access ----
kubectl get --raw /api/v1/namespaces
kubectl get --raw /apis/apps/v1/deployments
kubectl proxy &                          # Proxy API to localhost:8001 (no TLS)

12 · Production Best Practices (Introduction Level)

13 · Kubernetes Versioning and Release Cadence

Kubernetes follows a semantic-ish versioning scheme: v<MAJOR>.<MINOR>.<PATCH>. In practice MAJOR is always 1; every new feature release is a MINOR bump. As of early 2025, the current stable release is 1.32.

• Release cadence: 3 minor releases per year (roughly every 4 months).
• Support window: 3 minor versions supported at any time (N, N-1, N-2). Each minor version supported for ~14 months.
• API deprecation policy: GA APIs supported for 12 months / 3 releases minimum. Beta APIs for 9 months / 3 releases.
• Skew policy: kubelet may be at most 2 minor versions behind the API server. kube-proxy must match kubelet or be 1 behind.

# Check cluster and client versions
kubectl version --short

# Deprecated API check (before upgrading)
kubectl convert -f old-manifest.yaml --output-version apps/v1  # requires kubectl convert plugin

# API resource availability
kubectl api-resources
kubectl api-versions | grep apps

14 · Introduction to Troubleshooting Mindset

Kubernetes debugging follows a systematic top-down approach:

1. Start with events: kubectl describe pod <name> — the Events section at the bottom tells you what happened.
2. Check controller logs: if a Deployment isn't rolling, check the controller-manager logs.
3. Check scheduler logs: if Pods are stuck in Pending, the scheduler log shows why it couldn't place them.
4. Check kubelet logs on the target node: container pull errors, CRI failures, volume mount failures appear here.
5. Check the container logs: kubectl logs <pod> -p (previous container) for crash reasons.
6. Check network: use kubectl exec -it <debug-pod> -- curl http://<service> to test connectivity.

Next Files to Study

References

• Kubernetes Official Documentation — kubernetes.io/docs
• Borg, Omega, and Kubernetes (Google, ACM Queue 2016) — foundational paper describing the lineage
• Kubernetes the Hard Way — Kelsey Hightower's manual cluster bootstrap tutorial
• CNCF Kubernetes Architecture Guide — github.com/cncf/k8s-conformance
• Kubernetes API Reference — kubernetes.io/docs/reference/kubernetes-api/
• client-go source — github.com/kubernetes/client-go (informers, work queues, leader election)
• OCI Image Spec — github.com/opencontainers/image-spec
• OCI Runtime Spec — github.com/opencontainers/runtime-spec
• CNI Spec — github.com/containernetworking/cni
• CSI Spec — github.com/container-storage-interface/spec