Kubernetes
Beginner 14 min read Kubernetes

Kubernetes Architecture

Kubernetes is a declarative container orchestration platform split into a control plane and worker nodes. Learn which component does what, and how a request travels from kubectl to a running pod.

control planekube-apiserveretcdkube-schedulerkube-controller-managerkubeletkube-proxy
Prerequisites: What is Docker?
Introduction

What is this?

Kubernetes is a declarative container orchestration platform: you describe the desired state (which images, how many replicas, which ports) and the platform works to make reality match that state. A cluster is split into a control plane, which makes global decisions, and worker nodes, which actually run the workloads. Every interaction flows through the kube-apiserver, the single API endpoint that persists cluster state to etcd.

Motivation

Why do you need it?

  • The control plane runs controllers that continuously reconcile the current state toward the declared desired state.
  • Every component talks to the API server through a versioned API, which makes the cluster extensible, auditable and scriptable.
  • Scheduling, scaling and self-healing happen centrally, so application code does not need to manage infrastructure.
  • Knowing the components is the foundation for diagnosing nearly every production incident in Kubernetes.
Think about it

Mental model

Imagine

An air traffic control tower

Think of

The Kubernetes control plane

Tower controllers coordinate every aircraft and hand off routing instructions; they do not fly the planes. The control plane coordinates every workload and schedules it onto worker nodes, while the kubelet on each node does the actual running.

Mechanics

How it works

  • You submit declarative desired state to the kube-apiserver with kubectl or the REST API.
  • The API server authenticates and validates the request, then persists the object to etcd.
  • The kube-scheduler watches for unassigned pods and picks the best node for each one.
  • The kubelet on that node pulls container images and starts the containers, reporting status back through the API.
  • Controllers such as the deployment, node and endpoints controllers compare current state to desired state and correct any drift.

How a kubectl request travels through the control plane to a worker node.

kubectl / API client
kube-apiserver
etcd
kube-scheduler
kube-controller-manager
kubelet
Pod running
Reference

Key commands

kubectl cluster-info

Show the control plane and CoreDNS endpoint URLs.

Kubernetes control plane is running at https://192.168.49.2:8443
CoreDNS is running at https://192.168.49.2:8443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
kubectl get nodes -o wide

List nodes with roles, Kubernetes version and container runtime.

kubectl get pods -A

List pods across all namespaces.

kubectl describe node minikube

Show capacity, allocatable resources, conditions and taints for a node.

kubectl get events --sort-by=.lastTimestamp -A

Show recent cluster events sorted by time, useful for diagnosing failures.

kubectl api-resources

List every API resource type with its API group, kind and verbs.

Hands-on

Examples

Declarative desired state

Declarative desired state
apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  containers:
  - name: nginx
    image: nginx:1.25

This manifest declares a desired state: one nginx pod named web. kubectl apply sends it to the kube-apiserver, which validates it and stores it in etcd. The scheduler assigns a node and the kubelet starts nginx. Because no controller owns this pod, it is not recreated if it dies — controllers such as Deployment add that guarantee.

Real world

In production

  • Teams run the control plane as a managed service (EKS, GKE, AKS) so they do not patch etcd or API servers by hand.
  • Multiple namespaces with RBAC and resource quotas isolate teams on one shared control plane.
  • Scaling is declarative: bump replicas and the controllers and scheduler handle the rest.
  • Auditability: every change is a versioned API call recorded in etcd and visible through events and audit logs.
Guidelines

Best practices

  • Use kubectl apply with GitOps-tracked manifests; avoid imperative kubectl create and kubectl edit in production.
  • Back up etcd regularly and rehearse restore drills, since etcd holds the entire cluster state.
  • Keep etcd on fast SSD storage with low fsync latency and away from noisy CPU neighbors.
  • Use namespaces with RBAC and quotas so permissions and blast radius stay small.
Watch out

Common mistakes

  • Fixing live objects with kubectl edit and losing the git source of truth.
  • Assuming the API server is reachable on port 8080 without a kubeconfig.
  • Ignoring etcd disk latency, which silently degrades the whole cluster.
  • Scheduling workloads on control plane nodes and exhausting their resources.
Root cause analysis

Common issues

Error
Node status stays NotReady
Root cause

kubelet is down, the node lost network connectivity, or disk pressure set a condition.

Fix

Check the node with kubectl describe node, then verify the kubelet service and node network; free disk if pressure is reported.

Error
The connection to the server localhost:8080 was refused
Root cause

kubectl cannot find or use a kubeconfig, so it falls back to localhost:8080.

Fix

Point kubectl at the right config with kubectl --kubeconfig /path/to/config or export KUBECONFIG.

Error
etcdserver: request timed out
Root cause

Slow disk or overloaded etcd node slows every API write.

Fix

Check etcd health and disk fsync latency, then move etcd to dedicated nodes with fast SSDs.

When things break

Debugging tips

  • kubectl describe node <name> shows capacity, conditions and taints for scheduling failures.
  • kubectl get events --sort-by=.lastTimestamp -A surfaces controller and kubelet errors.
  • kubectl api-resources and kubectl explain <resource> reveal the exact API schema.
  • Check kubelet logs (journalctl -u kubelet) when a node reports NotReady.
Interviews

Interview checkpoint

Test yourself

Quick quiz

0/3
1

Which component is the front door for all API requests?

2

etcd stores both the desired and the observed state of the cluster.

3

Which control plane component decides which node a pod runs on?

Quick reference

Cheat sheet

Control plane inspection
kubectl cluster-infoControl plane + CoreDNS endpoints
kubectl get nodes -o wideNode roles, versions, runtime
kubectl describe node NAMECapacity, conditions, taints
kubectl get events --sort-by=.lastTimestamp -ARecent cluster events
kubectl api-resourcesDiscover all API resource types
Go deeper

Official documentation

Kubernetes Components
docs
Nodes and the control plane
docs
kube-apiserver reference
docs
kubelet reference
docs