KEP2149: Add the well known property ladder #5255
Conversation
k8s-ci-robot
added
cncf-cla: yes
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: ryanzhang-oss The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
sig/multicluster
|
Hi @ryanzhang-oss. Thanks for your PR. I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
k8s-ci-robot
added
the
size/S
| * The property sponsor must present a discussion agenda with clear use cases and motivation at a Multi-cluster SIG meeting. | ||
| * The community will vote on the proposal, and if it receives approval from at least 2/3 of voters, the property becomes a standard property and is incorporated into the About API KEP. | ||
|
|
||
| 3. **Core Property Stage**: After a property has maintained standard status for at least 3 months and has 3 or more implementations, one can propose to elevate it to a **core** property which means it must be implemented by every implementer that implements the About API. |
There was a problem hiding this comment.
what happens if it is missing? 3months from? given we don't have a release process so it may be hard to start counting?
Should we have some kind of versioning in place?
If we don't have versioning, we may want more than 3mo of stability.
There was a problem hiding this comment.
by versioning, do you mean that each property will have things like v1alpha1/beta/GA or more like 0.1, 0.2?
There was a problem hiding this comment.
X-posting discussion from 6/17 SIG-Meeting:
Do we need versioning?
The general temperature was "Probably", and people gave examples of other things that had to retcon this in.
This would be per well known property name, so separately from the regular apiGroup/version of the CRD in general. We would need to come up with what format storing this data would be; is it required that well known properties include it in their value, or are we adding another field? Relatedly we had talked about a "last updated" field in the past, so this could be packaged with that.
See also the comment #5255 (comment) that addresses the thoughts on what to use this version for regarding deprecation and skew, assuming it exists.
| 2. **Standard Property Stage**: The implementor can propose to add a property to be a **standard** property which means if anyone implements the property with the same name, it must follow the same definition and rules described in the KEP. Not all implementers are required to implement the property. | ||
| The process for proposing a standard property is as follows: | ||
| * The property sponsor must present a discussion agenda with clear use cases and motivation at a Multi-cluster SIG meeting. | ||
| * The community will vote on the proposal, and if it receives approval from at least 2/3 of voters, the property becomes a standard property and is incorporated into the About API KEP. |
There was a problem hiding this comment.
How are people eligible to vote? Do we need a quorum? Is there a cool off period between votes on similar proposals? Is there any veto powers by the sig co chairs? Is there anything from CNCF or other SIGs we can, must, or even want to draw on for regulations or tooling?
What, if any, are the obligations of the About API subproject or the proposer to facilitate implementation of a new standard property? For example do we ship the About API with as much webhook coverage as possible for the validation? Do we publish and/or run periodic About API conformance tests for standard properties, or only core properties, or none? If by conformance tests or otherwise we want to try to enforce compliance, how do we determine which implementations to "watch"?
There was a problem hiding this comment.
Cloud-event used to have a voting mechanism like this and I would propose something like this
- Who are eligible to vote: Every entity whose member collectively kept good attendence ( attend the meeting at least 4 out of the last 5 times) have one vote.
- 2/3 of all eligible voters vote yes pass the proposal
- The cool off period is 3 months
- No veto power
There was a problem hiding this comment.
X-posting discussion from 6/17 SIG-Meeting:
Is there a world where it is not a vote but is a rubric/checklist of things that have to be done (example from Gateway API: conformance and 3 implementing projects).
Note that this proposal does already include some rubric/checklist, and THEN there is a vote as well.
On the voting method
What does 'entity' mean to us? Companies, individuals, academics?
Do you have a vote as a 'project' that may not be representing a 'company'?
There is a general feeling that implementors are the ones who should have the most say
Is 4 out of the last 5 "times" of meeting too high of a bar? Maybe 3 out of 5? Is meeting presence even the best representation of participation?
Cool off period = time we must wait before we vote on the same proposal again
|
|
||
| We foresee that there will be more properties that the community wants to adopt as "well known" properties. Thus, we want to define a process for adopting a property to be a well known property in the future: | ||
|
|
||
| 1. **Extension Property Stage**: A property is implemented as an extension property if the implementer has no intent to elevate it to a standard property. This property cannot use the reserved suffixes and is not required to be implemented by all implementers. |
There was a problem hiding this comment.
I think "Extension Property" and "Additional Property" (in the directly preceding header and section) are referring to the same definition. Can we pick one term? Either is fine with me
There was a problem hiding this comment.
Actually, I think "Additional Property" refers to all the new properties that are not in the current KEP while "Extension Property Stage" refers to the initial stage that a new property starts which might gradually progress to the final core stage.
|
|
||
| 2. **Standard Property Stage**: The implementor can propose to add a property to be a **standard** property which means if anyone implements the property with the same name, it must follow the same definition and rules described in the KEP. Not all implementers are required to implement the property. | ||
| The process for proposing a standard property is as follows: | ||
| * The property sponsor must present a discussion agenda with clear use cases and motivation at a Multi-cluster SIG meeting. |
There was a problem hiding this comment.
I think we can add in the template they need to follow too, drawing from the existing ones like
The requirements below use the keywords **must, should,** and **may**
purposefully in accordance with [RFC-2119](https://tools.ietf.org/html/rfc2119).
#### Property: `[INSERT PROPERTY NAME HERE]`
##### Uniqueness
##### Lifespan
##### Contents
##### Consumers
##### Uniqueness
##### Notable scenarios (optional)
Maybe we also want to add in that a head for the use cases need to be included inline, and we update the ones we have today with that too.
| * The property sponsor must present a discussion agenda with clear use cases and motivation at a Multi-cluster SIG meeting. | ||
| * The community will vote on the proposal, and if it receives approval from at least 2/3 of voters, the property becomes a standard property and is incorporated into the About API KEP. | ||
|
|
||
| 3. **Core Property Stage**: After a property has maintained standard status for at least 3 months and has 3 or more implementations, one can propose to elevate it to a **core** property which means it must be implemented by every implementer that implements the About API. |
There was a problem hiding this comment.
I'm wondering if the "implementer" / "implementation" here and also in a few places in this patch is really the right word. Because like I think this makes sense when you are using a cloud provider and it's integrated and you expect to have all those properties. But I can also easily see a scenario where you are not on a cloud provider and want to use certain projects integrating with about API (potentially only reading from it or also writing very specific properties) and you populate this with some kind of ArgoCD setup or whatever automation you use to provision/configure your cluster. Maybe talking about either (not specifically here) of projects that integrate with certain properties or using some more precise term like producer/consumer would be less confusing?
Also if those properties are required I am guessing we might want to have a "dumb"-ish conformance script that checks for those somehow?
There was a problem hiding this comment.
I think here the implementer are all producers as only they can "provide" the property. In ArgoCD case, the cluster manager (i.e. OCM/Karmada/KubeFleet) are the implementors while Argo is the consumer.
There was a problem hiding this comment.
I meant that right now there is only two required field that are very static and easy to define: clusterset name and cluster name. To declare that you don't necessarily need any cluster manager project to define those you can just apply those two resources in whatever ways you prefer. Do we want to change that by having much more properties in the "core property stage"/required list of properties, and if yes to what extent?
Also I am assuming there could be some case where the "implementation" is not only one project like if you have multiple providers publishing some properties. Could be perhaps that you are using some OSS cluster manager but still relies on your cloud provider to publish some of the properties for instance or a mix of project interacting with each other somehow.
| * The property sponsor must present a discussion agenda with clear use cases and motivation at a Multi-cluster SIG meeting. | ||
| * The community will vote on the proposal, and if it receives approval from at least 2/3 of voters, the property becomes a standard property and is incorporated into the About API KEP. | ||
|
|
||
| 3. **Core Property Stage**: After a property has maintained standard status for at least 3 months and has 3 or more implementations, one can propose to elevate it to a **core** property which means it must be implemented by every implementer that implements the About API. |
There was a problem hiding this comment.
nit: "it must be implemented by every implementer that implements the About API." sounds a bit redundant :x
|
Triage notes: still open for comment from folks on the governance perspective, need lead final input as well and will need to put a deadline on it next. |
| * The property sponsor must present a discussion agenda with clear use cases and motivation at a Multi-cluster SIG meeting. | ||
| * The community will vote on the proposal, and if it receives approval from at least 2/3 of voters, the property becomes a standard property and is incorporated into the About API KEP. | ||
|
|
||
| 3. **Core Property Stage**: After a property has maintained standard status for at least 3 months and has 3 or more implementations, one can propose to elevate it to a **core** property which means it must be implemented by every implementer that implements the About API. |
There was a problem hiding this comment.
Would there ever be scenario where there is conflicts or collisions across extension and standard properties?
How do we decide to not promote such collision? Would it be contained at Extension Property Stage ?
Example: Two different implementor could independently define similar properties at the extension level, which then complicates promotion to standard/core.
| @@ -487,6 +488,24 @@ free to use non-namespaced properties (e.g. `fingerprint`) as they see fit, but | |||
| any shared tooling should use appropriately namespaced names. | |||
|
|
|||
|
|
|||
| #### Property Ladder | |||
There was a problem hiding this comment.
There seems to be no process for deprecating/removing property which could lead to long term tech debt for properties that are never see adoption or is proving to be harmful or redundant.
Is there a plan to add something along that line?
There was a problem hiding this comment.
X-posting discussion from 6/17 SIG-Meeting:
What is actually realistic for enterprise environment?
Deprecation is hard, harsher on the enterprises which is who we probably are interacting with given this is multicluster. The temperature at the meeting was that in general we (SIG-MC) need to treat deprecation as even rarer and more painful than in other contexts.
What can we take from the core k8s deprecation policy?
That policy is described at https://kubernetes.io/docs/reference/using-api/deprecation-policy/. I selected some relevant parts:
> Rule #1: API elements may only be removed by incrementing the version of the API group.
> Rule #2: API objects must be able to round-trip between API versions in a given release without information loss, with the exception of whole REST resources that do not exist in some versions.
> Rule #3: An API version in a given track may not be deprecated in favor of a less stable API version.
> Rule #4a: API lifetime is determined by the API stability level
> Rule #4b: The "preferred" API version and the "storage version" for a given group may not advance until after a release has been made that supports both the new version and the previous version
[ ... irrelevant stuff removed ... ]
> Rule #7: Deprecated behaviors must function for no less than 1 year after their announced deprecation.
> Rule #8: The feature of behavior must not be deprecated in favor of an alternative implementation that is less stable
It is hard to directly apply some of this to this for as long as the well known properties do not have independent versions.
What can we take from the version skew policy?
We also brought up the k8s version skew policies between components (https://kubernetes.io/releases/version-skew-policy/) and how that might apply here as well, e.g. need for APIs to be compatible to n-3 minor version kubelets and n-1 minor version API servers, but we don't have as much strict versioning between components.
Signed-off-by: Ryan Zhang <[email protected]>
k8s-ci-robot
added
size/M
|
Triage notes:
|
Add the well known property ladder