From f1c176e5395b70711cc2a2d844785c314fc95e89 Mon Sep 17 00:00:00 2001 From: Antoine Pelisse Date: Wed, 18 Jul 2018 14:44:53 -0700 Subject: Move api-machinery KEPs to dir --- keps/0006-apply.md | 171 --------------------------------- keps/0015-dry-run.md | 66 ------------- keps/sig-api-machinery/0006-apply.md | 171 +++++++++++++++++++++++++++++++++ keps/sig-api-machinery/0015-dry-run.md | 66 +++++++++++++ 4 files changed, 237 insertions(+), 237 deletions(-) delete mode 100644 keps/0006-apply.md delete mode 100644 keps/0015-dry-run.md create mode 100644 keps/sig-api-machinery/0006-apply.md create mode 100644 keps/sig-api-machinery/0015-dry-run.md diff --git a/keps/0006-apply.md b/keps/0006-apply.md deleted file mode 100644 index 980f89e8..00000000 --- a/keps/0006-apply.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -kep-number: 6 -title: Apply -authors: - - "@lavalamp" -owning-sig: sig-api-machinery -participating-sigs: - - sig-api-machinery - - sig-cli -reviewers: - - "@pwittrock" - - "@erictune" -approvers: - - "@bgrant0607" -editor: TBD -creation-date: 2018-03-28 -last-updated: 2018-03-28 -status: provisional -see-also: - - n/a -replaces: - - n/a -superseded-by: - - n/a ---- - -# Apply - -## Table of Contents - -- [Apply](#apply) - - [Table of Contents](#table-of-contents) - - [Summary](#summary) - - [Motivation](#motivation) - - [Goals](#goals) - - [Non-Goals](#non-goals) - - [Proposal](#proposal) - - [Implementation Details/Notes/Constraints [optional]](#implementation-detailsnotesconstraints-optional) - - [Risks and Mitigations](#risks-and-mitigations) - - [Graduation Criteria](#graduation-criteria) - - [Implementation History](#implementation-history) - - [Drawbacks](#drawbacks) - - [Alternatives](#alternatives) - -## Summary - -`kubectl apply` is a core part of the Kubernetes config workflow, but it is -buggy and hard to fix. This functionality will be regularized and moved to the -control plane. - -## Motivation - -Example problems today: - -* User does POST, then changes something and applies: surprise! -* User does an apply, then `kubectl edit`, then applies again: surprise! -* User does GET, edits locally, then apply: surprise! -* User tweaks some annotations, then applies: surprise! -* Alice applies something, then Bob applies something: surprise! - -Why can't a smaller change fix the problems? Why hasn't it already been fixed? - -* Too many components need to change to deliver a fix -* Organic evolution and lack of systematic approach - * It is hard to make fixes that cohere instead of interfere without a clear model of the feature -* Lack of API support meant client-side implementation - * The client sends a PATCH to the server, which necessitated strategic merge patch--as no patch format conveniently captures the data type that is actually needed. - * Tactical errors: SMP was not easy to version, fixing anything required client and server changes and a 2 release deprecation period. -* The implications of our schema were not understood, leading to bugs. - * e.g., non-positional lists, sets, undiscriminated unions, implicit context - * Complex and confusing defaulting behavior (e.g., Always pull policy from :latest) - * Non-declarative-friendly API behavior (e.g., selector updates) - -### Goals - -"Apply" is intended to allow users and systems to cooperatively determine the -desired state of an object. The resulting system should: - -* Be robust to changes made by other users, systems, defaulters (including mutating admission control webhooks), and object schema evolution. -* Be agnostic about prior steps in a CI/CD system (and not require such a system). -* Have low cognitive burden: - * For integrators: a single API concept supports all object types; integrators - have to learn one thing total, not one thing per operation per api object. - Client side logic should be kept to a minimum; CURL should be sufficient to - use the apply feature. - * For users: looking at a config change, it should be intuitive what the - system will do. The “magic” is easy to understand and invoke. - * Error messages should--to the extent possible--tell users why they had a - conflict, not just what the conflict was. - * Error messages should be delivered at the earliest possible point of - intervention. - -Goal: The control plane delivers a comprehensive solution. - -Goal: Apply can be called by non-go languages and non-kubectl clients. (e.g., -via CURL.) - -### Non-Goals - -* Multi-object apply will not be changed: it remains client side for now -* Providing an API for just performing merges (without affecting state in the - cluster) is left as future work. -* Some sources of user confusion will not be addressed: - * Changing the name field makes a new object rather than renaming an existing object - * Changing fields that can’t really be changed (e.g., Service type). - -## Proposal - -Some highlights of things we intend to change: - -* Apply will be moved to the control plane: [overall design](https://goo.gl/UbCRuf). - * It will be invoked by sending a certain Content-Type with the verb PATCH. -* The last-applied annotation will be promoted to a first-class citizen under - metadata. Multiple appliers will be allowed. -* Apply will have user-targeted and controller-targeted variants. -* The Go IDL will be fixed: [design](https://goo.gl/EBGu2V). OpenAPI data models will be fixed. Result: 2-way and - 3-way merges can be implemented correctly. -* 2-way and 3-way merges will be implemented correctly: [design](https://goo.gl/nRZVWL). -* Dry-run will be implemented on control plane verbs (POST and PUT). - * Admission webhooks will have their API appended accordingly. -* The defaulting and conversion stack will be solidified to allow converting - partially specified objects. -* An upgrade path will be implemented so that version skew between kubectl and - the control plane will not have disastrous results. -* Strategic Merge Patch and the existing merge key annotations will be - deprecated. Development on these will stop, but they will not be removed until - the v1 API goes away (i.e., likely 3+ years). - -The linked documents should be read for a more complete picture. - -### 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 - -There are many things that will need to change. We are considering using a -feature branch. - -## Graduation Criteria - -This can be promoted to beta when it is a drop-in replacement for the existing -kubectl apply, which has no regressions (which aren't bug fixes). - -This will be promoted to GA once it's gone a sufficient amount of time as beta -with no changes. - -## Implementation History - -Major milestones in the life cycle of a KEP should be tracked in `Implementation History`. -Major milestones might include - -- the `Summary` and `Motivation` sections being merged signaling SIG acceptance -- the `Proposal` section 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 - -Why should this KEP _not_ be implemented: many bugs in kubectl apply will go -away. Users might be depending on the bugs. - -## Alternatives - -It's our belief that all routes to fixing the user pain involve -centralizing this functionality in the control plane. diff --git a/keps/0015-dry-run.md b/keps/0015-dry-run.md deleted file mode 100644 index cdd2012a..00000000 --- a/keps/0015-dry-run.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -kep-number: 15 -title: Dry-run -authors: - - "@apelisse" -owning-sig: sig-api-machinery -participating-sigs: - - sig-api-machinery - - sig-cli -reviewers: - - "@lavalamp" - - "@deads2k" -approvers: - - "@erictune" -editor: apelisse -creation-date: 2018-06-21 -last-updated: 2018-06-21 -status: provisional ---- -# Kubernetes Dry-run - -Dry-run is a new feature that we intend to implement in the api-server. The goal -is to be able to send requests to modifying endpoints, and see if the request -would have succeeded (admission chain, validation, merge conflicts, ...) and/or -what would have happened without having it actually happen. The response body -for the request should be as close as possible to a non dry-run response. - -## Specifying dry-run - -Dry-run is triggered by setting the “dryRun” query parameter on modifying -verbs: POST, PUT, PATCH and DELETE. - -This parameter is a string, working as an enum: -- All: Everything will run as normal, except for the storage that won’t be - modified. Everything else should work as expected: admission controllers will - be run to check that the request is valid, mutating controllers will change - the object, merge will be performed on PATCH. The storage layer will be - informed not to save, and the final object will be returned to the user with - normal status code. -- Leave the value empty, or don't specify the parameter at all to keep the - default modifying behavior. - -No other values are supported yet, but this gives us an opportunity to create a -finer-grained mechanism later, if necessary. - -## Admission controllers - -Admission controllers need to be modified to understand that the request is a -“dry-run” request. While admission controllers are not supposed to have -side-effects when triggered, some of them still do. Quotas for example uses the -current request values to change the available quotas. Providing a parameter, -either as an argument for built-in admission plugins or through a dryRun -query-parameter for dynamic webhooks, will give them a chance not to have any -side-effect. - -All admission controllers will have to be verified and changed. A new flag will -be added so that webhooks can explicitly register with dry-run support. If -dry-run is requested on a non-supported webhook, the request will be completely -rejected. - -## Storage - -The storage layer will be modified, so that it can know if request is dry-run, -most likely by looking for the field in the “Options” structure (missing for -some handlers, to be added). If it is, it will NOT store the object, but return -success. That success can be forwarded back to the user. diff --git a/keps/sig-api-machinery/0006-apply.md b/keps/sig-api-machinery/0006-apply.md new file mode 100644 index 00000000..980f89e8 --- /dev/null +++ b/keps/sig-api-machinery/0006-apply.md @@ -0,0 +1,171 @@ +--- +kep-number: 6 +title: Apply +authors: + - "@lavalamp" +owning-sig: sig-api-machinery +participating-sigs: + - sig-api-machinery + - sig-cli +reviewers: + - "@pwittrock" + - "@erictune" +approvers: + - "@bgrant0607" +editor: TBD +creation-date: 2018-03-28 +last-updated: 2018-03-28 +status: provisional +see-also: + - n/a +replaces: + - n/a +superseded-by: + - n/a +--- + +# Apply + +## Table of Contents + +- [Apply](#apply) + - [Table of Contents](#table-of-contents) + - [Summary](#summary) + - [Motivation](#motivation) + - [Goals](#goals) + - [Non-Goals](#non-goals) + - [Proposal](#proposal) + - [Implementation Details/Notes/Constraints [optional]](#implementation-detailsnotesconstraints-optional) + - [Risks and Mitigations](#risks-and-mitigations) + - [Graduation Criteria](#graduation-criteria) + - [Implementation History](#implementation-history) + - [Drawbacks](#drawbacks) + - [Alternatives](#alternatives) + +## Summary + +`kubectl apply` is a core part of the Kubernetes config workflow, but it is +buggy and hard to fix. This functionality will be regularized and moved to the +control plane. + +## Motivation + +Example problems today: + +* User does POST, then changes something and applies: surprise! +* User does an apply, then `kubectl edit`, then applies again: surprise! +* User does GET, edits locally, then apply: surprise! +* User tweaks some annotations, then applies: surprise! +* Alice applies something, then Bob applies something: surprise! + +Why can't a smaller change fix the problems? Why hasn't it already been fixed? + +* Too many components need to change to deliver a fix +* Organic evolution and lack of systematic approach + * It is hard to make fixes that cohere instead of interfere without a clear model of the feature +* Lack of API support meant client-side implementation + * The client sends a PATCH to the server, which necessitated strategic merge patch--as no patch format conveniently captures the data type that is actually needed. + * Tactical errors: SMP was not easy to version, fixing anything required client and server changes and a 2 release deprecation period. +* The implications of our schema were not understood, leading to bugs. + * e.g., non-positional lists, sets, undiscriminated unions, implicit context + * Complex and confusing defaulting behavior (e.g., Always pull policy from :latest) + * Non-declarative-friendly API behavior (e.g., selector updates) + +### Goals + +"Apply" is intended to allow users and systems to cooperatively determine the +desired state of an object. The resulting system should: + +* Be robust to changes made by other users, systems, defaulters (including mutating admission control webhooks), and object schema evolution. +* Be agnostic about prior steps in a CI/CD system (and not require such a system). +* Have low cognitive burden: + * For integrators: a single API concept supports all object types; integrators + have to learn one thing total, not one thing per operation per api object. + Client side logic should be kept to a minimum; CURL should be sufficient to + use the apply feature. + * For users: looking at a config change, it should be intuitive what the + system will do. The “magic” is easy to understand and invoke. + * Error messages should--to the extent possible--tell users why they had a + conflict, not just what the conflict was. + * Error messages should be delivered at the earliest possible point of + intervention. + +Goal: The control plane delivers a comprehensive solution. + +Goal: Apply can be called by non-go languages and non-kubectl clients. (e.g., +via CURL.) + +### Non-Goals + +* Multi-object apply will not be changed: it remains client side for now +* Providing an API for just performing merges (without affecting state in the + cluster) is left as future work. +* Some sources of user confusion will not be addressed: + * Changing the name field makes a new object rather than renaming an existing object + * Changing fields that can’t really be changed (e.g., Service type). + +## Proposal + +Some highlights of things we intend to change: + +* Apply will be moved to the control plane: [overall design](https://goo.gl/UbCRuf). + * It will be invoked by sending a certain Content-Type with the verb PATCH. +* The last-applied annotation will be promoted to a first-class citizen under + metadata. Multiple appliers will be allowed. +* Apply will have user-targeted and controller-targeted variants. +* The Go IDL will be fixed: [design](https://goo.gl/EBGu2V). OpenAPI data models will be fixed. Result: 2-way and + 3-way merges can be implemented correctly. +* 2-way and 3-way merges will be implemented correctly: [design](https://goo.gl/nRZVWL). +* Dry-run will be implemented on control plane verbs (POST and PUT). + * Admission webhooks will have their API appended accordingly. +* The defaulting and conversion stack will be solidified to allow converting + partially specified objects. +* An upgrade path will be implemented so that version skew between kubectl and + the control plane will not have disastrous results. +* Strategic Merge Patch and the existing merge key annotations will be + deprecated. Development on these will stop, but they will not be removed until + the v1 API goes away (i.e., likely 3+ years). + +The linked documents should be read for a more complete picture. + +### 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 + +There are many things that will need to change. We are considering using a +feature branch. + +## Graduation Criteria + +This can be promoted to beta when it is a drop-in replacement for the existing +kubectl apply, which has no regressions (which aren't bug fixes). + +This will be promoted to GA once it's gone a sufficient amount of time as beta +with no changes. + +## Implementation History + +Major milestones in the life cycle of a KEP should be tracked in `Implementation History`. +Major milestones might include + +- the `Summary` and `Motivation` sections being merged signaling SIG acceptance +- the `Proposal` section 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 + +Why should this KEP _not_ be implemented: many bugs in kubectl apply will go +away. Users might be depending on the bugs. + +## Alternatives + +It's our belief that all routes to fixing the user pain involve +centralizing this functionality in the control plane. diff --git a/keps/sig-api-machinery/0015-dry-run.md b/keps/sig-api-machinery/0015-dry-run.md new file mode 100644 index 00000000..cdd2012a --- /dev/null +++ b/keps/sig-api-machinery/0015-dry-run.md @@ -0,0 +1,66 @@ +--- +kep-number: 15 +title: Dry-run +authors: + - "@apelisse" +owning-sig: sig-api-machinery +participating-sigs: + - sig-api-machinery + - sig-cli +reviewers: + - "@lavalamp" + - "@deads2k" +approvers: + - "@erictune" +editor: apelisse +creation-date: 2018-06-21 +last-updated: 2018-06-21 +status: provisional +--- +# Kubernetes Dry-run + +Dry-run is a new feature that we intend to implement in the api-server. The goal +is to be able to send requests to modifying endpoints, and see if the request +would have succeeded (admission chain, validation, merge conflicts, ...) and/or +what would have happened without having it actually happen. The response body +for the request should be as close as possible to a non dry-run response. + +## Specifying dry-run + +Dry-run is triggered by setting the “dryRun” query parameter on modifying +verbs: POST, PUT, PATCH and DELETE. + +This parameter is a string, working as an enum: +- All: Everything will run as normal, except for the storage that won’t be + modified. Everything else should work as expected: admission controllers will + be run to check that the request is valid, mutating controllers will change + the object, merge will be performed on PATCH. The storage layer will be + informed not to save, and the final object will be returned to the user with + normal status code. +- Leave the value empty, or don't specify the parameter at all to keep the + default modifying behavior. + +No other values are supported yet, but this gives us an opportunity to create a +finer-grained mechanism later, if necessary. + +## Admission controllers + +Admission controllers need to be modified to understand that the request is a +“dry-run” request. While admission controllers are not supposed to have +side-effects when triggered, some of them still do. Quotas for example uses the +current request values to change the available quotas. Providing a parameter, +either as an argument for built-in admission plugins or through a dryRun +query-parameter for dynamic webhooks, will give them a chance not to have any +side-effect. + +All admission controllers will have to be verified and changed. A new flag will +be added so that webhooks can explicitly register with dry-run support. If +dry-run is requested on a non-supported webhook, the request will be completely +rejected. + +## Storage + +The storage layer will be modified, so that it can know if request is dry-run, +most likely by looking for the field in the “Options” structure (missing for +some handlers, to be added). If it is, it will NOT store the object, but return +success. That success can be forwarded back to the user. -- cgit v1.2.3