Try Kubernetes

Imported Docs

Docs imported from other Kubernetes SIGs and repos.

Edit This Page

Kubernetes Enhancement Proposal Process

Metadata

---
kep-number: 1
title: Kubernetes Enhancement Proposal Process
authors:
  - name: Caleb Miles
    github: calebamiles
    slack: calebamiles
  - name: Joe Beda
    github: jbeda
    email: joe@heptio.com
    slack: jbeda
owning-sig: sig-architecture
participating-sigs:
  - `kubernetes-wide`
reviewers:
  - name: TBD
approvers:
  - name: TBD
editor:
  name: TBD
creation-date: 2017-08-22
status: draft

Table of Contents

Summary

A standardized development process for Kubernetes is proposed in order to

This process is supported by a unit of work called a Kubernetes Enhancement Proposal or KEP. A KEP attempts to combine aspects of a

into one file which is created incrementally in collaboration with one or more Special Interest Groups (SIGs).

Motivation

For cross project SIGs such as SIG PM and SIG Release an abstraction beyond a single GitHub Issue or Pull request seems to be required in order to understand and communicate upcoming changes to Kubernetes. In a blog post describing the road to Go 2, Russ Cox explains

that it is difficult but essential to describe the significance of a problem in a way that someone working in a different environment can understand

as a project it is vital to be able to track the chain of custody for a proposed enhancement from conception through implementation. This proposal does not attempt to mandate how SIGs track their work internally, however, it is suggested that SIGs which do not adhere to a process which allows for their hard work to be explained to others in the wider Kubernetes community will see their work wallow in the shadows of obscurity. At the very least survey data suggest that high quality documentation is crucial to project adoption. Documentation can take many forms and it is imperative to ensure that it is easy to produce high quality user or developer focused documentation for a complex project like Kubernetes.

Without a standardized mechanism for describing important enhancements our talented technical writers and product managers struggle to weave a coherent narrative explaining why a particular release is important. Additionally for critical infrastructure such as Kubernetes adopters need a forward looking road map in order to plan their adoption strategy.

The purpose of the KEP process is to reduce the amount of “tribal knowledge” in our community. By moving decisions from a smattering of mailing lists, video calls and hallway conversations into a well tracked artifact this process aims to enhance communication and discoverability.

A KEP is broken into sections which can be merged into source control incrementally in order to support an iterative development process. An important goal of the KEP process is ensuring that the process for submitting the content contained in design proposals is both clear and efficient. The KEP process is intended to create high quality uniform design and implementation documents for SIGs to deliberate.

Reference-level explanation

What type of work should be tracked by a KEP

The definition of what constitutes an “enhancement” is a foundational concern for the Kubernetes project. Roughly any Kubernetes user or operator facing enhancement should follow the KEP process: if an enhancement would be described in either written or verbal communication to anyone besides the KEP author or developer then consider creating a KEP. One concrete example is an enhancement which should be communicated to SIG Release or SIG PM.

Similarly, any technical effort (refactoring, major architectural change) that will impact a large section of the development community should also be communicated widely. The KEP process is suited for this even if it will have zero impact on the typical user or operator.

As the local bodies of governance, SIGs should have broad latitude in describing what constitutes an enhancement which should be tracked through the KEP process. SIGs may find that helpful to enumerate what does not require a KEP rather than what does. SIGs also have the freedom to customize the KEP template according to their SIG specific concerns. For example the KEP template used to track API changes will likely have different subsections than the template for proposing governance changes. However, as changes start impacting other SIGs or the larger developer community outside of a SIG, the KEP process should be used to coordinate and communicate.

KEP Template

The template for a KEP is precisely defined in the template proposal

KEP Metadata

There is a place in each KEP for a YAML document that has standard metadata. This will be used to support tooling around filtering and display. It is also critical to clearly communicate the status of a KEP.

Metadata items:

KEP Workflow

TODO(jbeda) Rationalize this with status entires in the Metadata above.

A KEP is proposed to have the following states

with possible paths through the state space

the happy path is denoted by (j) where an KEP is opened; accepted by a SIG as in their roadmap; fleshed out with a design; started; and finally implemented. As Kubernetes continues to mature, hopefully metrics on the utilization of features will drive decisions on what features to maintain and which to deprecate and so it is possible that a KEP would be retired if its functionality no longer provides sufficient value to the community.

Git and GitHub Implementation

Practically an KEP would be implemented as a pull request to a central repository with the following example structure

├── 0000-kep-template.md
├── CODEOWNERS
├── index.md
├── sig-architecture
│   ├── deferred
│   ├── orphaned
│   └── retired
├── sig-network
│   ├── deferred
│   ├── kube-dns
│   ├── orphaned
│   └── retired
├── sig-node
│   ├── deferred
│   ├── kubelet
│   ├── orphaned
│   └── retired
├── sig-release
│   ├── deferred
│   ├── orphaned
│   └── retired
├── sig-storage
│   ├── deferred
│   ├── orphaned
│   └── retired
├── unsorted-to-be-used-by-newcomers-only
└── wg-resource-management
    ├── deferred
    ├── orphaned
    └── retired

where each SIG or working group is given a top level directory with subprojects maintained by the SIG listed in sub directories. For newcomers to the community an unsorted-to-be-used-by-newcomers-only directory may be used before an KEP can be properly routed to a SIG although hopefully if discussion for a potential KEP begins on the mailing lists proper routing information will be provided to the KEP author. Additionally a top level index of KEPs may be helpful for people looking for a complete list of KEPs. There should be basic CI to ensure that an index.md remains up to date.

Ideally no work would begin within the repositories of the Kubernetes organization before a KEP has been approved by the responsible SIG or working group. While the details of how SIGs organize their work is beyond the scope of this proposal one possibility would be for each charter SIG to create a top level repository within the Kubernetes org where implementation issues managed by that SIG would be filed.

KEP Editor Role

Taking a cue from the Python PEP process, I believe that a group of KEP editors will be required to make this process successful; the job of an KEP editor is likely very similar to the PEP editor responsibilities and will hopefully provide another opportunity for people who do not write code daily to contribute to Kubernetes.

In keeping with the PEP editors which

Read the PEP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don’t seem likely to be accepted. The title should accurately describe the content. Edit the PEP for language (spelling, grammar, sentence structure, etc.), markup (for reST PEPs), code style (examples should match PEP 8 & 7).

KEP editors should generally not pass judgement on a KEP beyond editorial corrections.

Important Metrics

It is proposed that the primary metrics which would signal the success or failure of the KEP process are

Prior Art

The KEP process as proposed was essentially stolen from the Rust RFC process which itself seems to be very similar to the Python PEP process

Graduation Criteria

should hit at least the following milestones

Drawbacks

Any additional process has the potential to engender resentment within the community. There is also a risk that the KEP process as designed will not sufficiently address the scaling challenges we face today. PR review bandwidth is already at a premium and we may find that the KEP process introduces an unreasonable bottleneck on our development velocity.

It certainly can be argued that the lack of a dedicated issue/defect tracker beyond GitHub issues contributes to our challenges in managing a project as large as Kubernetes, however, given that other large organizations, including GitHub itself, make effective use of GitHub issues perhaps the argument is overblown.

The centrality of Git and GitHub within the KEP process also may place too high a barrier to potential contributors, however, given that both Git and GitHub are required to contribute code changes to Kubernetes today perhaps it would be reasonable to invest in providing support to those unfamiliar with this tooling.

Expanding the proposal template beyond the single sentence description currently required in the features issue template may be a heavy burden for non native English speakers and here the role of the KEP editor combined with kindness and empathy will be crucial to making the process successful.

Alternatives

This KEP process is related to

this proposal attempts to place these concerns within a general framework.

Github issues vs. KEPs

The use of GitHub issues when proposing changes does not provide SIGs good facilities for signaling approval or rejection of a proposed change to Kubernetes since anyone can open a GitHub issue at any time. Additionally managing a proposed change across multiple releases is somewhat cumbersome as labels and milestones need to be updated for every release that a change spans. These long lived GitHub issues lead to an ever increasing number of issues open against kubernetes/features which itself has become a management problem.

In addition to the challenge of managing issues over time, searching for text within an issue can be challenging. The flat hierarchy of issues can also make navigation and categorization tricky. While not all community members might not be comfortable using Git directly, it is imperative that as a community we work to educate people on a standard set of tools so they can take their experience to other projects they may decide to work on in the future. While git is a fantastic version control system (VCS), it is not a project management tool nor a cogent way of managing an architectural catalog or backlog; this proposal is limited to motivating the creation of a standardized definition of work in order to facilitate project management. This primitive for describing a unit of work may also allow contributors to create their own personalized view of the state of the project while relying on Git and GitHub for consistency and durable storage.

Unresolved Questions

Mentors

Analytics

Create an Issue Edit this Page