K8s Architecture Overview

When you first look at Kubernetes, the sheer number of components — the API server, controller manager, scheduler, etcd, kubelets, kube-proxies — can feel overwhelming. Without a clear mental map, you'll struggle to debug cluster issues, choose the right setup, or even follow basic tutorials. This lesson gives you that map: a clear, practical kubernetes architecture overview that shows how every piece fits together so you can operate any cluster with confidence.

The problem this lesson solves

Most Kubernetes beginners jump straight into writing YAML files or running kubectl commands without understanding what's running underneath. When something breaks — a pod doesn't start, a node goes NotReady, or the API is unresponsive — they have no idea where to look. A solid kubernetes architecture overview turns you from a button-pusher into someone who can diagnose and fix issues. Without it, you're flying blind.

Pro tip: The architecture is the same whether you run a single-node cluster on your laptop with Minikube or a multi-node production cluster on AWS. Learn it once, apply it everywhere.

Core concept / mental model

Think of Kubernetes as an operating system for your cluster. Just as a laptop has a kernel (Linux, macOS) that manages hardware, memory, and processes, Kubernetes has a control plane that manages the cluster's state. And just as your laptop runs apps in user space, Kubernetes runs your containers on worker nodes.

The two main parts

• Control plane (the brain): Makes global decisions about the cluster (scheduling, responding to events, maintaining desired state).
• Data plane / worker nodes (the muscles): Actually run your applications in pods.

Key components defined

• etcd: A distributed, consistent key-value store that holds the entire cluster state. Think of it as the cluster's "single source of truth."
• kube-apiserver: The front door to the control plane. All communication (from kubectl, nodes, or internal controllers) goes through the API server.
• kube-scheduler: Watches for newly created pods that have no node assigned and picks the best node for them based on resource requirements, policies, and constraints.
• kube-controller-manager: Runs controller processes — each one watches the API server for changes and works to drive the current state toward the desired state.
• kubelet: The agent that runs on every worker node. It ensures that containers are running in a pod as expected.
• kube-proxy: A network proxy that maintains network rules on nodes, enabling communication to pods from inside or outside the cluster.

How it works step by step

Let's trace what happens when you deploy a simple Nginx pod:

1. You run kubectl apply -f nginx.yaml. This sends a REST API request to the kube-apiserver.
2. The API server authenticates your request, validates the YAML, and stores the pod definition in etcd.
3. The kube-scheduler (via its watch loop) sees a new pod that hasn't been scheduled to any node. It evaluates available nodes, picks one, and writes the binding back to the API server.
4. The API server updates etcd with the node assignment.
5. The kubelet on that specific node sees the update and instructs the container runtime (Docker or containerd) to pull the image and start the container.
6. The kubelet continuously reports back to the API server with the pod's status. The API server updates etcd.
7. Meanwhile, the kube-controller-manager runs controllers that ensure replica counts match expectations, service endpoints are correct, and so on.

Key insight: Every action is event-driven and declarative. You describe what you want; Kubernetes makes it so, then maintains it.

Hands-on walkthrough

Setup

You'll need a running Kubernetes cluster. If you're on macOS or Windows, use Docker Desktop with Kubernetes enabled. On Linux, install Minikube.

# Verify your cluster is running and you can connect
kubectl cluster-info
# Should output something like:
# Kubernetes control plane is running at https://127.0.0.1:6443
# CoreDNS is running at https://127.0.0.1:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

View the components

# See control plane components in the kube-system namespace
kubectl get pods -n kube-system

Your output will look similar to:

NAME                               READY   STATUS    RESTARTS   AGE
coredns-6488c6f55c-5pz2r           1/1     Running   0          5m23s
etcd-minikube                      1/1     Running   0          5m38s
kube-apiserver-minikube            1/1     Running   0          5m38s
kube-controller-manager-minikube   1/1     Running   0          5m38s
kube-scheduler-minikube            1/1     Running   0          5m38s
storage-provisioner                1/1     Running   0          5m38s

Notice how each pod name ends with the node name (minikube) — that's how Kubernetes identifies which node the pod is running on.

Examine node details

kubectl get nodes -o wide
# Example output:
# NAME       STATUS   ROLES    AGE    VERSION   INTERNAL-IP     EXTERNAL-IP   OS-IMAGE             KERNEL-VERSION    CONTAINER-RUNTIME
# minikube   Ready    master   5m45s   v1.28.3   192.168.49.2   <none>        Ubuntu 22.04.2 LTS   5.15.0-91-generic   docker://24.0.7

Now run a simple pod and trace its path:

kubectl run nginx --image=nginx:latest
kubectl get pods -w  # watch the pod spin up

You'll see the pod go through Pending (scheduler looking for a node) → ContainerCreating (kubelet pulling the image) → Running.

Compare options / when to choose what

Pro tip: The control plane components are agnostic to the worker node OS — you can even mix Linux and Windows nodes in the same cluster.

Troubleshooting & edge cases

Common errors and fixes

• Pod stays Pending: Check if nodes have sufficient resources (kubectl describe pod <pod> → grep for Events). Also verify that the scheduler is running (kubectl get pods -n kube-system | grep scheduler).
• API server is down: You can't run kubectl commands. Check the control plane node's health (systemctl status kubelet), and inspect etcd (etcdctl endpoint health).
• Node goes NotReady: Usually the kubelet stopped reporting. SSH onto the node, check systemctl status kubelet and journalctl -u kubelet -n 50.
• etcd cluster loses quorum: If more than half of etcd nodes are down, the cluster becomes read-only. Backups are your only rescue — always have automated etcd backups.
• Kubernetes API rate limits: If you have many controllers making frequent API calls, you may get 429 Too Many Requests. Tune --max-requests-inflight and --max-mutating-requests-inflight on the API server.

Edge case: single-node cluster vs. multi-node

On a single-node setup (like Minikube), the control plane and worker run on the same machine. This is great for learning but masks certain issues — e.g., node failure kills everything. In production, always separate control plane from worker nodes for resilience.

What you learned & what's next

You now understand the kubernetes architecture overview: the control plane (API server, scheduler, controller manager, etcd) and the data plane (kubelet, kube-proxy, container runtime). You saw how a pod request flows from kubectl to the API server, through the scheduler to a node, where the kubelet brings it to life. You also learned how to inspect components and troubleshoot basic issues.

This foundation is essential before moving to the next lesson: Pods and Workloads, where you'll learn how to define, deploy, and manage the actual containers that run on these nodes. You now know where they'll run; next, you learn what they'll run.

Final thought: The architecture is your map. When something breaks, you'll know whether to check the control plane (API unresponsive) or the worker node (pod not starting). Practice by breaking your cluster (on a dev setup!) and fixing it using the architecture knowledge you just gained.