Skip to content

Commit 4ab2fca

Browse files
yongruilinyongruilin
committed
[KEP-5073] Update KEP with section of validation ratcheting
1 parent 2dca874 commit 4ab2fca

File tree

1 file changed

+46
-3
lines changed
  • keps/sig-api-machinery/5073-declarative-validation-with-validation-gen

1 file changed

+46
-3
lines changed

‎keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md

Lines changed: 46 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,10 @@
6060
- [Scale-Type Subresources](#scale-type-subresources)
6161
- [Streaming Subresources](#streaming-subresources)
6262
- [Ratcheting](#ratcheting)
63+
- [Core Principles](#core-principles)
64+
- [Default Ratcheting Behavior](#default-ratcheting-behavior)
65+
- [Definition of Semantic Equivalence](#definition-of-semantic-equivalence)
66+
- [Ratcheting and Cross-Field Validation](#ratcheting-and-cross-field-validation)
6367
- [Test Plan](#test-plan)
6468
- [Prerequisite testing updates](#prerequisite-testing-updates)
6569
- [Unit tests](#unit-tests)
@@ -1024,10 +1028,49 @@ The streamed data does not require declarative validation, as it is not structur
10241028

10251029
### Ratcheting
10261030

1027-
TODO: Document and explain how:
1031+
As Kubernetes APIs evolve, validation rules change. To minimize disruption for users with existing objects created under older rules, declarative validation will incorporate **Validation Ratcheting**. This mechanism aims to selectively bypass new or changed validation rules during object updates (`UPDATE`, `PATCH`, `APPLY`) for fields that have not been modified from their previously persisted state.
10281032

1029-
- Add general purpose ratcheting to automatically skip validation of unchanged fields
1030-
- Catalog and handle complex cases where strict equality checks are not sufficient (lots of non-trivial cases exist today)
1033+
#### Core Principles
1034+
1035+
The design adheres to the following core principles:
1036+
1037+
1. **Stored data is considered valid:** Any object successfully persisted was once considered valid. Subsequent apiservers must not retroactively invalidate stored objects. (Implication: fixing validation bugs post-release is challenging).
1038+
2. **Unchanged fields do not cause update rejections:** An `UPDATE` operation must not fail validation due to fields that were not modified in that operation. (Rationale: HTTP 4xx errors imply a client request problem).
1039+
3. **Semantic deep-equal is always sufficient to elide re-validation:** Kubernetes API objects adhere to canonical semantic equivalence rules (`equality.Semantic.DeepEqual`). If a deserialized object satisfies that equivalence with its prior state, re-validation can be bypassed.
1040+
* **Subtle:** List elements might individually bypass re-validation, but the list itself might still be re-validated (e.g., if reordered).
1041+
1042+
Ratcheting is the **default behavior** during `UPDATE` operations.
1043+
1044+
#### Default Ratcheting Behavior
1045+
1046+
The default mechanism handles common cases by skipping re-validation if a field hasn't changed based on semantic equivalence.
1047+
1048+
##### Definition of Semantic Equivalence
1049+
1050+
"Semantic equivalence" builds on `k8s.io/apimachinery/pkg/api/equality.Semantic.DeepEqual` (similar to `reflect.DeepEqual` but `nil` and empty slices/maps are equivalent). The table below outlines the behavior:
1051+
1052+
| Value type | Semantic Equivalence | Ratcheting | CRD Comparison (KEP-4008) |
1053+
| :---------------------------------- | :------------------------------------------------------------- | :----------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ |
1054+
| Scalars (int, string, etc.) | direct equality of the value | revalidate the value if changed | same |
1055+
| Pointers | equivalence of the pointee | revalidate the value if changed | same |
1056+
| Struct | all fields are equivalent | revalidate the struct if any field changed | same |
1057+
| Struct fields<br/>`structType=granular` | - | revalidate changed fields | same |
1058+
| Struct fields<br/>`structType=atomic` | - | revalidate changed fields | [Issue #131566](https://github.com/kubernetes/kubernetes/issues/131566) (Alignment needed) |
1059+
| Slices | all elements are equivalent and the is order unchanged | revalidate the slice if any element changed or order changed | `listType=map`: no validate when re-order<br/>`listType=set`: re-validate when re-order<br/>`listType=atomic`: re-validate when re-order |
1060+
| Slice values<br/>`listType=atomic` | - | validate items which are not found (by value) in the old slice | Validate all elements (CRDs ratcheting may be expanded to match in-tree ratcheting) |
1061+
| Slice values<br/>`listType=map` | - | (re)validate items which are not found (by key) in the old slice or are changed | same |
1062+
| Slice values<br/>`listType=set` | - | validate items which are not found (by value) in the old slice | Validate all elements (CRDs ratcheting may be expanded to match in-tree ratcheting) |
1063+
| Maps | all elements are equivalent | revalidate the map if any element changed | same |
1064+
| Map values<br/>`mapType=granular` | - | (re)validate items which are not found (by key) in the old map | same |
1065+
| Map values<br/>`mapType=atomic` | - | (re)validate items which are not found (by key) in the old map | [Issue #131566](https://github.com/kubernetes/kubernetes/issues/131566) (Alignment needed) |
1066+
1067+
**Note on Atomic Types:** The behavior for `structType=atomic` and `mapType=atomic` intentionally deviates from strict atomic re-validation. Only the specific sub-fields or key-value pairs *that were actually modified* are re-validated. This prioritizes user experience but requires alignment with CRD behavior (tracked in Issue #131566).
1068+
1069+
#### Ratcheting and Cross-Field Validation
1070+
1071+
A challenge arises if a cross-field validation rule (e.g. `X < Y`) is defined on a common ancestor struct, and an unrelated field (e.g. `Z`) within that same ancestor is modified. This change to `Z` makes the common ancestor “changed” overall, triggering re-validation of the `X < Y` rule. If this rule was recently evolved (e.g., made stricter), it might now fail even if `X` and `Y` themselves are not modified by the user’s update. This could violate the principle “Unchanged fields do not cause update rejections.”
1072+
1073+
For the initial implementation, this behavior will be documented. Furthermore, cross-field validation rules themselves must incorporate internal ratcheting logic. For instance, generated code for dedicated cross-field tags (like `+k8s:unionMember`) will be designed to only act upon changes to the specific fields they govern and were designed to validate.
10311074

10321075
### Test Plan
10331076

0 commit comments

Comments
 (0)