Kubernetes: what the upstream repository actually gives you

The problem Kubernetes solves, and who is actually supposed to run it

The README describes Kubernetes as an open source system for managing containerized applications across multiple hosts, providing mechanisms for deployment, maintenance and scaling. Read that literally. The unit of value is the cluster, not the container. If you have one container and one machine, Kubernetes adds a scheduler, an API server, an etcd datastore and a reconciliation loop to solve a problem you do not have. The project's own history is the giveaway: the README says it builds on a decade and a half of experience at Google running production workloads at scale using a system called Borg. That is the scale it was designed against. The audience is platform teams who need to place workloads on many machines, roll them out gradually, and recover when a node disappears. The README points ordinary users at kubernetes.io rather than at the repository, which is a strong signal about who this repo is for. The repository is the upstream source of the control plane; the documentation site is where users are meant to start.

How the declared state actually gets enforced

Kubernetes is a control loop system. You write a desired state into the API server, and controllers compare that state with what is observed and act on the difference. The README frames this as keeping containerized applications in their declared state, handling placement, rollout, scaling and recovery. Placement is a scheduling decision made when a pod has no node assigned. Rollout is a controller replacing instances gradually rather than all at once. Scaling is the same loop reacting to a changed replica count. Recovery is the loop noticing that an observed instance is gone and creating a replacement. None of these are one-off commands; they are continuous reconciliations. The repository layout reflects the split. The api/ directory holds the API definitions, cmd/ holds the binaries, pkg/ holds the controller and scheduler logic, plugin/ holds the extension points, and staging/ holds the components published for reuse elsewhere. The go.mod file names the module k8s.io/kubernetes. That detail matters because the README says use of the k8s.io/kubernetes module or its subpackages as libraries is not supported, and points to the staging README for the list of published components instead.

Installing Kubernetes: build the upstream tree, or use a distribution

The README does not give end-user install instructions at all. It says to start using K8s, see the documentation on kubernetes.io. What it does give is two ways to build the repository from source. The first assumes a working Go environment and runs the top-level Makefile.

git clone https://github.com/kubernetes/kubernetes
cd kubernetes
make

The second assumes a working Docker environment and produces release artifacts instead of a plain build.

git clone https://github.com/kubernetes/kubernetes
cd kubernetes
make quick-release

Both paths are for people working on Kubernetes itself, not for people who want a cluster. The Makefile is explicit that it is old-skool build tooling and warns on undefined variables, so it is not a forgiving interface. For a first real cluster, follow the README's own direction to kubernetes.io and pick an installer there. Once you have a cluster, the first genuinely useful object is a Deployment, because it exercises placement, rollout and recovery in one file. You apply it with kubectl, watch the rollout finish, and then delete a pod to watch the controller replace it. That replacement is the whole product in one action.

Where upstream Kubernetes is the wrong tool

The repository does not ship a supported way to run a production cluster. There is no installer in the tree that the README endorses, no upgrade tool, and no backup procedure for the datastore. The README's support section sends you to a troubleshooting guide and then to the community communication channels, which tells you the maintenance model is community support, not a vendor hotline. The library restriction is another hard boundary. If you were considering importing the API machinery directly into your own Go service, the README rules that out: use of the k8s.io/kubernetes module or its subpackages as libraries is not supported. Build tooling is a third boundary. The Makefile header states that some environments do not link sh to bash, which is why it sets SHELL to bash with errexit, pipefail and nounset. That is a deliberate strictness that will break casual scripts. Finally, the version cadence is fast. Three releases appear in the recent list alone: v1.37.0, v1.36.4 and v1.35.8. If your team cannot absorb a minor upgrade roughly every few months, the upstream project is not going to slow down for you.

Kubernetes compared with Docker and with managed engines

The most common comparison is Kubernetes versus Docker, and the repository makes the distinction easy to state. Docker builds and runs containers on a host. Kubernetes decides which host runs them, keeps the declared number running, and replaces the ones that stop. They operate at different layers, which is why the README can describe Kubernetes as managing containerized applications across multiple hosts without contradicting anything Docker does. The second comparison is upstream Kubernetes versus a managed engine. A managed engine takes the control plane off your hands, including the datastore you would otherwise have to run and back up. The upstream repository gives you the source, the build targets and the API definitions, and leaves operational responsibility with you. That is the actual trade: control and portability on one side, and the obligation to run etcd, plan upgrades and handle certificate rotation on the other. The README does not pick a side, but the fact that it routes new users to kubernetes.io rather than to `make` is a hint about which path most people should take.

Maintenance cost, release cadence and the licence

The last push to the default branch was on 2026-08-26, the same day v1.37.0 was released, so the tree is moving. The release list shows patch releases on separate branches: v1.36.4 and v1.35.8 both dated 2026-08-20. That pattern means you are expected to track a minor version and take patches within it, not to pin a single tag forever. Upgrading is a project activity, not a file swap: the README does not document rollback, and the repository contains no upgrade tool, so the procedure lives in the external documentation. Running the control plane yourself also means running its datastore and its certificates, and neither appears in the README's support section. The licence is Apache-2.0, and the LICENSE file sits at the repository root alongside a LICENSES/ directory. Apache-2.0 permits commercial use and modification and includes an explicit patent grant. If you vendor or redistribute the code, the usual obligations around licence and notice files apply. That is a description of the licence text, not legal advice; check it against your own distribution model.

Editorial conclusion

Adopt Kubernetes when you need declarative placement, rollout and recovery across multiple hosts and you are prepared to run the control plane or pay someone to run it. Do not adopt it for a single container on one machine, or if a plain process manager already meets the requirement. Before committing, verify three things: which Kubernetes version your chosen installer ships, whether a supported upgrade path exists from it to the next minor release, and who is responsible for etcd backups, because the README says nothing about any of these.

Frequently asked questions

Official sources

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