# kubernetes/kubernetes: importing the main module as a library is not supported, and go.mod is generated

> The cluster system itself, in Go, with a vendored dependency tree, per-directory ownership files, and a build that hard-errors on a legacy environment variable. Two of its sharpest edges are written in its own files rather than in its documentation: the unsupported library import, and a go.mod that says do not edit.

**kubernetes/kubernetes** — Kubernetes keeps containerized applications in their declared state across a cluster, handling placement, rollout, scaling, and recovery.

- Repository: https://github.com/kubernetes/kubernetes
- Website: https://kubernetes.io
- Stars: 128,112 · Forks: 45,692
- Language: Go
- License: Apache-2.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/kubernetes-kubernetes

## Importing the main module as a library is ruled out in the readme itself

The getting started section is unusually direct about this. It says that to use Kubernetes code as a library in other applications you should see the list of published components, and that use of the main module or of packages under it as libraries is not supported. The repository is laid out accordingly, with a staging directory holding the individually published components and a vendor directory sitting beside it. Consequence for the reader: an application that reaches into the main module gets no support commitment from the project, and the migration path is a staged component with its own module, which is a different import path and its own release cadence. Anyone who skips that step is relying on an internal package layout that the project states it will not hold stable.

## go.mod says do not edit, and one dependency is a 2016 commit

The module file opens with four comment lines that are the most important text in the repository. It says the file is generated and must not be edited directly, tells you to read the vendor guide for the architecture special interest group, and names the two scripts that are allowed to change it: one to pin dependency versions and one to update the module files and the vendor directory.

```
hack/pin-dependency.sh
hack/update-vendor.sh
```

The module is k8s.io/kubernetes with a Go 1.27.0 directive and a debug directive defaulting to the same release, and the require block pins many dependencies to commit hashes rather than to tags, including one from 2016 and others from 2019 and 2025. Consequence for the reader: a dependency bump is a scripted operation that rewrites the module file and the vendor tree together, so a security update is a pull request against the project's tooling rather than an edit you can make in your own fork.

## The Makefile refuses a legacy variable instead of preferring it

Build strictness is deliberate and it is written down. The shell is overridden to bash with errexit, pipefail, and nounset, the bash startup file is pointed at a script inside the hack directory, built-in rules are switched off, undefined variables produce a warning, and the suffix rule list is cleared. Optional user inputs such as the test selector and the branch variable are declared so that the strict undefined variable check does not fire on them. The output directory defaults to a single underscore-prefixed name with a bin subdirectory. There is also a deprecation path: if the old flag variable is set the build prints that it is deprecated and should be replaced by the newer one.

Consequence for the reader: an old script that sets both variables stops the build with an error instead of quietly using one of them, which is the right failure and an abrupt one. Recipes are also silent by default, so a failing step shows no command until you switch the Makefile's own debug flag on.

## Two documented build routes, and the readme does not compare them

There are exactly two ways given, and they differ in both the clone and the command. With a working Go environment you clone the repository, change into the directory, and run make. With a working Docker environment you clone the same repository, change into the directory, and run a target called quick-release. The full story is deferred to the developer documentation, and the readme does not say what the quick release build skips relative to the full one, nor how long either takes.

Consequence for the reader: two contributors can be on the same commit and holding different artifacts, and a problem that reproduces for one of them may not reproduce for the other, because the readme gives no way to tell the two builds apart from the instructions alone. Anything beyond these two paths, such as cross-compiling or building a single component, is documented somewhere this file does not point to.

## Ownership and layering are enforced by files, not by review comments

The root of the tree is mostly policy. There is an owners file and an owners alias file, which is how a directory declares who reviews it and which groups count as an approver, a generated files list, and an import restrictions file that mechanically limits which packages may import which. Alongside them sit a support file, a security contacts file, a code of conduct, a contributing guide, an agent instructions file, and both a changelog file and a changelog directory. Consequence for the reader: the architecture is checkable without reading anybody's comments, so a change that crosses a forbidden dependency fails in a script rather than in review, and an unanswered pull request is a matter of who owns that directory rather than of who noticed it.

## A single module, a workspace file, and a vendor tree that is what actually compiles

The build inputs are unusual and worth understanding before you touch them. The root module is one module, but there is also a workspace file and its checksum beside it, which lets a local checkout resolve several modules at once. Alongside sit a staging directory whose contents are the published components, a third party directory, a vendor directory, and a plugin directory, plus the conventional source directories for the api, the package tree, the command entry points, build tooling, cluster tooling, tests, hack scripts, and documentation. Consequence for the reader: a workspace file in your checkout can pull modules into the build that the vendor tree does not contain, which is precisely the situation the generated module file and its pinning script exist to prevent, and the difference between those two states is invisible until the build behaves differently than the committed dependency list suggests.

## Release plans and backlogs live in a different repository

The readme is a signpost, and the destinations matter. Using the system is a documentation question, answered on the documentation site, with a free course on scalable microservices offered alongside. Building it points at a separate community repository. Support is described as a path rather than a promise: start with the troubleshooting guide, work through the process outlined there, and if questions remain reach the project through its communication page. Community meetings are listed in a single calendar. Governance is a document in the community repository, with a separate steering repository for the committee that oversees it. The roadmap section says the enhancements repository carries information about releases, feature tracking, and backlogs.

Consequence for the reader: nothing in this repository tells you what is planned for the next version, so a contributor cannot tell from here whether a feature is proposed, accepted, or abandoned, and the release list shows how fast the line moves, with an alpha for 1.38.0 dated 2026-09-29 next to patch releases for 1.37.1 and 1.36.5.

## Conclusion

Use this repository when you are changing the system itself, reviewing a change to it, or vendoring one of its staged components, because that is the only use its own readme supports. Do not import the main module into your application, since the readme rules that out explicitly and points you at the published component list instead. Before you build or patch, check four things: that your Go toolchain matches the 1.27 line the module declares, because the build is strict about its environment; that you go through the two documented scripts when a dependency version has to change, since hand edits to go.mod are overwritten and the vendor tree is what compiles; that you know which of the two build routes you are on, because the readme offers a full make with a Go environment and a quick release build with a Docker environment without explaining the difference; and that your change fits the layering, because the tree carries an import restrictions file that enforces it mechanically.

## FAQ

### What exactly is Kubernetes used for?

The readme calls it an open source system for managing containerized applications across multiple hosts, providing the mechanisms for their deployment, maintenance, and scaling. The project description puts it as keeping applications in their declared state, handling placement, rollout, scaling, and recovery.

### Is Kubernetes the same as Docker?

No. The readme presents Kubernetes as the system that manages containerized applications across multiple hosts, and treats Docker only as one of two environments in which you can build the source, the other being a Go environment. It also credits its design to a decade and a half of Google's experience with a system called Borg.

### how to install kubernetes

For building the software, the readme gives two routes: with a Go environment, clone the repository, change into the directory and run make, and with a Docker environment, clone it and run make quick-release. For using Kubernetes, it points at the documentation on kubernetes.io rather than giving an install command.

### Can I learn Kubernetes in 2 days?

The readme gives no time estimate. It points at the documentation on kubernetes.io, offers a free course on scalable microservices with Kubernetes, and keeps all community meetings in a single calendar. The two build routes it documents are for developers, not for learners.

### how to use kubernetes locally

The readme does not describe a local cluster. It sends usage questions to kubernetes.io, and the only local activity it describes is building the source from a clone, either with a Go environment or with a Docker environment using the quick release target.

## Sources

- [Official documentation](https://kubernetes.io)
- [Official README](https://github.com/kubernetes/kubernetes#readme)
- [Project repository](https://github.com/kubernetes/kubernetes)
- [Release notes](https://github.com/kubernetes/kubernetes/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kubernetes-kubernetes