Kubernetes: What the Declarative Container Orchestrator Actually Does and Where It Stops

The Problem Kubernetes Solves

Kubernetes manages containerized applications across multiple hosts. The core problem is keeping those applications in a declared state. If a container crashes, the system restarts it. If traffic increases, it can scale out. If a node fails, workloads move. This is not a tool for running one container on one machine. It is a control plane for a fleet of machines, and it assumes you have that fleet. The intended user is an organization running production workloads at scale, which is why the README traces its lineage to Google's Borg system. For a single developer with a laptop and a few containers, the overhead is likely not justified.

The Declarative Mechanism at Its Core

The repository description says Kubernetes keeps containerized applications in their declared state, but the README does not spell out the mechanism. The documentation on kubernetes.io fills in the model: you submit a desired state, typically as YAML, and the control plane works to match reality to that state. The actual data flow involves an API server, a scheduler that decides placement, and controllers that reconcile the cluster. The README gives no internals, but the key point is that you do not issue commands to start or stop containers. You declare what should run, and the system converges. That is a fundamental shift from imperative tools like shell scripts or even Docker Compose. It means the system is always trying to reach a target, and it will fight manual changes that deviate from that target.

Building from Source: Two Paths

The README offers two ways to build Kubernetes from source. The first assumes a working Go environment. You clone the repository, enter the directory, and run make. That builds everything from the Go source. The second path assumes a Docker environment. You run make quick-release, which builds release artifacts inside containers. Both commands are simple, but they hide a large dependency tree. The README warns that the k8s.io/kubernetes module is not supported as a library for other applications, so you should expect to run this as a standalone system, not to import its packages into your own code. For most users, the recommended route is not building from source at all; the README points to kubernetes.io for getting started, which in practice means downloading prebuilt binaries or using a managed distribution.

The Governance and Community Layer

Kubernetes is hosted by the Cloud Native Computing Foundation, which is a neutral home for open source infrastructure. The README lists governance documents, a community repository, and a steering committee. This matters for adoption because it means the project has a formal decision-making process and a public roadmap in the Kubernetes Enhancements repository. You can see what features are planned and which are still experimental. The release cadence is visible in the recent tags: v1.38.0-alpha.3, v1.36.6, and v1.34.13 all appeared on 2026-10-28. That indicates active maintenance and a steady stream of patch releases. For an engineer evaluating risk, this is a positive signal, but it also means you must track releases and plan upgrades.

A Genuine Limitation: It Is Not a Library

The README is explicit: using the k8s.io/kubernetes module or its packages as libraries is not supported. That is a hard boundary. If you want to embed Kubernetes logic into your own application, you cannot. The project publishes components in a staging directory for library use, but the main repository is a monolith for the system itself. This is a real limitation for teams that want to build custom orchestration on top of Kubernetes primitives. You must run the whole system or use the published components, which have their own compatibility rules. Also, the system assumes a cluster. Running it on a single machine is possible with minikube or kind, but those are not mentioned in the README. The documented path is for multiple hosts, and the complexity of networking, storage, and security grows with the cluster size.

The Alternative: Imperative Container Management

The main alternative to Kubernetes is a simpler, imperative container manager like Docker Compose or a plain container runtime. Docker Compose lets you define services in a YAML file and start them with one command, but it does not reconcile state. If a container dies, Compose does not restart it unless you configure a restart policy, and it has no built-in cluster awareness. The difference is philosophical: Kubernetes is a control loop that continuously enforces the desired state, while Compose is a one-shot deployment tool. For a small number of services on a single host, Compose is easier and faster to operate. For a multi-node cluster with rolling updates and self-healing, Kubernetes is designed to provide those mechanisms out of the box. The trade-off is complexity: Kubernetes requires you to learn concepts like pods, services, and controllers, and to operate a control plane.

Maintenance and Upgrade Cost

The README does not give a maintenance guide, but the release tags show the cost. The recent tags show a pre-release, v1.38.0-alpha.3, alongside patch releases for older branches (v1.36.6 and v1.34.13), so you will be tracking several versions at once. Patches arrive frequently, and you will need to plan upgrades. The Enhancements repository tracks features, but it also implies that APIs change across versions. Each upgrade can require updating manifests, because deprecated APIs are removed over time. The governance structure and the CNCF hosting suggest long-term stability, but they do not reduce the operational burden. You are adopting a system that demands ongoing attention, not a set-and-forget tool.

Editorial conclusion

Adopt Kubernetes if you run multiple containerized services that need automated placement, rollout, scaling, and recovery across a cluster, and you can commit to learning its operational model. Do not adopt it for a single host, a small set of static containers, or environments where you cannot invest in cluster administration. Before adopting, verify your container runtime compatibility, your networking plugin choices, and the upgrade path from your current version, because the project's own documentation emphasizes that the k8s.io/kubernetes module is not supported as a library, so you must run it as a system, not embed it.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes