docs(declarative-validation): migrate declarative validation docs from k/website#726
Conversation
k8s-ci-robot
added
size/XL
|
| Name | Link |
|---|---|
| 🔨 Latest commit | 1be6ef5 |
aaron-prindle
force-pushed
the
migrate-dv-docs
branch
from
1be6ef5 to
38775d3
Compare
|
|
||
| Declarative validation lets Kubernetes API authors put common validation rules next to the versioned API types they apply to. Instead of hand-writing every basic check in `validation.go`, API authors add `+k8s:` tags to `types.go`, and `validation-gen` turns those tags into Go validation code. | ||
|
|
||
| This does not completely replace handwritten validation as cross-field checks, compatibility quirks, and rules that cannot be expressed as tags still use handwritten validation code. The goal is to move the simple, repeated, field-local rules into a form that is easier to review and harder to accidentally drift. |
There was a problem hiding this comment.
Removed now - the intent was the explain common cases of keeping hand-written to the user as we do support some specific cross-field cases I have removed this now and kept this statement more generic to explain that complex/bespoke cases still need hand-written validation logic
| Use this as a quick pass when reviewing a PR that adds declarative validation: | ||
|
|
||
| - Are the tags on the versioned API types? | ||
| - Did the PR regenerate `zz_generated.validations.go`? |
There was a problem hiding this comment.
Are the test artifacts generated properly?
There was a problem hiding this comment.
Updated to include this now:
- Did the PR regenerate
test/declarative_validation/<group>/<kind>/zz_generated.validations.main_test.go? - Did the PR regenerate
test/declarative_validation/<group>/<kind>/zz_generated.validations.<api-version-*>_test.go?
|
|
||
| - Put validation tags on versioned API types. | ||
| - Run `hack/update-codegen.sh` after adding or changing tags. | ||
| - For migrations of existing handwritten validation, use lifecycle wrappers so the generated result can soak before it becomes authoritative. |
There was a problem hiding this comment.
You mentioned lifecycle wrappers . Didn't talk about explicit about it? should we talk about the lifcycle of migration in this doc?
There was a problem hiding this comment.
The goal of this is to port the kubernetes/website documentation which has already been approved to this page with minor updates so that it is still correct as of 5/22/2026 code changes.
I have removed this specific line now but kept some of the lifecycle related text in the into/feature-gate section as some explanation is necessary to explain what the feature gates do.
aaron-prindle
force-pushed
the
migrate-dv-docs
branch
from
338262a to
6d6d3b2
Compare
| @@ -0,0 +1,792 @@ | |||
| --- | |||
| content_type: "reference" | |||
There was a problem hiding this comment.
nit: I don't think we use this field on the contributor docs. Not harmful, but also OK to remove.
There was a problem hiding this comment.
Ah thanks, removed now
lmktfy
left a comment
lmktfy
left a comment
There was a problem hiding this comment.
I think we should merge this. Even if not perfect, merging this will be a big improvement on what we have today.
aaron-prindle
force-pushed
the
migrate-dv-docs
branch
from
6d6d3b2 to
f299168
Compare
|
/lgtm |
k8s-ci-robot
added
the
lgtm
|
@lmktfy - we have approval for the content of the document now from @lalitc375. PTAL, thanks! |
|
/assign @lmktfy |
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: aaron-prindle, jberkus The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
approved
5 participants
This adds a contributor-site reference page for Kubernetes declarative API validation.
PR migrates the core declarative validation material from
kubernetes/website, rewrites it for API contributors, and updates the tag catalog against the currentvalidation-genimplementation so it is up to date w.r.t existing tags, stability levels, etc.