{"canonical_url":"https://engineer.company/glossary/kubernetes/","content_markdown":"# Kubernetes\n\n## What it is\n\nKubernetes, often written K8s, is open-source software that runs containerised\napplications across a group of machines, called a cluster, and holds them to a\ndescription you give it: which image each application runs, how many copies\nexist, how much memory and CPU each copy may use, and how other programs reach\nit. The project's own documentation calls it \"a portable, extensible, open\nsource platform for managing containerized workloads and services\". The name is\nGreek for helmsman or pilot, K8s keeps the K and the s and replaces the eight\nletters in between with their count, and Google open-sourced the project in\n2014.\n\nA cluster has two halves. The control plane holds the description: the API\nserver is the one HTTP interface every change goes through, etcd stores what it\nis told, the scheduler assigns each new Pod to a suitable node, and the\ncontroller manager runs the loops that act on the description. On every worker\nnode, the kubelet makes sure the Pods assigned there are running, kube-proxy\nmaintains the network rules behind Services, and a container runtime such as\ncontainerd or CRI-O starts the containers. Docker Engine stopped being a\nbuilt-in runtime in Kubernetes 1.24, and images built with Docker run unchanged,\nbecause they are standard OCI images.\n\nThe description is a set of objects, usually written as YAML. A Pod is the\nsmallest unit Kubernetes schedules: one or more containers that share a network\naddress and storage on one machine. A\n[Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)\nsays how many identical Pods should exist and replaces them step by step when\ntheir template changes. A Service gives a changing set of Pods one stable name\nand address, picking its members by label. A small web application looks like\nthis:\n\n```text\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: web\nspec:\n  replicas: 3\n  selector:\n    matchLabels:\n      app: web\n  template:\n    metadata:\n      labels:\n        app: web\n    spec:\n      containers:\n        - name: web\n          image: registry.example.com/web:1.4.2\n          resources:\n            requests:\n              cpu: 250m\n              memory: 256Mi\n            limits:\n              memory: 256Mi\n          readinessProbe:\n            httpGet:\n              path: /healthz\n              port: 8080\n```\n\nIt is usually weighed against three smaller options. Docker Compose describes\ncontainers on one machine, and when that machine goes away, so do they. A\nservice manager such as systemd can restart a crashed container and start it at\nboot, which covers a great many needs with far less machinery, but it has no\nnotion of moving work to another machine. Hosted platforms such as Google Cloud\nRun or Azure Container Apps run containers without handing you a control plane\nto operate, in exchange for fewer settings. The documentation is also plain\nabout what Kubernetes is not: a traditional all-inclusive platform as a service.\nIt does not build your application, and it ships no databases or message queues\nof its own.\n\n## Why it matters\n\nThe central idea is that the cluster keeps working towards a written description\ninstead of running a list of commands once. Applying the file above starts\nnothing directly; it records a wish. Controllers are control loops that watch\nthe cluster and act to move its current state closer to the desired one. If a\nmachine dies and three copies become two, a controller sees the gap, a new Pod\nis created, and the scheduler places it on a machine with room. Because the\ndescription is a set of files, it can live in a repository and go through the\nsame review as the code it runs.\n\nReleases come with the platform. The default strategy is a rolling update: new\nPods start, and old ones stop as the new ones become ready, within limits that\ndefault to 25% extra and 25% missing at any moment. Each change to the Pod\ntemplate is kept as a revision, ten by default, and `kubectl rollout undo`\nreturns to the previous one. The script that once drained a server, swapped a\nbinary and brought it back becomes built-in behaviour.\n\nThe scheduler also changes the economics of a fleet. It places each Pod by the\nCPU and memory the Pod requests, so many small services share a set of machines\ninstead of each getting a server sized for its worst day.\n\nThe price is real. A cluster is a distributed system in its own right, with\nversions to upgrade on a schedule, a network layer, a storage layer,\ncertificates and access control, all of which someone has to understand when\nthey misbehave. Managed offerings such as Google Kubernetes Engine, Amazon EKS\nand Azure Kubernetes Service run the control plane for you, but every manifest,\nand usually the worker nodes, stay yours. For a handful of services on one or\ntwo machines, a plain service manager often does the job with fewer moving\nparts.\n\n## What it looks like in practice\n\n[The company's stack page](/tech-stack/) states the rule plainly: Docker and\nKubernetes for the workloads that earn them, and plain systemd units for the\nones that do not. Kubernetes is chosen per workload, for the size and shape of\nthe job, and not as a default.\n\nWorkloads that earned it appear in one engagement.\n[Twenty Docker applications were deployed and maintained across Google Cloud and AWS](/portfolio/ran-20-docker-apps-on-google-cloud-and-aws/),\namong them R-based analytics apps, with consistent configuration and monitoring\nso that no application became a special case. Troubleshooting went through\nPodman and the orchestration debugging through Kubernetes. The page reports that\nproblems were diagnosed faster and that deployments stayed stable and\nreproducible.\n\nThe other half of the rule shows on the company's own platform.\n[A container plane built on Podman and Quadlet](/portfolio/ran-containers-on-podman-and-quadlet/)\nruns each container as a service of the operating system's own supervisor,\ndescribed in the same declarative form as everything else on the host. The\ncontainers use host networking and publish no ports, so the firewall rules the\nhardening role installs stay in charge. Where Kubernetes would roll out a new\nimage through its API, a deploy user without root runs one fixed script that\nbuilds the image and restarts the service. On one\nhost, that gives every container a written description and the supervisor the\nhost already trusts, with no second process manager. What it leaves out is\nplacement across machines and replacing a dead node, which is where Kubernetes\nbegins to pay for its weight.\n\n## Where it goes wrong\n\nMost Kubernetes trouble comes from the gap between what a manifest asks for and\nwhat the cluster reports back.\n\n**A rollout sits half-finished while the deploy job reports success.** When new\nPods never become ready, because of a wrong image tag, a crash on start, a\nfailing readiness probe or a missing quota, the Deployment stops making\nprogress. After the progress deadline, 600 seconds by default, it records the\nreason `ProgressDeadlineExceeded`, and the documentation says Kubernetes takes\nno other action: the old Pods still running keep serving, and nothing rolls back\non its own. `kubectl rollout status` exits non-zero once the deadline passes, so\na deploy step can wait on it and undo the release:\n\n```sh\nkubectl apply -f web.yaml\nkubectl rollout status deployment/web --timeout=10m \\\n  || kubectl rollout undo deployment/web\n```\n\n**A container restarts with `OOMKilled`, or slows down on a node with spare\nCPU.** The kernel enforces limits, and the two resources behave differently. A\ncontainer over its memory limit can be killed and restarted; one at its CPU\nlimit is throttled, so it runs slower without dying, which looks like an\napplication problem. The scheduler places Pods by what they request, not by what\nthey use, so low requests crowd a node and high ones leave machines idle. A\nlimit given without a request becomes the request. Set memory from measured\nusage, and treat CPU limits as a deliberate decision.\n\n**A slow-starting application is killed before it finishes starting.** A failing\nliveness probe makes the kubelet kill and restart the container, so an\napplication that needs a minute to load, checked after ten seconds, restarts\nforever. A startup probe holds off the other checks until the application is up.\nA readiness probe takes a Pod out of its Service without restarting it, which\nsuits a Pod that is busy or warming a cache. A liveness probe that calls the\ndatabase restarts every replica at once when the database is slow, turning a\nslow dependency into an outage.\n\n**A Pod started by hand disappears, and a fix made by hand comes undone.** A Pod\ncreated on its own stays on its node until it ends, is deleted or evicted, or\nthe node fails, and no controller recreates it; the documentation advises a\nDeployment or a Job even for a single copy. A change made with `kubectl edit`\nlives only in the cluster, and the next apply from the repository puts the old\nvalue back, so an emergency fix belongs in the files as soon as the emergency is\nover.\n\n## Further reading\n\n- [Kubernetes overview](https://kubernetes.io/docs/concepts/overview/) — the\n  project's own account of what Kubernetes is, what it offers and what it leaves\n  out.\n- [Pods](https://kubernetes.io/docs/concepts/workloads/pods/) — the smallest\n  unit Kubernetes schedules, its lifecycle and why Pods are rarely created by\n  hand.\n- [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)\n  — rolling updates, rollbacks, revision history and the progress deadline.\n- [Service](https://kubernetes.io/docs/concepts/services-networking/service/) —\n  stable names and addresses in front of a changing set of Pods.\n- [Resource Management for Pods and Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/)\n  — requests, limits, and how the kernel enforces each.\n- [Configure Liveness, Readiness and Startup Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)\n  — the three probes and how to protect a slow-starting container.\n\n\u003chttps://engineer.company/glossary/kubernetes/\u003e\n","date_modified":"2026-10-20T21:59:50Z","description":"What Kubernetes is, how Pods, Deployments and Services fit together, when a single host with systemd is enough, and the four ways clusters most often bite.","formats":{"gemtext":"https://engineer.company/glossary/kubernetes/index.gmi","gopher":"https://engineer.company/glossary/kubernetes/gophermap","html":"https://engineer.company/glossary/kubernetes/","json":"https://engineer.company/glossary/kubernetes/index.json","markdown":"https://engineer.company/glossary/kubernetes/index.md","pdf":"https://engineer.company/glossary/kubernetes/index.pdf"},"kind":"page","language":"en","title":"What is Kubernetes?","url":"https://engineer.company/glossary/kubernetes/","version":1}