Skip to content

Kubernetes Overview

Assumes: you have used a terminal and run a Docker container once. Nothing else.

Kubernetes is a platform for running containerized applications reliably at scale.

It handles deployment, scheduling, health recovery, service discovery, and rollouts so teams can operate applications consistently across environments.

Vocabulary you need first

Three words appear on every page of this site, including this one:

  • Node: a machine, physical or virtual, that runs your containers.
  • Cluster: a set of nodes plus the control plane that manages them.
  • kubectl: the command-line tool you use to talk to a cluster (pronounced "kube control"). Every example command on this site starts with it.

You don't have a cluster yet. Get a Cluster to Practice On sets one up on your laptop in about five minutes, and everything below becomes something you can run rather than read.

Why Kubernetes Exists

Containers made application packaging easier, but running containers in production introduced hard operational problems:

  • How do you place workloads on available machines?
  • How do you recover from container or node failures?
  • How do you scale up and down safely?
  • How do you roll out new versions without downtime?

Kubernetes solves these problems with declarative APIs and controllers.

Core Mental Model

Kubernetes works by continuously reconciling actual state to desired state.

  1. You declare desired state (usually in YAML).
  2. The API server stores that state in etcd.
  3. Controllers compare desired vs actual state.
  4. Controllers take actions until they match.

This loop is why Kubernetes can self-heal and keep systems stable over time.

Two properties of this model are worth internalizing early, because they explain most Kubernetes behavior that surprises newcomers:

  • Controllers act on what is true now, not on a stream of commands (the formal term is level-triggered rather than edge-triggered). They compare the current state against what you asked for. If a controller crashes and restarts, it just looks at desired vs actual state again and continues. Nothing is lost, because nothing depended on catching an event in flight.
  • Convergence is eventual, not instant. kubectl apply returning success means your intent was recorded, not that it was achieved. The cluster then converges toward it - usually in seconds, sometimes never (for example, if no node has enough capacity). This is why checking status and events matters more than checking whether a command "worked."

Key Building Blocks

These are the object types the rest of this page (and the rest of the site) assumes you have met:

  • Pod: the smallest deployable unit. Usually one app container per pod.
  • Deployment: manages stateless pods and rolling updates.
  • StatefulSet: manages stateful workloads with stable identity and storage.
  • Service: stable virtual endpoint in front of pod backends.
  • Ingress or Gateway API: north-south HTTP/TLS routing into cluster services.
  • ConfigMap and Secret: runtime configuration and sensitive values.

Cluster Architecture

A Kubernetes cluster has two major parts:

graph TB
    subgraph Control Plane
        API[API Server]
        ETCD[(etcd)]
        SCH[Scheduler]
        CM[Controller Manager]
        API <--> ETCD
        SCH --> API
        CM --> API
    end

    subgraph Worker Node
        KL[kubelet]
        KP[kube-proxy]
        RT[Container Runtime]
        KL --> RT
    end

    API <--> KL
    API <--> KP
    User([kubectl / CI]) --> API
  • API server: the single entry point for all cluster changes; every component talks through it.
  • etcd: distributed key-value store that holds all cluster state. Only the API server writes to it directly.
  • Scheduler: watches for unscheduled pods and assigns them to nodes based on resources and constraints.
  • Controller manager: runs control loops (Deployment, ReplicaSet, Node, etc.) that reconcile desired state.
  • kubelet: agent on each node that ensures pods are running per the API server's instructions.
  • kube-proxy: maintains network rules on each node to implement Service virtual IPs.
  • Container runtime: executes containers (containerd, CRI-O).

A detail that surprises many people: these components barely talk to each other. The scheduler never calls the kubelet. The kubelet never calls the controller manager. Everything coordinates through the API server by reading and writing shared objects. That design is what makes Kubernetes resilient - components can crash and restart independently without losing coordination state. Control Plane and etcd goes deeper on how these components coordinate and fail.

What happens when you kubectl apply a Deployment

The best way to understand the architecture is to trace one request end to end:

sequenceDiagram
    participant U as kubectl
    participant API as API Server
    participant DC as Deployment controller
    participant RC as ReplicaSet controller
    participant S as Scheduler
    participant K as kubelet (node)

    U->>API: apply Deployment (replicas: 3)
    API->>API: authn → authz → admission
    API-->>U: created (intent recorded)
    DC->>API: sees new Deployment, creates ReplicaSet
    RC->>API: sees new ReplicaSet, creates 3 Pods (no node assigned)
    S->>API: sees unscheduled Pods, filters + scores nodes, binds each Pod
    K->>API: sees Pod bound to my node
    K->>K: pull image, start containers, run probes
    K->>API: report Pod status: Running, Ready

Notice the division of labor:

  1. kubectl only writes an object. It never starts anything.
  2. The Deployment controller doesn't create pods - it creates a ReplicaSet.
  3. The ReplicaSet controller creates Pod objects, but they have no node yet.
  4. The scheduler picks a node for each pod in two phases: filtering (which nodes are even possible - enough CPU/memory, matching tolerations and affinity rules, which are settings that say which nodes a pod may or prefers to run on) and scoring (which of the possible nodes is best). It then writes the decision back as a binding. Scheduling and Placement covers this in depth.
  5. The kubelet on the chosen node notices "a pod is assigned to me" and does the actual work: pulls the image, starts containers, runs health probes, and reports status. Kubelet and Container Runtime traces this final step down to the kernel.

Every arrow in that diagram is a watch on the API server. Nobody polls, and nobody commands anyone else directly.

What Kubernetes Is Not

Kubernetes is not a replacement for:

  • Good application architecture
  • Observability and incident response practices
  • Security design and policy
  • Platform standards and release discipline

It provides powerful primitives. You still need sound operational patterns.

How to Learn Efficiently

Use this sequence:

  1. Get a cluster on your own machine so every command is runnable.
  2. Understand pods and deployments and probes.
  3. Learn networking and services.
  4. Learn namespaces, configuration, and resource requests.
  5. Learn security fundamentals, then maintenance and troubleshooting workflows.

For the full picture, including where developer, admin, and security-specialist paths diverge, see Kubernetes Learning Paths.

Preparing for a certification? The CKA, CKAD, and CKS guides map these topics to exam domains.

Key Takeaways

  • Kubernetes is a reconciliation engine: you declare state, controllers converge toward it.
  • All coordination flows through the API server - components never talk to each other directly.
  • kubectl apply records intent; convergence happens afterward, asynchronously.
  • The scheduler decides where pods run; the kubelet makes them actually run.

Check Yourself

You run kubectl apply and it returns success. Is your app running?

No. apply records intent - the object is stored, nothing more. Controllers then converge the cluster toward it, usually in seconds and occasionally never (if, say, no node has capacity). Check status and events, not the exit code of the command.

The controller manager crashes and restarts thirty seconds later. What happened to the changes it missed?

Nothing was missed, because controllers are level-triggered: they act on current state, not on a stream of events. On restart it re-reads desired versus actual state and continues from there. Nothing depended on catching an event in flight.

Why does the scheduler never call the kubelet directly to start a pod?

Components in Kubernetes coordinate only through the API server. The scheduler writes a binding (this pod goes on that node) to the API; the kubelet on that node is watching for pods assigned to it and picks it up. That indirection is what lets any component crash and restart without losing coordination state.

A pod stays in Pending for ten minutes. Which component would you suspect, and why?

The scheduler, or rather what the scheduler is telling you: Pending means the pod exists in the API but has not been bound to a node. Usually no node passed the filtering phase - insufficient CPU or memory, an unsatisfied node selector, or a taint with no matching toleration. kubectl describe pod shows the scheduler's own reason.

Next Steps

Beginner track - step 1 of 12. Next: Get a Cluster to Practice On. Back to the track overview.