Skip to main content
As Kubernetes adoption grows, contributors continuously suggest improvements. Kubernetes Enhancement Proposals (KEPs) collect, document, discuss, and manage these ideas in a consistent way — and they track progression through release stages (Alpha → Beta → GA). KEPs are the canonical source for motivation, design, test plans, and graduation criteria for significant changes to Kubernetes.
A presentation slide titled "Standard Procedures" on a dark blue background with four rounded white bars. The bars list steps: "Collect and document ideas," "Identify why they are needed," "Discuss and implement ideas," and "Ensure they go through release cycles: Alpha, Beta, and GA."
Why consult a KEP?
  • To learn the rationale behind a change (e.g., why service account tokens moved from automatic Secrets to on-demand tokens).
  • To see design decisions, implementation plans, testing strategies, and graduation criteria.
  • To find the authoritative record of how a change should behave across versions.
If you have an idea for a new feature, an API change, or a security hardening, write a KEP to explain the proposal and invite feedback. The KEP process provides a structured workflow so SIGs (Special Interest Groups) and the community can track development, discuss trade-offs, and ensure consistent implementation. Why KEPs instead of GitHub issues?
  • KEPs provide a structured, reviewable format that SIGs can approve or reject consistently.
  • They support long-lived documentation (goals, non-goals, test plans, graduation criteria) that is hard to maintain in issues.
  • Issues are flat and easily proliferate; KEPs give structure for tracking multi-release work and formalizing SIG intent.
KEPs are not a replacement for issues or pull requests; they complement them. Use a KEP when a proposal needs design, rationale, test plans, and defined graduation criteria beyond a simple issue.

KEP structure and naming

Every KEP follows a naming convention and must be well-documented. Typical KEP sections include: KEPs are organized under SIG directories. SIGs focus on areas like applications, cluster lifecycle, networking, storage, and security. Each SIG maintains a KEP directory where proposals relevant to that SIG are stored and managed.
A dark-themed README/documentation page about certificate signing requests and design details is displayed, with numbered "Story" steps and notes. On the left there's a small inset video or webcam of a man gesturing.
SIG members vote on whether to accept KEPs. Accepted KEPs then progress through implementation and the defined graduation path (alpha → beta → GA) across releases.

Example: Kubernetes Dry-Run KEP

The dry-run feature began as a KEP. It specifies:
  • Which API verbs and endpoints support dry-run.
  • How kubectl should expose the CLI behavior.
  • A test plan and graduation criteria.
Example test files and code paths referenced by the KEP:
A simplified Go function from the KEP that parses the --dry-run flag:
Note: The KEP documents that an empty --dry-run value is deprecated and will require an explicit value in a future release. Pay attention to deprecation warnings and upgrade guidance in the KEP.

Example: Bound Service Account Tokens (KEP 1205)

KEP 1205 introduced bound service account tokens and the TokenRequest API to address several security issues:
  • Non-audience-bound JWTs could be replayed in other contexts.
  • Automatically provisioning service account tokens created many Secrets and increased attack surface.
  • Long-lived tokens were hard to rotate; stolen tokens could provide prolonged access.
The proposal added an on-demand TokenRequest API that issues short-lived, audience-bound tokens. The KEP includes API types, example usage, test plans, and graduation criteria.
A dark-themed GitHub repository page open to a "Kubernetes Dry-run" README with a table of contents. A small inset video of a man speaking appears on the left.
Sample API type excerpts from the TokenRequest KEP:
The TokenRequest API followed a staged rollout: alpha in v1.10, beta in v1.12, and GA in v1.20 (as the KEP specified). Graduation checklist excerpts from the KEP (feature gates, flags, and client requirements):
A dark-themed webpage or document about Kubernetes and JSON Web Tokens with headings like "Summary", "Background", and "Design Details." On the left is a small rounded video overlay showing a bearded man speaking.

KEP lifecycle

KEPs are explicitly tracked through defined lifecycle stages so the community knows the current state and expectations. Each KEP should document the criteria for moving between stages (for example, tests required to move from alpha to beta, or graduation criteria to reach GA).

Resources and further reading

By following KEPs, contributors and users can track the motivation, architectural decisions, test coverage, and version milestones for feature work across the Kubernetes project.

Watch Video