kubernetes/enhancements: the tracking repo behind every Kubernetes KEP

What kubernetes/enhancements is, and the problem it exists to solve

Kubernetes changes through features that outlive a single release. The README's own framing is that an enhancement usually takes multiple releases to complete and may sit as a backlog item before work begins. A tracking issue in this repository is the umbrella for that work, and the KEP documents under keps/ carry the design. The problem being solved is coordination: the README states that once users adopt an enhancement they expect to use it for an extended period, and that the project therefore holds new enhancements to a high standard of conceptual integrity with consistency across the system, thorough testing and complete documentation. As the project grows, no single person can check whether all of those requirements are met, so the tracking issue becomes a checklist with different approvers for different aspects, which the README says ensures nothing is forgotten across the development lifetime of an enhancement.

The audience is narrow. It is Kubernetes contributors and SIG members, plus release-team people who need to know which features are landing in a milestone. The README's heuristics for what counts are worth reading before filing anything: an enhancement is something a blog post would be written about after release, something requiring multiple parties or SIGs, something graduating from alpha to beta to GA, or something that introduces API changes or would take around ten person-weeks. Equally useful is the exclusion list. A change implemented with a CustomResourceDefinition is unlikely to be an enhancement, and so are flaky-test fixes, refactors, and performance improvements visible to users only as faster API operations or control loops. Adding error messages or events is excluded too. That boundary is what keeps the repository from becoming a second issue tracker for the whole project.

The repository layout: KEPs, Go tooling and verification scripts

The top-level entries show a repository that is part documentation, part Go program. There is keps/ for the enhancement proposals, docs/ for supporting material, and api/, cmd/, internal/ and pkg/ for the Go code that reads and checks them. The module is declared in go.mod as k8s.io/enhancements, and the dependency list is telling: gopkg.in/yaml.v3 for parsing, github.com/go-playground/validator/v10 for metadata validation, github.com/google/go-github/v89 for talking to GitHub, github.com/spf13/cobra for the command line, and k8s.io/release. The presence of go-github matters. It means the tooling can pull issue state from GitHub rather than relying on a human to keep a table current.

The Makefile exposes the verification surface directly. Targets include update-toc, verify-toc, verify-metadata, verify-boilerplate, verify-build, verify-golangci-lint, verify-go-mod and verify-shellcheck, with a verify target that runs the whole set through hack/verify.sh. There is also add-verify-hook, which runs git config --local core.hooksPath to point at .githooks, so the same checks can run before a commit. The KEP metadata check is the one that matters most for contributors: verify-metadata is described as verifying that KEP metadata is valid yaml, which is why a malformed header in a KEP file fails CI rather than merging quietly.

Labels are the other half of the mechanism. The README documents sig/foo as denoting the owning SIG, set with the comment /sig foo on a separate line, and kind/feature as marking an issue as an enhancement, set with /kind feature. Anyone may apply them. That convention is what lets the tracking boards filter by SIG and by kind without a maintainer hand-editing a list.

Filing an enhancement: the prerequisites the README sets

The README is unusually explicit about sequencing, and the order is not negotiable. Before creating an issue you should have circulated the idea through community meetings, SIG meetings, SIG mailing lists, or an issue in github.com/kubernetes/kubernetes. You may optionally have prototyped in your own fork. You should have identified people who agree to work on the enhancement, and you should be prepared for the roughly nine months to a year the README says it takes to progress to Stable. Finally, you are expected to be ready to act as project manager for the enhancement.

That last point is the part contributors underestimate. The tracking issue is not a wish list entry that someone else picks up. It is a commitment to shepherd a document through multiple stages, with the README noting that many enhancements take several releases to move through Alpha, Beta and Stable. The README also draws a line around issue comments: use them for review requests, process clarifications, status updates and links to issues in other repos, but do not use them to debate a detail of design, code or docs. That belongs on a linked issue or pull request. In practice this keeps the umbrella issue readable as a status record rather than a discussion thread.

Installing the tooling and validating KEP metadata

There is no installable product here. The README points to the repository itself, and the work is done by cloning it and running the Make targets, which shell out to scripts under hack/. You need a Go toolchain matching the module, which go.mod declares as go 1.26.0, and a git checkout because the Makefile resolves REPO_ROOT with git rev-parse --show-toplevel.

Clone the repository and move into it. Because REPO_ROOT comes from git, running make from a directory that is not inside a git work tree will fail before any check starts.

Where this repository is the wrong tool

The most common misreading is that kubernetes/enhancements is a place to request features. It is not. The README's exclusion list rules out changes implemented with a CustomResourceDefinition, flaky test fixes, refactors, performance work that only shows up as faster API operations or control loops, and added error messages or events. If your change falls into one of those categories, an issue here will be closed or redirected, and the time spent writing it up is wasted. The correct path is the repository that owns the code.

The second limitation is latency. The README says an enhancement may take roughly nine months to a year to reach Stable, and that it may take multiple releases. Anyone treating this repository as a way to get a feature shipped quickly has misjudged what it is for. The tracking issue is a coordination record, not a fast lane.

The third is that there is no consumer artifact. go.mod declares the module as k8s.io/enhancements, but there are no retrieved releases, no versioned package to import, and no binary distributed for general use. The Go code exists to validate and report on KEP metadata for the project's own CI. If you arrived looking for a library, a CLI you can install from a package manager, or a server to deploy, this repository does not contain one. The README also leaves gaps: the enhancement tracking spreadsheet section states its procedure as TBA, and the spreadsheet approach itself was superseded by the tracking boards after the 1.26 release, so the older documentation is historical rather than operational.

How this differs from a conventional RFC or design-doc process

The nearest comparison is an RFC repository in another large project, where proposals are markdown files reviewed and merged, and that is the end of the lifecycle. kubernetes/enhancements keeps the proposal but adds a live tracking issue that persists across releases, and the README's reason is explicit: the development of an enhancement often spans Alpha, Beta and Stable, and the tracking issue provides a checklist with different approvers for different aspects. A merged RFC has no equivalent graduation state.

The other difference is that the metadata is machine-checked. An RFC repository typically relies on reviewers noticing a malformed header. Here, verify-metadata and verify-toc run in CI through hack/verify.sh, and the dependency on go-playground/validator and yaml.v3 exists precisely to enforce structure. That shifts some review burden from humans to scripts, at the cost of contributors needing a working Go environment just to check their own document.

The third difference is the label-driven view. The README documents sig/foo and kind/feature applied through comments, and the tracking boards linked per release, from the 1.26 milestone through the 1.38 milestone, are generated views over those labels rather than hand-maintained tables. The archived spreadsheet links under docs/ are the earlier version of the same idea, and the README points readers there for pre-1.26 history.

Maintenance, licensing and the cost of following a KEP

The repository is not archived, and the last push was on 2026-09-22. Activity here tracks the Kubernetes release cycle rather than a product roadmap, so the useful question is not whether commits land but whether the current cycle is documented. The README links the 1.38 release information under kubernetes/sig-release, and lists tracking board links from the 1.26 milestone through 1.38, which is the practical signal that the repository is in step with the release it serves.

Upgrade cost for a contributor is close to zero in the usual sense, because there is nothing to upgrade. What you maintain is a KEP document and its metadata. The cost shows up when the tooling moves: go.mod pins go 1.26.0 and a set of dependencies including k8s.io/release and k8s.io/test-infra, so a contributor's local Go version has to keep pace with the module or the Make targets will not run. The Makefile's verify-go-mod target exists to catch drift in the module files themselves.

On licensing, the repository carries Apache-2.0, and the Makefile's boilerplate header block reproduces the standard Apache License, Version 2.0 notice with the http://www.apache.org/licenses/LICENSE-2.0 URL and the note that the file is distributed on an AS IS BASIS without warranties or conditions of any kind. KEP text and the Go tooling sit under the same repository licence. Nothing here is legal advice; if you intend to reuse KEP text in your own documentation, read the LICENSE file and the boilerplate notice in the files you copy rather than assuming the header is decorative.

Editorial conclusion

Adopt this repo as a contributor or release-team member working inside the Kubernetes project, not as an application dependency: there is no published release artifact, no versioned module for consumers, and nothing to deploy. If you are outside the project, the useful thing to read is keps/, which records the design intent and graduation criteria behind features you already run. Before you open an issue, confirm you have consensus in at least one Kubernetes SIG, because the README states an enhancement may be filed only once that consensus exists, and confirm that your change is not something the README explicitly excludes, such as a CustomResourceDefinition or a refactor.

Frequently asked questions

Official sources

1. Issues
2. kubernetes/enhancements on GitHub
3. License: Apache-2.0
4. README