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 1 commit into
base: master
Choose a base branch
from
Open

KEP2149: Add the well known property ladder #5255

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
25 changes: 22 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 @@ -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

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.
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


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


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

Choose a reason for hiding this comment

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

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.

Copy link
Member

@MrFreezeex MrFreezeex Apr 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

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?

Copy link
Member

Choose a reason for hiding this comment

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

nit: "it must be implemented by every implementer that implements the About API." sounds a bit redundant :x

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

#### Note: On ClusterProperty.value max length validation
Expand Down Expand Up @@ -640,7 +659,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 +671,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 +720,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