The easiest way I found to actually understand it wasn't reading more diagrams. It was mapping the theory onto a cluster I'd already built — my EKS cluster running shopflow, a microservices e-commerce platform I've been building as a hands-on DevOps project.

So here's Kubernetes architecture, explained the way I wish someone had explained it to me: through a real cluster, not a generic one.

The Two Halves of Every Cluster

Every Kubernetes cluster splits into two parts:

1. The control plane — the brain. It makes decisions but doesn't run your application.

2. The worker nodes — the muscle. This is where your actual application containers run.

In EKS, AWS manages the control plane for you. You don't SSH into it, you don't patch it, you barely think about it — which is exactly why EKS is a good starting point for understanding the concept without getting lost in managing it yourself.

The Control Plane: Decisions, Not Execution

The control plane doesn't run your app. It runs the components that decide how your app should run.

• API server — the front door. Every kubectl command, every CI/CD deploy, every ArgoCD sync goes through here first.

• etcd — the cluster's memory. It stores the entire desired state: what should be running, how many replicas, what config, everything.

• Scheduler — decides which worker node a new pod should land on, based on resource availability.

• Controller manager — constantly compares "what's actually running" against "what etcd says should be running," and corrects any drift.

For shopflow, this is the layer that makes GitOps with ArgoCD actually work. ArgoCD talks to the API server, the API server updates etcd, and the controller manager makes sure the cluster's real state eventually matches it. I don't manually reconcile anything — the control plane's whole job is doing that reconciliation for me.

The Worker Nodes: Where Your App Actually Lives

Worker nodes are where the four FastAPI microservices in shopflow actually run as pods.

Each node runs:

• kubelet — the agent that talks to the control plane and makes sure the containers scheduled to this node are actually running.

• kube-proxy — handles networking so Services can route traffic to the right pods, even as pods get replaced or rescheduled.

• Container runtime — actually runs the containers (pulling images, starting/stopping them).

My HPAs (Horizontal Pod Autoscalers) live at this layer too — they watch resource usage per pod and tell the control plane to schedule more replicas when load increases. The control plane decides where those new pods go; the worker nodes are just where they land and run.

Where IRSA and OIDC Fit In

This is the part that took me longest to actually get, and it's not usually in the basic architecture diagrams.

Pods need permissions to talk to AWS services — S3, RDS, KMS, whatever. The naive (and dangerous) approach is hardcoding credentials into the pod. Shopflow instead uses IRSA (IAM Roles for Service Accounts) with OIDC.

Here's the flow: EKS runs an OIDC provider. A Kubernetes ServiceAccount gets annotated with an IAM role ARN. When a pod using that ServiceAccount starts, it can assume that IAM role directly — no static credentials anywhere, no secrets to rotate.

This isn't a separate system bolted onto Kubernetes; it's Kubernetes' own trust model (ServiceAccounts, tokens) extended to talk to AWS's IAM. Once I understood that ServiceAccounts are actually identity objects — not just Kubernetes-internal permission scoping — IRSA stopped feeling like magic.

Namespaces as Blast-Radius Control

Shopflow's cluster isn't one flat space. The application runs in its own namespace, and monitoring lives in a completely separate one.

That separation matters architecturally: the Prometheus Agent running in the monitoring namespace has its own ServiceAccount and ClusterRole, scoped to read metrics across the whole cluster — but it's still logically isolated from the application namespace. If something goes wrong in one namespace, RBAC and network boundaries stop it from silently affecting the other.

What Happens When the Cluster Itself Is Unhealthy

This is where architecture stopped being theoretical for me. If your monitoring stack runs inside the same cluster it's observing, and the cluster has a serious problem, your visibility disappears at the exact moment you need it most.

That's why in shopflow, the Prometheus Agent (lightweight, in-cluster) only collects metrics. The actual Prometheus Server — the one storing data and firing alerts — runs independently on an EC2 instance outside the cluster, receiving metrics over remote_write. If the EKS control plane or nodes have issues, the server keeps running and I can still see exactly when things went wrong.

That's not a Kubernetes-native pattern — it's a decision I made because I understood the architecture well enough to see the failure mode.

Why Mapping Theory to a Real Cluster Helped

Reading about the control plane and worker nodes in the abstract never made it click. What made it click was asking, for each component: where does this show up in my actual cluster, and what breaks if it's missing?

• No API server → ArgoCD can't sync, kubectl stops responding

• No scheduler → new pods stay Pending forever

• No kubelet on a node → that node stops reporting healthy, pods get rescheduled elsewhere

• No IRSA → pods either can't reach AWS services or (worse) need hardcoded credentials

Kubernetes architecture is a lot easier to hold onto once it's not abstract — once it's the exact set of moving parts keeping your own project alive.

Thank You