From b210b37ec81af5448763228f7d7a1c6142382cd6 Mon Sep 17 00:00:00 2001 From: Daniel Smith Date: Wed, 28 Mar 2018 17:27:17 -0700 Subject: [PATCH] begin apply KEP --- keps/0006-apply.md | 159 +++++++++++++++++++++++++++++++++++++++++++ keps/NEXT_KEP_NUMBER | 2 +- 2 files changed, 160 insertions(+), 1 deletion(-) create mode 100644 keps/0006-apply.md diff --git a/keps/0006-apply.md b/keps/0006-apply.md new file mode 100644 index 000000000..b24136052 --- /dev/null +++ b/keps/0006-apply.md @@ -0,0 +1,159 @@ +--- +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 + +TODO: generate from: https://github.com/ekalinin/github-markdown-toc + +## 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](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](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](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/NEXT_KEP_NUMBER b/keps/NEXT_KEP_NUMBER index 62f945751..7f8f011eb 100644 --- a/keps/NEXT_KEP_NUMBER +++ b/keps/NEXT_KEP_NUMBER @@ -1 +1 @@ -6 \ No newline at end of file +7