Kubernetes Architecture Guide
Learn how Kubernetes control-plane, workload, networking, storage, and observability components fit together, then practice explaining the trade-offs in an architecture diagram.
What is Kubernetes architecture?
Kubernetes architecture splits a cluster into a control plane and worker nodes. The control plane, made of the API server, scheduler, controllers, and etcd, reconciles declared state, while nodes run Pods behind Services and Ingress with storage, configuration, and observability around them.
Last reviewed:
Build a Kubernetes architecture you can explain
- Start with the workload boundaryUse Deployments, StatefulSets, or Jobs according to how the workload runs and stores state.
- Make traffic explicitTrace Ingress, Service, and Pod routing, including the policy boundaries that protect it.
- Separate control from data pathsShow how the API server, scheduler, controllers, and etcd reconcile declared state.
- Plan state and configurationUse persistent storage, configuration, and secrets with an explicit recovery boundary.
- Design for operationsInclude readiness, scaling, observability, and a safe rollout strategy.
The two halves of a cluster
A Kubernetes cluster has a control plane that decides what should run, and worker nodes that run it. The control plane stores the desired state of the cluster and continuously works to make reality match it. Nodes host the Pods, which are the smallest deployable units and contain one or more containers.
A clear architecture diagram separates these two halves, because they fail differently and are operated differently. Application traffic flows through the nodes; configuration and orchestration flow through the control plane.
Control plane and node components
| Component | Where | What it does |
|---|---|---|
| kube-apiserver | Control plane | The front end of the cluster. Every other component talks to the cluster through it, and it is the only component that reads and writes etcd. |
| etcd | Control plane | A consistent, highly available key-value store holding all cluster state. |
| kube-scheduler | Control plane | Watches for new Pods with no node and assigns each to a suitable node. |
| kube-controller-manager | Control plane | Runs the controllers that move current state toward desired state, such as the Deployment and Node controllers. |
| cloud-controller-manager | Control plane (optional) | Integrates with a cloud provider for resources such as load balancers and node lifecycle. |
| kubelet | Each node | Makes sure the containers described in assigned Pods are running and healthy. |
| Container runtime | Each node | Actually runs containers, for example containerd or CRI-O. |
| kube-proxy | Each node (optional) | Implements Service networking rules so traffic reaches the right Pods. |
The reconciliation loop
The idea that explains most Kubernetes behavior is reconciliation. You declare a desired state, for example three replicas of a service. The API server stores it in etcd. Controllers observe the difference between the desired and the current state and act to close it: creating Pods, replacing failed ones, or scaling up. The scheduler places new Pods on nodes, and each node's kubelet starts the containers.
This is why a diagram should show the control plane as a set of loops reacting to declared state, not as a request path. When a node dies, no one tells Kubernetes what to do; the controllers notice the missing Pods and create replacements.
Choose the workload type deliberately
Picking the wrong controller is a frequent source of design problems. Match the workload type to how the application runs and stores state.
| Workload | Use it for | Key property |
|---|---|---|
| Deployment | Stateless services and web APIs | Interchangeable Pods with rolling updates and rollbacks |
| StatefulSet | Databases and other stateful systems | Stable network identity and per-Pod persistent storage |
| DaemonSet | Node-level agents such as log or metrics collectors | One Pod on every matching node |
| Job | Finite batch work | Runs to completion and retries on failure |
| CronJob | Scheduled batch work | Creates Jobs on a schedule |
Make the traffic path explicit
Every Pod gets its own IP address, but Pods are ephemeral, so clients should not depend on those addresses. A Service provides a stable virtual IP and DNS name and load-balances across the healthy Pods selected by its labels. Common Service types are ClusterIP for internal traffic, NodePort, and LoadBalancer for external exposure through a cloud load balancer.
For HTTP traffic from outside the cluster, an Ingress, or the newer Gateway API, defines routing rules by host and path. These rules only take effect if an ingress controller is running in the cluster. In a diagram, trace one request: client, load balancer, ingress, Service, Pod, and then any downstream data store.
Network policies restrict which Pods can talk to which. They are enforced only if the cluster's network plugin supports them, so state that assumption. By default, all Pods can reach all other Pods, which is rarely what you want in production.
State, configuration, and secrets
- Persistent storage: a PersistentVolumeClaim requests storage, a StorageClass describes how it is provisioned, and a PersistentVolume is the underlying volume. Decide the backup and recovery boundary explicitly.
- Configuration: use ConfigMaps for non-sensitive settings so the same image runs in every environment.
- Secrets: they hold credentials, but by default they are only base64-encoded, not encrypted. Enable encryption at rest for etcd, restrict access with RBAC, and consider an external secret manager.
A useful design question is whether a stateful system belongs in the cluster at all. Running a database in Kubernetes is possible with a StatefulSet and the right operator, but a managed database service often removes significant operational work.
Design for scaling and availability
Availability in Kubernetes is the result of several small settings working together, so a good design names them.
- Resource requests and limits: requests drive scheduling decisions and limits cap usage. Without requests, the scheduler cannot place Pods sensibly.
- Readiness and liveness probes: a readiness probe keeps traffic away from a Pod that is not ready; a liveness probe restarts a stuck container. They answer different questions and are easy to confuse.
- Horizontal Pod Autoscaler: adjusts the number of replicas based on metrics such as CPU. Scaling nodes is a separate mechanism, so a diagram that shows Pods scaling should also show how nodes scale.
- PodDisruptionBudget: limits how many replicas can be down during voluntary disruptions such as node drains.
- Rolling updates: control how many Pods are replaced at a time so a deployment does not remove capacity all at once.
- Spreading replicas: use topology spread constraints or anti-affinity so replicas land on different nodes and zones.
Security basics to include
A diagram that ignores security is incomplete. At minimum, show role-based access control with least-privilege service accounts, network policies limiting Pod-to-Pod traffic, Pod security settings that avoid running as root or with extra privileges, and a trusted image source with pinned versions rather than the mutable latest tag.
For managed clusters, note which responsibilities belong to the provider, such as the control plane, and which belong to you, such as node configuration, workloads, and access policies.
Observability and operations
Operations is a first-class part of the architecture. Include a metrics pipeline for cluster and application metrics, centralized logging, and alerts on symptoms that users feel, such as error rate and latency, as well as on cluster health, such as failing nodes and Pods stuck in a pending or crash-looping state.
Also state your rollout and rollback strategy. Kubernetes can roll a Deployment back to a previous revision, but that only helps if your changes are backward compatible with the data they touch.
Trade-offs worth stating
| Decision | Option A | Option B | Deciding factor |
|---|---|---|---|
| Control plane | Managed (EKS, AKS, GKE) | Self-managed | Operational capacity versus need for control |
| Isolation | Namespaces in one cluster | Separate clusters | Blast radius, compliance, and cost |
| Stateful data | In-cluster StatefulSet | Managed database service | Operational burden versus portability |
| Exposure | Ingress or Gateway API | One LoadBalancer per Service | Cost and routing needs |
| Scaling | Fixed replicas | Autoscaling | Traffic variability and cost sensitivity |
Common mistakes
- Omitting resource requests and limits, which makes scheduling unpredictable and lets one workload starve others.
- Skipping readiness probes, so traffic reaches Pods that cannot serve it yet.
- Running a single replica and calling it highly available.
- Treating Pods as durable. Anything written to a container filesystem is lost when the Pod is replaced.
- Assuming Secrets are encrypted by default, or granting broad RBAC permissions out of convenience.
- Using the latest image tag, which makes deployments and rollbacks unpredictable.
- On self-managed clusters, running etcd without backups or a tested restore.
A checklist for your diagram
Before you call a Kubernetes diagram finished, check that it shows the workload type and why it was chosen, the full request path from client to Pod, the control plane and what it reconciles, where state is stored and how it is recovered, how configuration and secrets are delivered, how the system scales and tolerates node failure, and how you would observe and roll it back. For definitive details on any component, consult the official Kubernetes documentation.
Frequently asked questions
What are the main components of Kubernetes?
The control plane has the API server, scheduler, controller manager, and etcd. Each worker node runs a kubelet, a container runtime, and a network proxy, and hosts Pods.
What is the difference between a Deployment and a StatefulSet?
A Deployment manages interchangeable stateless Pods. A StatefulSet gives Pods stable identities and storage, which suits databases and other stateful workloads.
How does traffic reach a Pod in Kubernetes?
External traffic typically enters through an Ingress, is routed to a Service, and is load-balanced across the matching Pods, with network policies controlling what may connect.
How do I draw a Kubernetes architecture diagram?
Show the workload boundary, the traffic path from Ingress to Pods, the control plane, persistent storage, and the operational pieces such as scaling and observability.