kubernetes
/
community
mirror of https://github.com/kubernetes/community.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Describe ratcheting validation 

Signed-off-by: Maciej Szulik <soltysh@gmail.com>
This commit is contained in:
Maciej Szulik 2025-05-22 14:03:30 +02:00
parent 7b61a36b35
commit 0cb24d24e1
No known key found for this signature in database
GPG Key ID: F15E55D276FA84C4
1 changed files with 36 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
contributors/devel/sig-architecture/api_changes.md
View File

@ -39,6 +39,7 @@ found at [API Conventions](api-conventions.md).
- [Alpha, Beta, and Stable Versions](#alpha-beta-and-stable-versions)
- [Adding Unstable Features to Stable Versions](#adding-unstable-features-to-stable-versions)
- [New field in existing API version](#new-field-in-existing-api-version)
- [Ratcheting validation](#ratcheting-validation)
- [New enum value in existing field](#new-enum-value-in-existing-field)
- [New alpha API version](#new-alpha-api-version)
@ -1225,6 +1226,37 @@ In future Kubernetes versions:
}
```
#### Ratcheting validation
The word "ratcheting" refers to a process of incremental and often irreversible
progression or change, typically in a single direction. The term originates from
a mechanical device called a [ratchet](https://en.wikipedia.org/wiki/Ratchet_(device)),
which consists of a toothed wheel or bar and a pawl (a catch) that allows movement
in only one direction while preventing backward motion.
In the Kubernetes world, a ratcheting validation refers to an incremental tightening
of validation. This means we allow current resources to either remain invalid or
be fixed, but all new resources must pass the validation. The following table
best illustrates these cases:
| Resource | Validation |
|-------------|------------|
| new valid | succeeds |
| new invalid | fails |
| old valid | succeeds |
| old invalid | succeeds |
A good example of ratcheting validation was introduced in [this pull request](https://github.com/kubernetes/kubernetes/pull/130233).
It introduced validation for the optional `.spec.serviceName` field for StatefulSet,
such that old resources (nregarldess of whether they are valid or not) will succeed
the validation check, but new resources must adhere to stricter validation rules
for that field. The relevant changes include:
- A struct with options passed to validation methods (here it's the `StatefulSetValidationOptions`
struct, with `AllowInvalidServiceName` to handle this specific case).
- Appropriate changes inside `Validate*` methods which ensure the rules from the
table above are implemented.
- Tests ensuring all the cases from the above table are covered.
#### New enum value in existing field
A developer is considering adding a new allowed enum value of `"OnlyOnTuesday"`