A Kubernetes cluster is a group of computers that work together as if they were one big computer, run by a single manager.

Start with the smallest idea: a container

Modern software is usually packed into containers. A container is a sealed box that holds a program together with everything that program needs to run, such as its libraries and settings. Because the box is sealed, it runs the same way on your laptop, on a test server, and in a data center. This solves the old complaint “it works on my machine, but not on yours.”

One container is easy to handle. But a real company may need thousands of them: a box for the website, boxes for the payment system, boxes for search, boxes for sending emails, and several copies of each so that nothing breaks when one fails. Somebody has to decide which computer runs which box, restart the ones that crash, add more when traffic grows, and remove them when traffic falls. That somebody is Kubernetes.

Now the definition

A cluster is the complete Kubernetes system that does this job. It has two kinds of members. The first is a group of worker nodes, which are the computers that actually run your containers. The second is the control plane, which is the brain that decides what should run where and keeps watching to make sure reality matches the plan. Together, the brain and the workers form one cluster, and you talk to that cluster as a single unit.

What a cluster is not

• It is not one special computer. A cluster is made of many ordinary computers, which can be physical servers, cloud virtual machines, or even containers pretending to be computers on a laptop.
• It is not your application. The cluster is the platform. Your application is what you place on it.
• It is not a folder of settings. Settings tell the cluster what you want, but the cluster is the living system that carries those wishes out.

The vocabulary ladder

Beginners often mix up words that sit at different levels. It helps to see them as a ladder, from the biggest idea to the smallest. The cluster sits at the top because everything else lives inside it.

To appreciate the cluster, imagine life without one.

The single-server world

In the early days of the internet, a company would place its website on one big server. That was simple, but it had painful limits. If the server broke, the website went dark. If traffic doubled on a sale day, the server slowed down or crashed. If engineers wanted to update the software, they often had to take the site offline. And buying a bigger server has a ceiling: at some point no larger machine exists, and the biggest ones cost enormous amounts of money.

The many-server world, done by hand

The next step was to buy many smaller servers and spread the work between them. This is more flexible, but it creates new chores. Someone must log in to each machine, install the software, keep versions in sync, watch for failures, and move workloads around when a machine dies. With ten servers this is annoying. With ten thousand it is impossible without automation. Large companies built internal systems to automate it. Google’s system was called Borg, and the lessons from Borg shaped Kubernetes, which Google released to the public in 2014.

The cluster as the answer

A cluster turns many machines into one pool of computing power. You stop asking “which server should run this?” and start saying “I need three copies of this program, each with a certain amount of memory.” The cluster figures out the rest. If a machine dies, the cluster notices and starts replacements elsewhere. If traffic grows, the cluster can add more copies, and, with the right setup, even more machines.

The five gifts of a cluster

Every cluster, from a tiny practice cluster to a giant production one, has the same basic shape.

flowchart TB
    subgraph CP["Control Plane - the brain"]
        API["API Server - the front door"]
        ETCD[("etcd - the cluster memory")]
        SCH["Scheduler - chooses a node"]
        CM["Controller Manager - fixes any gap"]
        API --> ETCD
        SCH --> API
        CM --> API
    end
    subgraph W1["Worker Node 1"]
        K1["kubelet - node agent"]
        KP1["kube-proxy - network rules"]
        RT1["Container Runtime"]
        POD1["Pods running your app"]
        K1 --> RT1
        RT1 --> POD1
    end
    subgraph W2["Worker Node 2"]
        K2["kubelet - node agent"]
        KP2["kube-proxy - network rules"]
        RT2["Container Runtime"]
        POD2["Pods running your app"]
        K2 --> RT2
        RT2 --> POD2
    end
    USER["You or your automation tools"] --> API
    API --> K1
    API --> K2

Read the diagram from the top. Every request, whether it comes from a person at a keyboard or from an automated pipeline, enters through the API server. The API server records what you asked for in etcd, the cluster’s memory. The scheduler and the controller manager watch the API server for new work. Down in the worker nodes, a small agent called the kubelet listens to the API server for jobs that belong to its own machine, and starts the containers for them.

Two halves, two jobs

How the parts find and trust each other

A cluster is made of many separate programs, so they need a safe way to meet. Every component talks to the API server over an encrypted connection, and each one proves its identity with a certificate, which works like a signed photo badge that the cluster’s own certificate authority issues. When a new machine joins, it receives a temporary credential, introduces itself, and is given a permanent badge once accepted. After that, the kubelet on the machine sends a small heartbeat message at regular intervals so the control plane knows the machine is alive.

The people who use the cluster receive a small connection file, often called a kubeconfig. It lists the address of the API server, the credentials to use, and a default namespace. Each entry in this file, called a context, is a shortcut for one cluster and one identity. Engineers who work with several clusters switch between contexts the way you switch between saved contacts on a phone. Keep this file safe, because it may contain the keys to the kingdom.

The control plane is small in size but huge in importance. Let us meet its members one at a time.

etcd: the memory that must never be lost

Of all these parts, etcd deserves special respect. It is the single source of truth. If the scheduler crashes, it can be restarted with no loss. If the API server crashes, another copy can take over. But if etcd loses its data and there is no backup, the cluster forgets what it was supposed to run. That is why etcd is normally run as a group of three or five copies that vote on every change using an agreement method called consensus. As long as a majority of the copies are alive, the cluster keeps working. With three copies, one can fail. With five copies, two can fail. Using an odd number avoids tie votes.

The API server as a good receptionist

The API server does not just pass messages along. For every request it performs three checks in order. Authentication asks who you are. Authorization asks whether you are allowed to do this specific action. Admission control asks whether the request follows the cluster’s rules, and may even adjust it, for example by adding a default memory limit. Only after passing all three does the request get saved. Because everything goes through this one door, it is also the best place to add security and auditing.

A worker node is just a computer with three small programs installed. Those programs turn an ordinary machine into a member of the cluster.

What a node contributes

Each node offers a fixed amount of processor time, memory, and disk. Kubernetes reads these numbers when the node joins, keeps a little aside for the system itself, and treats the rest as allocatable. The scheduler uses these numbers like a hotel manager checking which rooms are free. When you say that a container needs a certain amount of memory, you are making a reservation, and the scheduler only places the Pod on a node with enough unreserved room.

Looking after nodes: maintenance without downtime

Machines need regular care: security patches, operating system updates, and hardware repairs. A cluster makes this safe with a two-step routine. First the node is cordoned, which means “do not place any new Pods here.” Then it is drained, which means the existing Pods are politely asked to leave and are recreated on other nodes. Once the node is empty, engineers can update or replace it, and afterward they allow work to return. Because a Deployment always keeps the wanted number of copies running, users notice nothing, provided the cluster has enough spare room and important apps run more than one copy.

Nodes can be almost anything

A node can be a physical server in a data center, a virtual machine from a cloud provider, or, in a local practice cluster, a container that pretends to be a machine. To the cluster it does not matter. All it needs is the kubelet, a runtime, and a network path to the control plane. That is why the same cluster ideas apply from a tiny laptop setup to a giant cloud deployment.

Machines are only the stage. The actors are the objects you create inside the cluster.

flowchart TB
    subgraph CL["One Kubernetes cluster"]
        subgraph NS1["Namespace: shop-production"]
            D1["Deployment: web"] --> P1["Pods"]
            S1["Service: web"] --> P1
        end
        subgraph NS2["Namespace: shop-testing"]
            D2["Deployment: web"] --> P2["Pods"]
            S2["Service: web"] --> P2
        end
        subgraph NS3["Namespace: payments-team"]
            D3["Deployment: billing"] --> P3["Pods"]
            S3["Service: billing"] --> P3
        end
    end

Notice that two namespaces can each contain an object called “web” without any conflict, because names only need to be unique inside their own room. Namespaces do not create hard walls by themselves, though. To stop teams from harming each other you also add permissions, resource limits, and network rules, which we cover in the security chapter.

The secret behind every cluster is a very simple habit repeated forever: compare what you want with what exists, and fix the difference.

Desired state versus actual state

When you use a cluster you never give step-by-step instructions such as “start a container on machine number seven.” You state the goal, for example “always keep three copies of the checkout service running.” This goal is called the desired state. What is really running at any moment is the actual state. Inside the control plane, many controllers run in endless loops, each watching one kind of object. Whenever the two states differ, the controller takes a small action to bring them closer. This idea is called reconciliation.

What happens when a machine dies

sequenceDiagram
    participant N as Worker Node 2
    participant API as API Server
    participant NC as Node Controller
    participant RC as Replica Controller
    participant SCH as Scheduler
    participant K3 as kubelet on Node 3
    N--xAPI: Stops sending heartbeats
    NC->>API: Notice missing heartbeats and mark node as not ready
    NC->>API: Mark the Pods on that node for replacement
    RC->>API: Count Pods, find 2 of 3 and create a new Pod
    SCH->>API: Assign the new Pod to Node 3
    K3->>API: Notice the new Pod assigned to me
    K3->>API: Start the containers and report Pod running

Every node sends a regular heartbeat to the control plane, a little message meaning “I am alive.” When the heartbeats stop for long enough, the node controller marks the node as not ready. The replica controller then sees that the Deployment wants three Pods but only two are healthy, so it creates a new Pod record. The scheduler chooses a healthy node, and the kubelet there starts the containers. No human was woken up. The whole cycle usually completes within minutes, and users of a well-designed application may never notice.

How controllers hear about changes

You might wonder how controllers notice a change so quickly without pestering the API server every second. They use a watch: a long-lived connection over which the API server pushes a small message whenever an object of interest is created, changed, or deleted. Each controller reacts to those messages and also does a full check now and then, in case a message was missed. This design keeps traffic low and reactions fast, and it explains how one control plane can supervise thousands of nodes.

Avoiding two bosses: leader election

In a high-availability cluster, three copies of the scheduler and the controller manager may all be running. If all three acted at once, they would fight, for example by placing the same Pod on three different nodes. To prevent this, the copies hold an election. One becomes the leader and does the real work, while the others wait, ready to take over within seconds if the leader disappears. The API servers, by contrast, can all work at the same time behind a load balancer, because they mostly read and write the shared database rather than make decisions.

Two journeys matter: how your instructions reach the cluster, and how a user’s request reaches your application.

Journey one: from your keyboard to a running Pod

Journey two: from a customer’s phone to your code

flowchart LR
    U["Customer browser"] --> DNS["DNS - finds the address"]
    DNS --> LB["Cloud Load Balancer"]
    LB --> ING["Ingress Controller - routes by address and path"]
    ING --> SVC["Service - stable address"]
    SVC --> PA["Pod A on Node 1"]
    SVC --> PB["Pod B on Node 2"]
    SVC --> PC["Pod C on Node 3"]
    PA --> DB[("Database")]
    PB --> DB
    PC --> DB

A customer types your website address. DNS translates the name into the address of a load balancer, which spreads incoming connections across the cluster’s entry points. The ingress controller reads the request, decides which Service should handle it, and forwards it. The Service then picks one of its healthy Pods, possibly on a completely different node, and the Pod does the real work, perhaps calling a database. The Service address stays the same even while Pods are replaced behind it. This single idea, a stable front with changing members behind it, is why upgrades and crashes stay invisible to users.

The lifecycle of a Pod

Pods are mortal. A Pod is created, waits to be scheduled, pulls its images, runs, and eventually ends, either because it finished its job, was replaced during an update, or lost its node. Kubernetes never “repairs” a Pod in place. It replaces it with a fresh copy. For this reason, anything precious such as customer data must live outside the Pod, in a database or a persistent disk, and not in the Pod’s own temporary storage.

The stages a Pod passes through

Kubernetes summarizes a Pod’s life with a few simple phases. Pending means the Pod has been accepted but is not running yet, perhaps because it is waiting for a node with enough room or for its image to download. Running means at least one container is up. Succeeded means every container finished its job and exited cleanly, which is normal for one-time tasks. Failed means the containers ended with an error. If a Pod stays Pending for a long time, the events usually explain why, such as a shortage of memory across all nodes or a mistyped image name. Learning to read these phases is the fastest route to becoming comfortable with debugging clusters.

Two things turn a pile of machines into a usable platform: a network where every Pod can be found, and disks that outlive the containers.

The networking promises

Kubernetes makes a few clear promises about networking, and a component called a network plugin keeps them. Every Pod receives its own address. Every Pod can talk to every other Pod without awkward translation, even across nodes. Nodes can talk to Pods, and Pods can talk to nodes. On top of this, Services provide stable names, and DNS inside the cluster lets one application find another simply by name, like calling a friend by name instead of remembering a number.

Three ways to expose an application

A Service comes in several types, and each answers the question “who should be able to reach this application?” in a different way.

• ClusterIP: the default. The Service gets an address that works only inside the cluster. It is ideal for internal parts such as a database or a background worker.
• NodePort: opens the same port on every node, so outside traffic can enter through any machine. It is simple but rough, and mostly used for testing.
• LoadBalancer: asks the cloud provider to create a real load balancer with a public address that forwards traffic to the Service. This is the common choice for exposing an application on the internet.

Above these sits Ingress, which shares a single load balancer between many websites by looking at the requested address, saving both money and effort. On a laptop cluster, there is no cloud to create a real load balancer, so local tools provide substitutes.

Network policies: rules for who may call whom

By default, in most clusters, all Pods may talk to all other Pods. That is convenient for learning but risky for production. Network policies let you state rules such as “only the web Pods may call the payment Pods.” They work like locked doors between departments, and they require a network plugin that supports them.

Storage: giving containers a long memory

Containers have a short memory by design. When one is replaced, its private files disappear. For data that must survive, Kubernetes offers volumes. A PersistentVolume is a piece of real storage, such as a cloud disk, and a PersistentVolumeClaim is a Pod’s request for storage of a certain size. A StorageClass describes the type of disk, so the cluster can create the right disk automatically when a claim appears. When a Pod that uses such a disk is replaced, the disk is reattached to the new Pod and the data is still there.

Not every cluster looks the same. The right shape depends on what you need to protect against.

flowchart TB
    LBAPI["Load balancer in front of the API"] --> CP1["Control plane 1 in Zone A"]
    LBAPI --> CP2["Control plane 2 in Zone B"]
    LBAPI --> CP3["Control plane 3 in Zone C"]
    CP1 --- E1[("etcd copy 1")]
    CP2 --- E2[("etcd copy 2")]
    CP3 --- E3[("etcd copy 3")]
    CP1 --> WA["Workers in Zone A"]
    CP2 --> WB["Workers in Zone B"]
    CP3 --> WC["Workers in Zone C"]

How big can one cluster get?

The Kubernetes project documents a comfortable range for a single cluster of up to about 5,000 nodes, 150,000 Pods, and 110 Pods per node. Real companies push near or beyond these figures with careful tuning. OpenAI has publicly written about running Kubernetes clusters of several thousand nodes for machine learning, and Google has publicly announced support for GKE clusters with tens of thousands of nodes. Most organizations never come close, and that is fine. Bigger is not better, because a larger cluster is also a larger blast radius when something goes wrong.

Where clusters live

The same cluster ideas apply in three very different homes. On a laptop, tools such as Minikube and kind create small clusters in minutes for learning and testing. In a company data center, teams install Kubernetes on their own servers with tools such as kubeadm or with enterprise products, and they take responsibility for every part, including the control plane and backups. In the public cloud, managed services such as Amazon EKS, Google GKE, and Azure AKS run the control plane for you across several zones, and you decide how many workers to attach. Most companies use a mix: laptop clusters for development, automated temporary clusters for testing, and managed clusters for production.

One big cluster or many small ones?

This is one of the most debated questions in real teams. One large cluster shares hardware efficiently and is simpler to manage in a single place, but a bad upgrade or a mistake affects everyone. Many smaller clusters isolate problems, satisfy laws that require data to stay in a country, and let teams move at their own speed, but they cost more in duplicate overhead and need good tooling to manage together. A common middle path is one cluster per environment (development, staging, production) and one per region for production.

A cluster earns its keep when demand jumps and when hardware fails. Both are handled by scaling and by redundancy.

Three ways to scale

Telling the scheduler how to place work

By default the scheduler simply looks for free room. Real systems often need more control, and the cluster offers several gentle tools. Resource requests reserve a minimum amount of processor and memory for a container, while limits set the maximum it may use. Node selectors and affinity rules attract Pods to nodes with certain labels, for example machines that have fast disks or graphics processors. Anti-affinity rules do the opposite and push copies of the same app apart, so that no single node or zone holds them all. Taints mark a node as off-limits to ordinary Pods, and only Pods carrying a matching toleration may enter, which is how teams reserve special machines for special jobs.

Think of a hotel front desk. Requests are the reservations guests make. Affinity is the guest asking for a room near the elevator, and anti-affinity is the manager placing rival tour groups on different floors. A taint is a sign saying “staff only,” and a toleration is the staff badge that opens the door.

Building for high availability

• Spread the control plane across three zones so that no single building failure stops the brain.
• Spread the workers across zones and ask Kubernetes to place copies of the same app in different zones.
• Run more than one copy of every important application. A single copy is a single point of failure.
• Use health checks so traffic is only sent to Pods that are truly ready.
• Set disruption budgets that promise a minimum number of copies stay up during upgrades and repairs.
• Back up etcd and application data, and practice restoring from those backups.

A cluster is a powerful tool, but not every project needs one.

Where the money goes

A cluster has three main cost buckets. The first is the control plane, which is free or lightly charged on some managed services and a fixed monthly fee on others, and on a self-managed cluster it means the machines and the engineers who care for them. The second, and usually the biggest, is the worker nodes, since you pay for their processor and memory whether or not your Pods fill them. The third is everything around the cluster: load balancers, disks, backups, and data transfer between zones or out to the internet. The most common waste is over-provisioning, where teams reserve far more memory and processor than their applications use. Measuring real usage, setting realistic requests, and letting autoscaling remove idle machines often cuts the bill dramatically.

Key trade-offs

A useful rule of thumb: if you run a handful of small services with modest traffic, a simpler platform may serve you better. Once you have many services, several teams, changing traffic, and a need for reliability, the cluster starts to pay for itself many times over.

A cluster can start any program on demand across many machines. That power is exactly why attackers want it, and why security must be planned early.

The layers of defense

Tenant isolation inside a shared cluster

When several teams share one cluster, namespaces alone are not enough. Combine them with separate permissions per namespace, resource quotas that cap how much each team can consume, and network policies between namespaces. For very strict needs, such as running code from unknown customers, use separate clusters or stronger sandboxing for the containers.

A cluster that you cannot observe is a cluster you cannot trust. Watching it means collecting three kinds of signals.

What to watch at each level

Health checks: how the cluster knows a Pod is truly fine

A running process is not always a working process. An application can be alive but stuck, or alive but still loading data. Kubernetes lets you describe three kinds of checks, called probes. A startup probe gives slow applications time to start before anyone judges them. A readiness probe tells the cluster when the Pod is ready to receive traffic, and while it fails, the Pod is quietly removed from its Service. A liveness probe tells the cluster when the Pod is stuck, and a failure causes it to be restarted. Well-chosen probes are among the cheapest ways to make an application more reliable.

Common tools

Kubernetes includes a small metrics server that powers basic usage views and autoscaling. Most teams add Prometheus to collect metrics, Grafana to draw dashboards, and a log collector such as Fluent Bit or a cloud logging service to gather container logs into one searchable place. Cloud providers offer their own integrated options, and OpenTelemetry has become a popular standard for traces. Choose tools that fit your team’s size, and start with a few useful dashboards instead of hundreds of unused ones.

Patterns are habits that healthy teams share. Anti-patterns are shortcuts that feel smart today and hurt later.

Patterns that work

Anti-patterns to avoid

These are lessons teams often learn painfully. You can learn them cheaply, right now.

Best practices

• Keep Kubernetes up to date. Each version is supported for roughly a year. Upgrade one version at a time, and test on a staging cluster first.
• Use a managed control plane if you can. Running etcd and the API server well is hard work that a cloud provider does for you.
• Label everything. Labels are small tags on objects that let you find, group, and select them, and they drive cost tracking and monitoring.
• Define health checks. Readiness checks keep traffic away from Pods that are not ready. Liveness checks restart Pods that are stuck.
• Set resource requests and limits for every container.
• Enable autoscaling at both the Pod and machine level, with sensible minimums and maximums.
• Back up and rehearse recovery. A backup that has never been restored is only a hope.
• Automate cluster creation with files or infrastructure tools so a new cluster takes minutes, not weeks.
• Review permissions regularly and remove access that is no longer needed.
• Watch cost. Tag resources by team, review the bill monthly, and delete unused clusters and disks.

Common mistakes

These examples come from what the organizations have said publicly, and details may have changed since.