Revise KEP template #703
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,5 @@ | ||
| --- | ||
| title: KEP Template | ||
| authors: | ||
| - "@janedoe" | ||
| owning-sig: sig-xxx | ||
|
|
@@ -16,14 +15,14 @@ approvers: | |
| editor: TBD | ||
| creation-date: yyyy-mm-dd | ||
| last-updated: yyyy-mm-dd | ||
| status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced | ||
| see-also: | ||
| - "/keps/sig-aaa/20190101-we-heard-you-like-keps.md" | ||
| - "/keps/sig-bbb/20190102-everyone-gets-a-kep.md" | ||
| replaces: | ||
| - "/keps/sig-ccc/20181231-replaced-kep.md" | ||
| superseded-by: | ||
| - "/keps/sig-xxx/20190104-superceding-kep.md" | ||
| --- | ||
|
|
||
| # Title | ||
|
|
@@ -39,12 +38,14 @@ To get started with this template: | |
| Make sure that the problem space is something the SIG is interested in taking up. | ||
| KEPs should not be checked in without a sponsoring SIG. | ||
| 1. **Make a copy of this template.** | ||
| Copy this template into the owning SIG's directory (or KEP root directory, as appropriate) and name it `YYYYMMDD-my-title.md`, where `YYYYMMDD` is the date the KEP was first drafted. | ||
| 1. **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 with the appropriate SIG. | ||
| 1. **Create a PR.** | ||
| Assign it to folks in the SIG that are sponsoring this process. | ||
| 1. **Create an issue in kubernetes/enhancements, if the enhancement will be targeting changes to kubernetes/kubernetes** | ||
| When filing an enhancement tracking issue, please ensure to complete all fields in the template. | ||
| 1. **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. | ||
|
|
@@ -63,28 +64,65 @@ See the KEP process for details on each of these items. | |
| 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. | ||
| [Tools for generating][] a table of contents from markdown are available. | ||
|
|
||
| - [Title](#title) | ||
| - [Table of Contents](#table-of-contents) | ||
| - [Release Signoff Checklist](#release-signoff-checklist) | ||
| - [Summary](#summary) | ||
| - [Motivation](#motivation) | ||
| - [Goals](#goals) | ||
| - [Non-Goals](#non-goals) | ||
| - [Proposal](#proposal) | ||
| - [User Stories [optional]](#user-stories-optional) | ||
| - [Story 1](#story-1) | ||
| - [Story 2](#story-2) | ||
| - [Implementation Details/Notes/Constraints [optional]](#implementation-detailsnotesconstraints-optional) | ||
| - [Risks and Mitigations](#risks-and-mitigations) | ||
| - [Design Details](#design-details) | ||
| - [Test Plan](#test-plan) | ||
| - [Graduation Criteria](#graduation-criteria) | ||
| - [Examples](#examples) | ||
| - [Alpha -> Beta Graduation](#alpha---beta-graduation) | ||
| - [Beta -> GA Graduation](#beta---ga-graduation) | ||
| - [Removing a deprecated flag](#removing-a-deprecated-flag) | ||
| - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy) | ||
| - [Version Skew Strategy](#version-skew-strategy) | ||
| - [Implementation History](#implementation-history) | ||
| - [Drawbacks [optional]](#drawbacks-optional) | ||
| - [Alternatives [optional]](#alternatives-optional) | ||
| - [Infrastructure Needed [optional]](#infrastructure-needed-optional) | ||
|
|
||
| [Tools for generating]: https://github.com/ekalinin/github-markdown-toc | ||
|
|
||
| ## Release Signoff Checklist | ||
|
|
||
| **ACTION REQUIRED:** In order to merge code into a release, there must be an issue in [kubernetes/enhancements] referencing this KEP and targeting a release milestone **before [Enhancement Freeze](https://github.com/kubernetes/sig-release/tree/master/releases) | ||
| of the targeted release**. | ||
|
|
||
| For enhancements that make changes to code or processes/procedures in core Kubernetes i.e., [kubernetes/kubernetes], we require the following Release Signoff checklist to be completed. | ||
|
|
||
| Check these off as they are completed for the Release Team to track. These checklist items _must_ be updated for the enhancement to be released. | ||
justaugustus marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| - [ ] kubernetes/enhancements issue in release milestone, which links to KEP (this should be a link to the KEP location in kubernetes/enhancements, not the initial KEP PR) | ||
|
There was a problem hiding this comment. Honestly from the perspective of people wanting to file KEPs this seems like obscure busywork. Why don't we make a bot to file these issues? There was a problem hiding this comment. I think that's something we can start to look at, once we've stabilized more of the process. |
||
| - [ ] KEP approvers have set the KEP status to `implementable` | ||
|
There was a problem hiding this comment. Questions have been raised here over adding iterative features. If a KEP is marked as 'implementable' and then a feature is added, it inherits the implementable status. Would be nice to have some structure around these changes if it makes sense to do in this revision. There was a problem hiding this comment. I'd rework this to say -- "Any PRs to move a KEP to WDYT? There was a problem hiding this comment. May not make sense to put that in this section fo the template/instructions but we can put it someplace. There was a problem hiding this comment. I still don't really understand why the "approvers" and "reviewers" section of KEPs exist. If it's about people who are supposed to approve/review the KEP itself, don't we have owners files for that? KEPs are in separate directories now. If it's about people who are going to help approve and/or review the code changes (e.g., demonstrating that you've lined up sufficient bandwidth in the schedules of busy folks to actually get the changes made), it's probably named wrong. Actually IMO it's totally ambiguous right now and that section of the KEP could either be renamed or have a comment to make it clear what it means. There was a problem hiding this comment. Part of the goal is disambiguate the KEP itself from the place it lives / things that operate over it. OWNERS leads me to looking up the OWNERS_ALIASES, neither or which are guaranteed to stay the same over time. If I needed to reach out to someone to discuss the KEP, I would need more context. We can do better on making that more clear in the documentation. I've added an AI in #822. There was a problem hiding this comment. My intent was that the leads of the area (e.g., SIG TLs, subproject owners) would assign specific reviewers and approvers for each KEP, so that there are specific people that can review/approve, shepherd, serve as points of contact, etc. Always assigning SIG TLs to these roles is unrealistic due to time constraints, and if it's just everyone in a SIG, then it's easy to fall through the cracks or to get conflicting guidance. Unclear OARP is one of our biggest problems. |
||
| - [ ] Design details are appropriately documented | ||
|
There was a problem hiding this comment. Are KEPs design docs or requirements docs? People have said "both" but I'm not convinced that's a good answer. There is no reason to suppose that the set of people who know what good goals are has a lot of overlap with the set of people who will be good at charting a path to achieving the goals. I personally feel that it's reasonable to hold a vote on goals (i.e. requirements), as long as they're appropriately phrased (e.g., "is problem X an important problem for the project to solve" NOT "is changing the frobber API to interoperate with the thingy a good idea"). It is not a good idea to vote on solutions (designs), that should be handled by the right technical folks. (I think any formal specification of this distinction can be gamed, unfortunately.) There was a problem hiding this comment. I don't have a great answer for this at the moment. I think that "both" is the right answer currently, simply because all SIGs have slightly different operating mechanisms, each KEP isn't strictly technical content (it may be process-related, like this one), etc. Authors and editors have the obvious roles. Approvers then act as the rubber stamp to signal SIG acceptance. I've added an AI in #822 to firm up docs on this. There was a problem hiding this comment. Requirements vs design: They must cover both. Whether requirements should be agreed upon before discussing the design is more of a process question, but it also depends on the complexity of the change. Simple changes could address both simultaneously. |
||
| - [ ] Test plan is in place, giving consideration to SIG Architecture and SIG Testing input | ||
| - [ ] Graduation criteria is in place | ||
| - [ ] "Implementation History" section is up-to-date for milestone | ||
| - [ ] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io] | ||
| - [ ] Supporting documentation e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes | ||
justaugustus marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| **Note:** Any PRs to move a KEP to `implementable` or significant changes once it is marked `implementable` should be approved by each of the KEP approvers. If any of those approvers is no longer appropriate than changes to that list should be approved by the remaining approvers and/or the owning SIG (or SIG-arch for cross cutting KEPs). | ||
|
|
||
| **Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone. | ||
|
|
||
| [kubernetes.io]: https://kubernetes.io/ | ||
| [kubernetes/enhancements]: https://github.com/kubernetes/enhancements/issues | ||
| [kubernetes/kubernetes]: https://github.com/kubernetes/kubernetes | ||
| [kubernetes/website]: https://github.com/kubernetes/website | ||
|
|
||
| ## 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. | ||
| KEP editors, SIG Docs, and SIG PM should help to ensure that the tone and content of the `Summary` section is useful for a wide audience. | ||
|
|
||
|
|
@@ -105,7 +143,7 @@ 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 | ||
|
|
@@ -135,13 +173,96 @@ 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 the SIG or subproject. | ||
|
|
||
| ## 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. | ||
justaugustus marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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][testing-guidelines] when drafting this test plan. | ||
|
|
||
| [testing-guidelines]: https://git.k8s.io/community/contributors/devel/sig-testing/testing.md | ||
|
|
||
| ### Graduation Criteria | ||
|
|
||
| **Note:** *Section not required until targeted at a release.* | ||
|
|
||
| Define graduation milestones. | ||
|
|
||
| These may be defined in terms of API maturity, or as something else. Initial KEP should keep | ||
| this high-level with a focus on what signals will be looked at to determine graduation. | ||
|
|
||
| Consider the following in developing the graduation criteria for this enhancement: | ||
| - [Maturity levels (`alpha`, `beta`, `stable`)][maturity-levels] | ||
| - [Deprecation policy][deprecation-policy] | ||
|
There was a problem hiding this comment. Could we explicitly state that a single KEP is for all maturity levels through graduation and that the graduation criteria should be described for the transition between each level. The examples below share this but some explicit direction could help clear up what @bgrant0607 noticed and I realized may be implicitly communicated. There was a problem hiding this comment. @mattfarina -- I'm wondering if that's a better fit for the front documentation on KEPs (which I'm planning to work on once this lands)? A KEP captures details of an enhancement and is meant to be the steel thread to capture all implementation states. There should only be one KEP per enhancement. Happy to add something if that thought isn't really captured well. |
||
|
|
||
| Clearly define what graduation means by either linking to the [API doc definition](https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning), | ||
justaugustus marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| or by redefining what graduation means. | ||
|
|
||
| In general, we try to use the same stages (alpha, beta, GA), regardless how the functionality is accessed. | ||
|
|
||
| [maturity-levels]: https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions | ||
| [deprecation-policy]: https://kubernetes.io/docs/reference/using-api/deprecation-policy/ | ||
|
|
||
| #### Examples | ||
|
|
||
| These are generalized examples to consider, in addition to the aforementioned [maturity levels][maturity-levels]. | ||
|
|
||
| ##### Alpha -> Beta Graduation | ||
|
|
||
| - Gather feedback from developers and surveys | ||
| - Complete features A, B, C | ||
justaugustus marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Tests are in Testgrid and linked in KEP | ||
|
|
||
| ##### Beta -> GA Graduation | ||
|
|
||
| - N examples of real world usage | ||
|
There was a problem hiding this comment. Is there a way to have comments in markdown? Perhaps leave these as suggestions inside a comment; outside of the comment I'd say something like "TBD after beta" with the hint that people will update the KEP once they are in beta and know what they'll do? There was a problem hiding this comment. This section is only meant as examples, so authors should feel free to remove. |
||
| - N installs | ||
|
There was a problem hiding this comment. I suggest we document current best practice here rather than try to raise the bar by suggesting untested approaches. We need to get much better at measuring actual usage of features, user surveys, user research, etc., but we don't have established ways to do these things. These should be tasks that need to be completed in order to achieve the bar for the desired maturity level, currently sketched here: It might include more rigorous forms of testing, for instance, such as downgrade tests or scalability tests. Generally we also wait at least 2 releases between beta and GA/stable, since there's no opportunity for user feedback, or even bug reports, in back-to-back releases. There was a problem hiding this comment. @kow3ns Could you share what we went through with taking the workloads to GA? That may help as a real world example. |
||
| - More rigorous forms of testing e.g., downgrade tests and scalability tests | ||
| - Allowing time for feedback | ||
|
|
||
| **Note:** Generally we also wait at least 2 releases between beta and GA/stable, since there's no opportunity for user feedback, or even bug reports, in back-to-back releases. | ||
|
|
||
| ##### 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 | ||
|
|
||
| **For non-optional features moving to GA, the graduation criteria must include [conformance tests].** | ||
|
|
||
| [conformance tests]: https://github.com/kubernetes/community/blob/master/contributors/devel/conformance-tests.md | ||
|
|
||
| ### Upgrade / Downgrade Strategy | ||
|
|
||
| If applicable, how will the component be upgraded and downgraded? Make sure this is in the test plan. | ||
|
|
||
| Consider the following in developing an upgrade/downgrade strategy for this enhancement: | ||
| - What changes (in invocations, configurations, API use, etc.) is an existing cluster required to make on upgrade in order to keep previous behavior? | ||
| - What changes (in invocations, configurations, API use, etc.) is an existing cluster required to make on upgrade in order to make use of the enhancement? | ||
|
|
||
| ### Version Skew Strategy | ||
|
|
||
| If applicable, how will the component handle version skew with other components? What are the guarantees? Make sure | ||
| this is in the test plan. | ||
|
|
||
| Consider the following in developing a version skew strategy for this enhancement: | ||
| - Does this enhancement involve coordinating behavior in the control plane and in the kubelet? How does an n-2 kubelet without this feature available behave when this feature is used? | ||
|
There was a problem hiding this comment. This applies to nodes generally, so kube-proxy and any other node agents as well as kubelet. |
||
| - Will any other components on the node change? For example, changes to CSI, CRI or CNI may require updating that component before the kubelet. | ||
|
|
||
| ## Implementation History | ||
|
|
||
|
|
@@ -167,4 +288,4 @@ Similar to the `Drawbacks` section the `Alternatives` section is used to highlig | |
|
|
||
| Use this section if you need things from the project/SIG. | ||
| Examples include a new subproject, repos requested, github details. | ||
| Listing these here allows a SIG to get the process for these resources started right away. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How do we deal with differing release processes? For example, when kubectl is broken out into its own repo and has a release process and timing that is different from k8s/k8s?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd prefer we deal with that later, and focus on getting this to an iterable place for kubernetes/kubernetes since that's the pressing need
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree to postpone that. It's worth specifying that this is for the main Kubernetes minor release, though.