Skip to content

Commit d91e647

Browse files
michaelaspmichaelasp
committed
Comparable Resource Version KEP
1 parent ae9096a commit d91e647

File tree

2 files changed

+323
-0
lines changed

2 files changed

+323
-0
lines changed

‎keps/sig-api-machinery/5504-comparable-resource-version/README.md‎

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
1+
<!--
2+
**Note:** When your KEP is complete, all of these comment blocks should be removed.
3+
4+
To get started with this template:
5+
6+
- [ ] **Pick a hosting SIG.**
7+
Make sure that the problem space is something the SIG is interested in taking
8+
up. KEPs should not be checked in without a sponsoring SIG.
9+
- [ ] **Create an issue in kubernetes/enhancements**
10+
When filing an enhancement tracking issue, please make sure to complete all
11+
fields in that template. One of the fields asks for a link to the KEP. You
12+
can leave that blank until this KEP is filed, and then go back to the
13+
enhancement and add the link.
14+
- [ ] **Make a copy of this template directory.**
15+
Copy this template into the owning SIG's directory and name it
16+
`NNNN-short-descriptive-title`, where `NNNN` is the issue number (with no
17+
leading-zero padding) assigned to your enhancement above.
18+
- [ ] **Fill out as much of the kep.yaml file as you can.**
19+
At minimum, you should fill in the "Title", "Authors", "Owning-sig",
20+
"Status", and date-related fields.
21+
- [ ] **Fill out this file as best you can.**
22+
At minimum, you should fill in the "Summary" and "Motivation" sections.
23+
These should be easy if you've preflighted the idea of the KEP with the
24+
appropriate SIG(s).
25+
- [ ] **Create a PR for this KEP.**
26+
Assign it to people in the SIG who are sponsoring this process.
27+
- [ ] **Merge early and iterate.**
28+
Avoid getting hung up on specific details and instead aim to get the goals of
29+
the KEP clarified and merged quickly. The best way to do this is to just
30+
start with the high-level sections and fill out details incrementally in
31+
subsequent PRs.
32+
33+
Just because a KEP is merged does not mean it is complete or approved. Any KEP
34+
marked as `provisional` is a working document and subject to change. You can
35+
denote sections that are under active debate as follows:
36+
37+
```
38+
<<[UNRESOLVED optional short context or usernames ]>>
39+
Stuff that is being argued.
40+
<<[/UNRESOLVED]>>
41+
```
42+
43+
When editing KEPS, aim for tightly-scoped, single-topic PRs to keep discussions
44+
focused. If you disagree with what is already in a document, open a new PR
45+
with suggested changes.
46+
47+
One KEP corresponds to one "feature" or "enhancement" for its whole lifecycle.
48+
You do not need a new KEP to move from beta to GA, for example. If
49+
new details emerge that belong in the KEP, edit the KEP. Once a feature has become
50+
"implemented", major changes should get new KEPs.
51+
52+
The canonical place for the latest set of instructions (and the likely source
53+
of this file) is [here](/keps/NNNN-kep-template/README.md).
54+
55+
**Note:** Any PRs to move a KEP to `implementable`, or significant changes once
56+
it is marked `implementable`, must be approved by each of the KEP approvers.
57+
If none of those approvers are still appropriate, then changes to that list
58+
should be approved by the remaining approvers and/or the owning SIG (or
59+
SIG Architecture for cross-cutting KEPs).
60+
-->
61+
# KEP-5504: Comparable Resource Versions
62+
63+
<!--
64+
This is the title of your KEP. Keep it short, simple, and descriptive. A good
65+
title can help communicate what the KEP is and should be considered as part of
66+
any review.
67+
-->
68+
69+
<!--
70+
A table of contents is helpful for quickly jumping to sections of a KEP and for
71+
highlighting any additional information provided beyond the standard KEP
72+
template.
73+
74+
Ensure the TOC is wrapped with
75+
<code>&lt;!-- toc --&rt;&lt;!-- /toc --&rt;</code>
76+
tags, and then generate with `hack/update-toc.sh`.
77+
-->
78+
79+
<!-- toc -->
80+
- [Release Signoff Checklist](#release-signoff-checklist)
81+
- [Summary](#summary)
82+
- [Motivation](#motivation)
83+
- [Goals](#goals)
84+
- [Non-Goals](#non-goals)
85+
- [Proposal](#proposal)
86+
- [User Stories (Optional)](#user-stories-optional)
87+
- [Story 1](#story-1)
88+
- [Story 2](#story-2)
89+
- [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional)
90+
- [Risks and Mitigations](#risks-and-mitigations)
91+
- [Design Details](#design-details)
92+
- [Test Plan](#test-plan)
93+
- [Prerequisite testing updates](#prerequisite-testing-updates)
94+
- [Unit tests](#unit-tests)
95+
- [Integration tests](#integration-tests)
96+
- [e2e tests](#e2e-tests)
97+
- [Graduation Criteria](#graduation-criteria)
98+
- [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
99+
- [Version Skew Strategy](#version-skew-strategy)
100+
- [Production Readiness Review Questionnaire](#production-readiness-review-questionnaire)
101+
- [Implementation History](#implementation-history)
102+
- [Drawbacks](#drawbacks)
103+
- [Alternatives](#alternatives)
104+
<!-- /toc -->
105+
106+
## Release Signoff Checklist
107+
108+
<!--
109+
**ACTION REQUIRED:** In order to merge code into a release, there must be an
110+
issue in [kubernetes/enhancements] referencing this KEP and targeting a release
111+
milestone **before the [Enhancement Freeze](https://git.k8s.io/sig-release/releases)
112+
of the targeted release**.
113+
114+
For enhancements that make changes to code or processes/procedures in core
115+
Kubernetes—i.e., [kubernetes/kubernetes], we require the following Release
116+
Signoff checklist to be completed.
117+
118+
Check these off as they are completed for the Release Team to track. These
119+
checklist items _must_ be updated for the enhancement to be released.
120+
-->
121+
122+
Items marked with (R) are required *prior to targeting to a milestone / release*.
123+
124+
- [ ] (R) Enhancement issue in release milestone, which links to KEP dir in [kubernetes/enhancements] (not the initial KEP PR)
125+
- [ ] (R) KEP approvers have approved the KEP status as `implementable`
126+
- [ ] (R) Design details are appropriately documented
127+
- [ ] (R) Test plan is in place, giving consideration to SIG Architecture and SIG Testing input (including test refactors)
128+
- [ ] e2e Tests for all Beta API Operations (endpoints)
129+
- [ ] (R) Ensure GA e2e tests meet requirements for [Conformance Tests](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/conformance-tests.md)
130+
- [ ] (R) Minimum Two Week Window for GA e2e tests to prove flake free
131+
- [ ] (R) Graduation criteria is in place
132+
- [ ] (R) [all GA Endpoints](https://github.com/kubernetes/community/pull/1806) must be hit by [Conformance Tests](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/conformance-tests.md)
133+
- [ ] (R) Production readiness review completed
134+
- [ ] (R) Production readiness review approved
135+
- [ ] "Implementation History" section is up-to-date for milestone
136+
- [ ] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io]
137+
- [ ] Supporting documentation—e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes
138+
139+
<!--
140+
**Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone.
141+
-->
142+
143+
[kubernetes.io]: https://kubernetes.io/
144+
[kubernetes/enhancements]: https://git.k8s.io/enhancements
145+
[kubernetes/kubernetes]: https://git.k8s.io/kubernetes
146+
[kubernetes/website]: https://git.k8s.io/website
147+
148+
## Summary
149+
150+
Resource version is currently defined as an opaque string from the view of a client, with the only operation that is supported being equality comparisons. This differs from the internal apiserver implementation, where it is clearly defined as a monotonically incrementing integer. There are increasing requirements being required from clients consuming object metadata, where stronger comparisons than just equality are required.
151+
152+
We propose to extend some of the guarantees that the apiserver uses to the client as well, particularly the ability to consume the resource version as an integer, and the ability to compare resource versions to each other for more than equality. Clients can use the new semantics in order to view the "age" of a resource compared to another.
153+
154+
## Motivation
155+
156+
The motivation for this feature comes from the need for certain features to compare resources of the same kind to each other. One strong use case is storage version migration, where in order to tell whether a resource is fully migrated we check the resource version of the last migrated resource until we are sure all resources prior to migration have been migrated. This requires us to do comparisons besides equality on the resource.
157+
158+
Another good example of needing to compare resources is a controller that controls deployments. By being able to check the resource version before and after deployment updates, it has the ability to see whether or not a new pod has been created yet. While equality checks are used for that currently, this opens up the floor for subtle correctness bugs and issues when churn is happening in the cluster. Current controllers work most of the time but can run into issues where staleness of the cache and other issues can affect what the controller sees as the current state. By having comparison based RV handling, controllers can directly check whether the objects are actually newer than before.
159+
160+
161+
### Goals
162+
163+
The goals for this KEP are fairly straightforward, firstly we will expose a utility function that clients can use on the resource version to check comparisons between resource versions. This will take the opaque resource version string and return a boolean and an error if it occurs. Along with that we will update the documentation to specify that a ResourceVersion must be a monotonically increasing integer.
164+
165+
Second, we will create conformance tests to ensure that a conformant cluster abides by the new constraints to the resource version. This should be essentially every cluster in production but will give us the guarantee that users will be unaffected by the new constraints.
166+
167+
168+
### Non-Goals
169+
170+
Non goals for the KEP are constraining size of the resource version from a client perspective, or adding opinionated ideas of the structure of a resource version besides comparability from a client perspective.
171+
172+
## Proposal
173+
174+
We will expose a helper function in client-go that will compare resource versions. It will have the type definition as follows
175+
176+
```
177+
func CompareResourceVersion(x, y string) int error
178+
```
179+
180+
We expose an error in case the strings are non comparable and return either (-1, 0, 1), following the cmp definition where we return -1 if x is less than y, 0 if they are equal, and 1 if x is greater than y.
181+
182+
The internal implementation of this is important to ensure compatibility and efficiency:
183+
- Loop through the string to ensure all characters are 0-9 with no leading 0's
184+
- Compare length of strings, if they are not equal then the one with larger length is greater
185+
- If they are equal, perform a lexical comparison per character left to right until we hit a different character, at that point comparison between the characters will give us the larger integer
186+
187+
By doing it via lexical comparison we do not impose a restriction on resource version sizing and is more efficient than [bigint libraries](https://github.com/liggitt/kubernetes/commits/compare-rv-benchmark/)
188+
189+
Along with this, we will also add a conformance test to kubernetes for all builtin types to ensure they are conformant. On this end we will enforce a 128 bit integer limitation on resource version
190+
191+
### User Stories (Optional)
192+
193+
<!--
194+
Detail the things that people will be able to do if this KEP is implemented.
195+
Include as much detail as possible so that people can understand the "how" of
196+
the system. The goal here is to make this feel real for users without getting
197+
bogged down.
198+
-->
199+
200+
#### Story 1
201+
202+
I am a controller creator and want to see if my actions have been done to all objects created before a certain object. I use the helper function along with a streamed list to do my work until I hit a greater than or equal object and stop work. Without this I would have to run my work on all objects.
203+
204+
#### Story 2
205+
206+
I am a controller creator and want to see whether my cache has caught up to my actions done on my previous reconcile. I use the helper function to compare the resource version and use it to more efficiently reconcile my objects.
207+
208+
### Notes/Constraints/Caveats (Optional)
209+
210+
<!--
211+
What are the caveats to the proposal?
212+
What are some important details that didn't come across above?
213+
Go in to as much detail as necessary here.
214+
This might be a good place to talk about core concepts and how they relate.
215+
-->
216+
217+
### Risks and Mitigations
218+
219+
There are certain API objects that may not conform to this specification. Controllers must gracefully handle these objects, which is why we provide an error type to the function signature. These cases will only occur on non conformant clusters and certain aggregated apiservers however, since we will be adding conformance tests to ensure compatibility.
220+
221+
## Design Details
222+
223+
<!--
224+
This section should contain enough information that the specifics of your
225+
change are understandable. This may include API specs (though not always
226+
required) or even code snippets. If there's any ambiguity about HOW your
227+
proposal will be implemented, this is the place to discuss them.
228+
-->
229+
230+
### Test Plan
231+
232+
We will add unit tests for the actual helper function. However the more involved piece of work will be adding conformance tests for every built in api type to ensure that the cluster is conforming with the new requirements. This will ensure that a client working on a conformant cluster will not encounter errors.
233+
234+
[x] I/we understand the owners of the involved components may require updates to
235+
existing tests to make this code solid enough prior to committing the changes necessary
236+
to implement this enhancement.
237+
238+
##### Prerequisite testing updates
239+
240+
<!--
241+
Based on reviewers feedback describe what additional tests need to be added prior
242+
implementing this enhancement to ensure the enhancements have also solid foundations.
243+
-->
244+
245+
##### Unit tests
246+
247+
We will add unit tests for the helper function added above.
248+
249+
##### Integration tests
250+
251+
N/A
252+
253+
##### e2e tests
254+
255+
N/A
256+
257+
### Graduation Criteria
258+
259+
This is not a normal feature, rather an additional helper function. There will not be a graduation process function will be able to be used by clients once added to the client-go library. There will not be externally visible changes.
260+
261+
### Upgrade / Downgrade Strategy
262+
263+
N/A
264+
265+
### Version Skew Strategy
266+
267+
N/A
268+
269+
## Production Readiness Review Questionnaire
270+
271+
N/A as this is not a feature being added to K8s, rather a helper function with conformance tests.
272+
273+
## Implementation History
274+
275+
* 2025-08-28 - KEP sent for review
276+
<!--
277+
Major milestones in the lifecycle of a KEP should be tracked in this section.
278+
Major milestones might include:
279+
- the `Summary` and `Motivation` sections being merged, signaling SIG acceptance
280+
- the `Proposal` section being merged, signaling agreement on a proposed design
281+
- the date implementation started
282+
- the first Kubernetes release where an initial version of the KEP was available
283+
- the version of Kubernetes where the KEP graduated to general availability
284+
- when the KEP was retired or superseded
285+
-->
286+
287+
## Drawbacks
288+
289+
This constrains the possible values of a resource version to a comparable integer, however this is already used in the apiserver code. This just extends the same ability to the client code with
290+
291+
## Alternatives
292+
293+
N/A

‎keps/sig-api-machinery/5504-comparable-resource-version/kep.yaml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
title: Comparable Resource Version
2+
kep-number: 5504
3+
authors:
4+
- "@michaelasp"
5+
owning-sig: sig-api-machinery
6+
status: provisional
7+
creation-date: 2025-08-28
8+
reviewers:
9+
- "@jpbetz"
10+
approvers:
11+
- "@deads2k"
12+
- "@liggit"
13+
14+
15+
# The target maturity stage in the current dev cycle for this KEP.
16+
# If the purpose of this KEP is to deprecate a user-visible feature
17+
# and a Deprecated feature gates are added, they should be deprecated|disabled|removed.
18+
stage: alpha
19+
20+
# The most recent milestone for which work toward delivery of this KEP has been
21+
# done. This can be the current (upcoming) milestone, if it is being actively
22+
# worked on.
23+
latest-milestone: "v1.35"
24+
25+
# The milestone at which this feature was, or is targeted to be, at each stage.
26+
milestone:
27+
alpha: "v1.35"
28+
29+
# The following PRR answers are required at alpha release
30+
# List the feature gate name and the components for which it must be enabled

0 commit comments

Comments
 (0)