Kubernetes architecture

Kubernetes is an open-source platform that runs containerized applications across a cluster of machines. You describe the desired state (“run three copies of this service, reachable on this address”) and Kubernetes continuously works to make reality match it: placing containers on machines, restarting failures, and scaling up and down.

It has become the standard foundation for running containers at scale and the base of most internal developer platforms.

Diagram

flowchart TB
    dev[kubectl, CI/CD, GitOps] --> api
    subgraph cp [Control plane]
        api[API server]
        etcd[(etcd: cluster state)]
        sched[Scheduler]
        cm[Controller manager]
        api --- etcd
        api --- sched
        api --- cm
    end
    subgraph n1 [Worker node]
        k1[kubelet] --> p1[Pods]
    end
    subgraph n2 [Worker node]
        k2[kubelet] --> p2[Pods]
    end
    api --> k1 & k2
    lb[Ingress / load balancer] --> svc[Service] --> p1 & p2

How it works

• Declarative configuration. You submit desired state as YAML manifests; controllers reconcile actual state toward it.
• Control plane. The API server is the front door, etcd stores cluster state, the scheduler places workloads on nodes, and controllers drive reconciliation.
• Worker nodes run a kubelet agent that starts and monitors containers.
• Core objects: Pods (one or more containers scheduled together), Deployments (manage replicated pods and rolling updates), Services (a stable address for a set of pods), Ingress or Gateway (external HTTP routing), ConfigMaps and Secrets (configuration).
• Extensibility. Custom resources and operators let teams teach Kubernetes to manage databases, certificates and more.

Pros

• Self-healing: failed containers and nodes are replaced automatically.
• Portable: the same manifests run on any cloud or on-premises.
• Scaling and rolling updates built in.
• Huge ecosystem of tools for networking, security, observability and deployment.

Cons

• Complex: many concepts, components and failure modes to learn.
• Operational burden: upgrades, security patches and add-ons need dedicated skills, even on managed services.
• Easy to misconfigure: default settings aren’t secure or resource-efficient.
• Overkill for small workloads.

When to use it

• Many services, run by several teams, that need a consistent runtime.
• Building an internal developer platform.
• Portability across clouds or between cloud and on-premises.

When to avoid it

• A handful of services or a small team. Managed container services or serverless are much simpler.
• No one available to own the platform.

Common pitfalls

• No resource requests and limits, causing noisy neighbors and unpredictable scheduling.
• Secrets treated as secure by default. Kubernetes Secrets are only base64-encoded unless encryption and access controls are configured.
• Running a self-managed cluster when a managed service would do.
• Every team inventing its own manifests. Provide templates or a platform layer.

Related patterns

• Platform engineering and internal developer platforms
• Service mesh
• GitOps
• Microservices

Glossary: service mesh

Further reading

• Kubernetes documentation, “Concepts” (kubernetes.io)
• Brendan Burns et al., Kubernetes: Up and Running