Glossary

What the system currently looks like, as observed rather than assumed.

Reported by the components doing the work rather than assumed by whoever asked for it. The gap between this and desired state is the only thing a control loop acts on.

See also Desired state, Reconciliation

The gates that can change or refuse an object after you are authorised but before it is stored.

Mutating admission fills in defaults and applies namespace policy, so what gets stored is not always what you sent. Validating admission runs after that, because it has to judge the finished object.

See also API server, Object

The one component everything talks to, and the only way in or out of the cluster's state.

An HTTP API over the objects. It authenticates, authorises, defaults, validates and stores; it does not run, schedule or repair anything. Controllers and nodes reach it the same way you do.

See also Object, etcd, Control plane, Watch

A set of machines that Kubernetes manages as one pool of compute.

A cluster is a control plane plus the nodes it schedules work onto. You talk to the cluster, not to individual machines.

See also Control plane, Node

The default kind of Service: a virtual address reachable only from inside the cluster.

No pod or node has the address and nothing listens on it, which is why it can't be pinged. It only works because kube-proxy's rules on every node rewrite connections to it.

See also Service, kube-proxy, NodePort

A claim about an object right now, with a reason and the time it last changed.

Available, Progressing, Ready and their kin. Unlike events they do not expire, do not accumulate, and carry a machine-readable reason, which is what makes them the thing to read and the thing to alert on.

See also Actual state, Event, Object

Non-secret configuration data, kept outside the container image.

Mount it as files or inject it as environment variables. The same image can then run in staging and production unchanged.

See also Secret, Volume

An isolated process running from an image.

See also Pod

A packaged filesystem and start command that a container is created from.

The image is immutable and is identified by a tag or a digest. Anything that has to differ between environments should stay out of it.

See also Container, ConfigMap

Something that repeatedly observes state, compares it to what is wanted, and acts.

Kubernetes is a collection of these rather than one program working through a plan. They run independently, and none of them assumes it was the last thing to change anything.

See also Reconciliation, Controller, Desired state

The components that decide what should run and where.

The API server, scheduler, and controller manager. It holds desired state and continuously drives the cluster toward it.

See also Cluster, Reconciliation, Scheduler

A loop that watches one kind of object, compares it against what exists, and closes the gap.

It is handed the name of an object to look at, never a description of what happened to it, so it always reads the current state before deciding. That is what makes retrying free and a missed notification harmless.

See also Reconciliation, Control loop, Idempotent, Owner reference

The DNS server inside the cluster, answering for Services and the pods of headless Services.

It runs as a Deployment in kube-system behind a Service still called kube-dns, and every pod's resolv.conf points at it. A Service is `<name>.<namespace>.svc.cluster.local`, and short names work because of the search list the kubelet writes into each pod.

See also Service, Headless Service

A container keeps exiting and is being restarted with a growing delay between attempts.

Not a phase and not an error from Kubernetes: it is the node reporting that it has restarted this container several times and is now waiting longer each time before trying again. The pod itself is untouched, with the same name, address and node it had before.

See also Pod, Container

Creates a Job from a template on a cron schedule.

It never runs a pod itself, and each Job it makes is named after the minute it was scheduled for. It has no idea how long a run takes, so a new run starts on top of one that is still going unless `concurrencyPolicy` says otherwise, and the schedule is read on the controller's clock, usually UTC, unless `timeZone` is set.

See also Job

Runs one copy of a pod on every node, or every node that matches.

It has no replica count, the number of nodes is the count. Its pods are pinned to their node, come and go with it, and aren't evicted by a drain, which is why it's used for things about the machine: log shippers, metrics agents, network plugins.

See also Node, Pod, StatefulSet

You describe the end state you want, not the steps to reach it.

You submit an object saying "three replicas of this image". Kubernetes works out the difference from reality and closes the gap.

See also Reconciliation, Manifest

The object you write to run an application: a description of a pod, and how many of it.

Two parts: the pod template, and everything else. Change the template and every pod is replaced, because creating and deleting pods is the only thing a Deployment does to them. Change the replica count and the pods you have carry on untouched. It owns replicasets, which is how it keeps the previous template around to roll back to.

See also Pod template, ReplicaSet, Pod, Rollout

What the system is supposed to look like.

You write it down and it stays written down. Nothing about it changes when reality drifts away from it.

See also Actual state, Reconciliation, Declarative

The list of pod addresses behind a Service, kept up to date by a controller.

Each address is marked ready or not, and only ready ones get traffic. A large Service is split over several slices, 100 addresses each by default. When a Service misbehaves, its slices are the first thing to look at.

See also Service, Selector, kube-proxy

The key-value store holding every object in the cluster.

The only component with state that cannot be recreated. It is run as an odd number of members that agree by majority; lose the majority and the cluster stops changing while the running containers carry on.

See also API server, Object, resourceVersion, Quorum

An object recording that something happened, addressed to nobody and deleted within the hour.

Repeats of the same thing about the same object are folded into one record with a counter, so a large count is a duration rather than a magnitude. Nothing in the cluster reads events to decide anything; they exist so a person can reconstruct the past.

See also Object, Condition, Level-triggered

The system is not always correct, but something is always working on it.

A reconciler moves a system toward its desired state rather than putting it there. Between the moment reality diverges and the moment it matches again there is a window where the system is wrong and converging at the same time. Asking whether the gap is closing is usually more useful than asking whether it is closed.

See also Reconciliation, Control loop, Desired state, Actual state

The successor to Ingress, split into objects for whoever owns each part.

A GatewayClass names the implementation, a Gateway is the entrypoint the platform team owns (ports, TLS, which namespaces may attach), and routes like HTTPRoute are each app team's rules. It's installed as CRDs rather than built in.

See also HTTPRoute, Ingress

A Service with no ClusterIP, whose name resolves to the addresses of its pods.

Set with `clusterIP: None`. kube-proxy ignores it, and DNS answers with every ready pod instead. It's what a StatefulSet's `serviceName` points at, which gives each of its pods a name like `db-0.db`.

See also Service, CoreDNS, StatefulSet

An app team's HTTP routing rules, attached to a Gateway.

Rules match on path, headers or query parameters and send traffic to Services, with weights for splits and filters for rewrites and redirects. When several rules match, an exact path beats a prefix, a longer prefix beats a shorter one, and then the older route wins.

See also Gateway API, Service

Running it again changes nothing beyond what running it once did.

A reconcile pass reads what should exist, reads what does exist, and closes the gap. Doing that a hundred times has the same effect as doing it once, which is what lets the system retry anything, at any time, without bookkeeping.

See also Reconciliation, Controller, Control loop

Rules for routing external HTTP traffic to Services by hostname and path.

The object is inert on its own. An ingress controller watches Ingresses and configures a real proxy to match. Anything beyond hosts, paths and TLS is done with annotations that differ per controller, and the API is frozen in favour of the Gateway API.

See also Ingress controller, Gateway API, Service

A proxy running in the cluster that watches Ingress objects and configures itself from them.

It usually sits behind one LoadBalancer Service that every Ingress shares. `ingressClassName` on an Ingress says which controller it's meant for.

See also Ingress, LoadBalancer, Controller

A container that runs to completion before a pod's ordinary containers are started.

Init containers run in order, each one finishing before the next begins, and the pod does not start until the last has exited successfully. Each is a separate image, so setup tooling never has to be installed into the application's image. They run again every time the pod starts.

See also Pod, Container

Runs pods until the work finishes, and replaces the ones that fail.

It counts pods that exited 0 rather than pods that are running. A failed pod is replaced after a growing delay until there have been more than `backoffLimit` failures, and an evicted pod counts as failed. A replacement starts the command from the beginning, so anything a Job runs has to be safe to run twice. A process that hangs never fails, which is what `activeDeadlineSeconds` is for.

See also CronJob, Pod template, Pod, Idempotent

The agent on every node that turns Services into rules in the node's kernel.

It watches Services and EndpointSlices and writes iptables or nftables rules, so a connection to a Service's address has its destination rewritten to one of the pods before it leaves the node. Nothing is actually proxied. On many clusters the network plugin does this job instead, often with eBPF, and kube-proxy isn't installed at all.

See also Service, EndpointSlice, ClusterIP

The command-line client for the API server.

A convenience over HTTP requests. `kubectl get pods -v=8` prints the calls it makes, and anything it can do can be done with curl and a credential.

See also API server, Manifest

The agent on each node that starts and supervises the node's pods.

See also Node, Pod

A key/value tag attached to an object, used for grouping and selection.

Pods usually get theirs from the template of whatever made them. Labels mean nothing to Kubernetes on their own; they matter because selectors on Services, Deployments and policies pick pods by them.

See also Selector, Service

Acting on how things currently are, rather than on being told that they changed.

The edge-triggered alternative acts on the change itself, which makes a lost, duplicated or reordered notification into a wrong outcome. Reading the current state instead makes all three harmless, which is why every loop in Kubernetes works this way.

See also Reconciliation, Controller, Idempotent, Event

A Service that asks the cloud for an external load balancer in front of it.

By default it also gets a NodePort, and the load balancer sends traffic to that port on the nodes. `allocateLoadBalancerNodePorts: false` skips the NodePort for load balancers that don't need one, like those sending straight to pod addresses. On hardware with nothing to answer the request, like a bare metal cluster without MetalLB, its external address stays pending.

See also NodePort, ClusterIP, Ingress

A YAML or JSON file describing a Kubernetes object.

See also Declarative

A scope for object names within a cluster.

Two namespaces can each hold a Deployment named web. Namespaces scope most objects, but not cluster-wide ones such as nodes.

See also Object, Cluster

Rules for which connections the pods it selects will accept or make.

A pod accepts and sends anything until a policy selecting it covers a direction, and then only what some rule allows. Rules only ever allow, the network plugin enforces them, and on a plugin that doesn't support them they silently do nothing.

See also Pod network, Label, Selector

A single machine, virtual or physical, that runs workloads.

Each node runs a kubelet and a container runtime. The control plane places pods onto nodes; the node is responsible for actually running them.

See also Cluster, Kubelet, Pod

A Service that also opens the same port, between 30000 and 32767, on every node.

Traffic to any node's address on that port lands on the Service. It's only reachable from wherever the nodes' addresses are, which is often nowhere public.

See also ClusterIP, LoadBalancer, Service

A record in the Kubernetes API describing a piece of desired state.

It has a kind, a name, a spec saying what you want, and later a status saying what is. Creating one changes nothing by itself, and a controller acting on it is what changes something.

See also Manifest, Declarative, Namespace, Desired state

A note on an object saying which object it was created for.

The only link between a Deployment and its ReplicaSet, or a ReplicaSet and its pods. It records a uid rather than a name, so a recreated parent does not adopt the old one's children, and the garbage collector uses it to delete downwards when a parent goes.

See also Controller, Object, Deployment, ReplicaSet

A piece of storage in the cluster, with a lifetime independent of any pod.

See also PersistentVolumeClaim, StorageClass

A pod's request for storage of a given size and access mode.

The claim is what a workload references. Kubernetes binds it to a matching volume, provisioning one on demand if a StorageClass says how.

See also PersistentVolume, StorageClass

The smallest deployable unit: one or more containers that share a network namespace and storage.

Containers in a pod share an IP address and can talk over localhost. Pods are disposable by design, and you rarely create them by hand.

See also Container, Node, Init container, Deployment

The flat network every pod gets an address on, where any pod can reach any other without NAT.

Each node gets a range of addresses and every pod on it gets one from that range, handed out by the network plugin. Addresses aren't rewritten between pods, so a pod sees its real address and so does whoever it talks to. An address lasts exactly as long as its pod.

See also Pod, Node, Service

The description of a pod held inside another object, rather than a pod of its own.

A whole pod spec with no name, because it is about to be several pods. Its one property worth remembering is that a change to it is never applied to the pods already made from it. Whatever holds the template answers by building new pods and retiring the old ones, even for a field that could have been edited on a pod directly.

See also Pod, Deployment, Rollout

The majority of etcd members that must agree before a write counts.

Three members tolerate one failure and five tolerate two. An even number buys nothing over the odd number below it, which is why cluster sizes are odd.

See also etcd

Look at what is wanted, look at what exists, act on the difference, then look again.

The loop the whole system is built from. It reads the current state rather than a stream of instructions, so an event that arrives twice or never arrives at all changes nothing.

See also Desired state, Actual state, Control loop, Controller

One interchangeable copy of a workload.

Interchangeable is the important word. If any copy is as good as any other, the system is free to delete one and start another somewhere else.

See also ReplicaSet, Deployment, Pod

Keeps a stated number of identical pods alive, and nothing else.

A count and a pod template. It counts rather than tracks, so the pods are interchangeable and replacing one means a new pod with a new name. Changing its template does nothing to the pods it has already made, which is the reason deployments exist.

See also Deployment, Pod, Pod template, Owner reference

An opaque marker of when an object was last written.

It is the store's revision at the time of the write, not a version of your app, and that counter only ever increases across the whole cluster. The field is still documented as opaque: send it back with an update and the write is refused if anything changed in the meantime, but do not do arithmetic on it.

See also API server, etcd, Watch

Replacing every pod in a set with a new one, a few at a time, so the set keeps serving.

Triggered by the pod template reading differently, whatever changed in it. An image and a label cost exactly the same. If the new pods never become ready the rollout stops where it is rather than carrying on, so a broken release looks like a stuck count.

See also Deployment, Pod template

The control plane component that picks which node a new pod should run on.

It filters nodes that cannot fit the pod, then scores the rest on resource fit, spread, and affinity rules.

See also Control plane, Node, Pod

Like a ConfigMap, but for sensitive values and handled more carefully.

Base64 encoding is not encryption. Secrets are only as private as the cluster's RBAC and encryption-at-rest settings make them.

See also ConfigMap

A label query that decides which pods an object applies to.

A pod matches when it has every label the selector lists, whatever else it has and whatever created it. It's asked again every time pods change, so a new pod with the right labels is picked up straight away.

See also Label, Service, EndpointSlice

A stable name and address for a changing set of pods.

It picks its pods with a selector, and the EndpointSlice controller keeps a list of their addresses. Connections to the Service's address are sent to one of the ready pods on that list, picked per connection, by rules kube-proxy or the network plugin puts on every node.

See also ClusterIP, Selector, EndpointSlice, kube-proxy, Pod

Runs pods that each keep a name, a place in an order, and a disk of their own.

Pods are named db-0, db-1 and so on, created in order and removed in reverse, and a replacement comes back under the old name. Each pod gets its own disk from `volumeClaimTemplates`, which outlives the pod and is reattached to whichever pod takes that name next. If a node stops answering, it won't replace that node's pod until it's sure the old one is gone, because two pods with one name is worse than none.

See also Deployment, DaemonSet, PersistentVolumeClaim

A named recipe for provisioning storage automatically.

See also PersistentVolumeClaim

A directory made available to a pod's containers.

See also ConfigMap, PersistentVolume

A long-lived request that reports changes to a set of objects as they happen.

Not a message queue. It can drop you and be resumed from a version, or refuse to resume and make you list everything again, which is safe only because nothing treats an entry as an instruction.

See also API server, resourceVersion, Controller