Skip to content

KEP2149: Add the well known property ladder #5255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+50 −3
Open

KEP2149: Add the well known property ladder #5255

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
64b2225
add the property ladder
ryanzhang-oss Apr 21, 2025
ad47883
add property template
ryanzhang-oss Jun 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 50 additions & 3 deletions keps/sig-multicluster/2149-clusterid/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@ tags, and then generate with `hack/update-toc.sh`.
- [Contents](#contents-1)
- [Consumers](#consumers-1)
- [Additional Properties](#additional-properties)
- [Property Ladder](#property-ladder)
- [Notes/Constraints/Caveats](#notesconstraintscaveats)
- [Note: On ClusterProperty.value max length validation](#note-on-clusterpropertyvalue-max-length-validation)
- [Risks and Mitigations](#risks-and-mitigations)
Expand Down Expand Up @@ -486,6 +487,52 @@ following suffixes are reserved for Kubernetes and related projects: `.k8s.io`,
free to use non-namespaced properties (e.g. `fingerprint`) as they see fit, but
any shared tooling should use appropriately namespaced names.

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.
First, we would like to propose a template for everyone to fill in order to propose a new property,
and then we will define a "property ladder" that describes the process of adopting a property to be a well known property.

#### New property proposal template
<form>
Here is the requirements below use the keywords **must, should,** and **may**
purposefully in accordance with [RFC-2119](https://tools.ietf.org/html/rfc2119).

<label for="property-name">Property Name</label><br>
<input type="text" id="property-name" name="property-name" placeholder="[INSERT PROPERTY NAME HERE]" style="width:20%; height:auto;"><br><br>

<label for="uniqueness">Uniqueness</label><br>
<textarea id="uniqueness" name="uniqueness" placeholder="Describe the uniqueness requirements" style="width:50%; height:auto;"></textarea><br><br>

<label for="background">Background</label><br>
<textarea id="background" name="background" placeholder="Describe the motivation and context of this property" style="width:50%; height:auto;"></textarea><br><br>

<label for="notable-scenarios">Notable Scenarios</label><br>
<textarea id="notable-scenarios" name="notable-scenarios" placeholder="Describe the targeted scenario" style="width:50%; height:auto;"></textarea><br><br>

<label for="consumers">Consumers</label><br>
<textarea id="consumers" name="consumers" placeholder="Describe how consumers should use this property" style="width:50%; height:auto;"></textarea><br><br>

<label for="special-note">Special note (optional):</label><br>
<textarea id="special-note" name="special-note" placeholder="Describe any other speical note to this property" style="width:50%; height:auto;"></textarea><br><br>

</form>


#### Property Ladder
Here is the three-tiered approach to adopting a property to be a well known property in the About API:

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Contributor

@lauralorenz lauralorenz Apr 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cloud-event used to have a voting mechanism like this and I would propose something like this

  1. 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. 2/3 of all eligible voters vote yes pass the proposal
  3. The cool off period is 3 months
  4. No veto power

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


3. **Core Property Stage**: After a property has maintained standard status for at least 6 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.
The process for proposing a core property is as follows:
* SIG leads may initiate another vote to determine if there is consensus to elevate the property to the **core** group.
* The community will vote on the proposal, and if it receives approval from at least 2/3 of voters, the property becomes a core property and is incorporated into the About API KEP.

This three-tiered approach ensures that properties are thoroughly vetted before becoming required components of the About API.

### Notes/Constraints/Caveats

Expand Down Expand Up @@ -640,7 +687,7 @@ this time (see the Non-Goals section).
# An example object of `cluster.clusterset.k8s.io ClusterProperty`
# using a kube-system ns uuid as the id value (recommended above):

apiVersion: about.k8s.io/v1
apiVersion: about.k8s.io/v1beta1
kind: ClusterProperty
metadata:
name: cluster.clusterset.k8s.io
Expand All @@ -652,7 +699,7 @@ spec:
# An example object of `cluster.clusterset.k8s.io ClusterProperty`
# using a human-readable string as the id value:

apiVersion: about.k8s.io/v1
apiVersion: about.k8s.io/v1beta1
kind: ClusterProperty
metadata:
name: cluster.clusterset.k8s.io
Expand Down Expand Up @@ -701,7 +748,7 @@ valid.
```
# An example object of `clusterset.k8s.io ClusterProperty`:

apiVersion: about.k8s.io/v1
apiVersion: about.k8s.io/v1beta1
kind: ClusterProperty
metadata:
name: clusterset.k8s.io
Expand Down