Title¶
+This is the title of the KEP. +Keep it simple and descriptive. +A good title can help communicate what the KEP is and should be considered as part of any review.
+The title should be lowercased and spaces/punctuation should be replaced with -.
To get started with this template:
+-
+
- Make a copy of this template.
+ Create a copy of this template and name it
YYYYMMDD-my-title.md, whereYYYYMMDDis the date the KEP was first drafted.
+ - Fill out the "overview" sections. + This includes the Summary and Motivation sections. + These should be easy if you've preflighted the idea of the KEP in an issue. +
- Create a PR. + Assign it to folks that are sponsoring this process. +
- Create an issue + When filing an enhancement tracking issue, please ensure to complete all fields in the template. +
- Merge early.
+ Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly.
+ The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs.
+ View anything marked as a
provisionalas a working document and subject to change. + Aim for single topic PRs to keep discussions focused. + If you disagree with what is already in a document, open a new PR with suggested changes.
+
The canonical place for the latest set of instructions (and the likely source of this file) is here.
+The Metadata section above is intended to support the creation of tooling around the KEP process.
+This will be a YAML section that is fenced as a code block.
+See the KEP process for details on each of these items.
Table of Contents¶
+A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template.
+Ensure the TOC is wrapped with <!-- toc --&rt;<!-- /toc --&rt; tags, and then generate with hack/update-toc.sh.
-
+
- Summary +
- Motivation +
- Goals +
- Non-Goals +
- Proposal +
- User Stories [optional] + +
- Implementation Details/Notes/Constraints [optional] +
- Risks and Mitigations +
- Design Details +
- Test Plan + +
- Implementation History +
- Drawbacks [optional] +
- Alternatives [optional] + +
Summary¶
+The Summary section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap.
+It should be possible to collect this information before implementation begins in order to avoid requiring implementors to split their attention between writing release notes and implementing the feature itself.
A good summary is probably at least a paragraph in length.
+Motivation¶
+This section is for explicitly listing the motivation, goals and non-goals of this KEP. +Describe why the change is important and the benefits to users. +The motivation section can optionally provide links to experience reports to demonstrate the interest in a KEP within the wider Kubernetes community.
+Goals¶
+List the specific goals of the KEP. +How will we know that this has succeeded?
+Non-Goals¶
+What is out of scope for this KEP? +Listing non-goals helps to focus discussion and make progress.
+Proposal¶
+This is where we get down to the nitty gritty of what the proposal actually is.
+User Stories [optional]¶
+Detail the things that people will be able to do if this KEP is implemented. +Include as much detail as possible so that people can understand the "how" of the system. +The goal here is to make this feel real for users without getting bogged down.
+Story 1¶
+Story 2¶
+Implementation Details/Notes/Constraints [optional]¶
+What are the caveats to the implementation? +What are some important details that didn't come across above. +Go in to as much detail as necessary here. +This might be a good place to talk about core concepts and how they releate.
+Risks and Mitigations¶
+What are the risks of this proposal and how do we mitigate. +Think broadly. +For example, consider both security and how this will impact the larger kubernetes ecosystem.
+How will security be reviewed and by whom? +How will UX be reviewed and by whom?
+Consider including folks that also work outside project.
+Design Details¶
+Test Plan¶
+Note: Section not required until targeted at a release.
+Consider the following in developing a test plan for this enhancement:
+-
+
- Will there be e2e and integration tests, in addition to unit tests? +
- How will it be tested in isolation vs with other components? +
No need to outline all of the test cases, just the general strategy. +Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out.
+All code is expected to have adequate tests (eventually with coverage expectations). +Please adhere to the Kubernetes testing guidelines when drafting this test plan.
+Removing a deprecated flag¶
+-
+
- Announce deprecation and support policy of the existing flag +
- Two versions passed since introducing the functionality which deprecates the flag (to address version skew) +
- Address feedback on usage/changed behavior, provided on GitHub issues +
- Deprecate the flag +
Implementation History¶
+Major milestones in the life cycle of a KEP should be tracked in Implementation History.
+Major milestones might include
-
+
- the
SummaryandMotivationsections being merged signaling acceptance
+ - the
Proposalsection being merged signaling agreement on a proposed design
+ - the date implementation started +
- the first Kubernetes release where an initial version of the KEP was available +
- the version of Kubernetes where the KEP graduated to general availability +
- when the KEP was retired or superseded +
Drawbacks [optional]¶
+Why should this KEP not be implemented.
+Alternatives [optional]¶
+Similar to the Drawbacks section the Alternatives section is used to highlight and record other possible approaches to delivering the value proposed by a KEP.