Update doc for KEP 2876 #42120

cici37 · 2023-07-20T23:16:39Z

No description provided.

netlify · 2023-07-20T23:16:44Z

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Name	Link
🔨 Latest commit	`61d5b61`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/64bf469e545eb1000802d1af

cici37 · 2023-07-20T23:17:38Z

/sig api-machinery

cici37 · 2023-07-20T23:18:08Z

/assign @jpbetz
for tech review. Thank you!

windsonsea

Some text suggestions

content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md

cici37 · 2023-07-21T17:06:08Z

@windsonsea All comments have been addressed. Thank you

sftim

Thanks

I have a few suggestions, and also I'd like to know why setting fieldPath benefits people who consume the API that the CRD defines.

content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md

sftim · 2023-07-23T16:41:11Z

content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md

+#### The reason and fieldPath fields
+
+Besides the `message` and `messageExpression` fields, which defines the string reported for a validation rule failure,
+we have also added two more fields under `validation`:
+- `reason` field which allows user to specify a machine-readable validation failure reason when a request fails this validation rule.
+- `fieldPath` field which specify the field path returned when the validation fails.


We like timeless documentation: please avoid “we have also added”.

Suggested change

#### The reason and fieldPath fields

Besides the `message` and `messageExpression` fields, which defines the string reported for a validation rule failure,

we have also added two more fields under `validation`:

- `reason` field which allows user to specify a machine-readable validation failure reason when a request fails this validation rule.

- `fieldPath` field which specify the field path returned when the validation fails.

Setting `messageExpression` is optional.

#### The `message` field {#field-message}

If you want to set a static message, you can supply `message` rather than `messageExpression`.

The value of `message` is used as an opaque error string if validation fails.

Setting `message` is optional.

#### The `reason` field {#field-reason}

You can add a machine-readable validation failure reason within a `validation`, to be returned

whenever a request fails this validation rule.



Setting `reason` is optional.

#### The `fieldPath` field {#field-field-path}

You can specify the path to the data that have failed to validate.

NB. Can we explain why it's useful to specify a fieldPath?

Thank you for the review! I have updated the doc to align with the suggested format.
For fieldPath, we wanna user to be able to specify the accurate path when err returned instead of always using the path which self scoped. It is very usefully especially when do cross fields validation and user wanna the returned err indicate the path the err occurred. For example, if user trying to say a field has to be a different value than another field, something like self.foo.test.a != self.b. The validation has to be scoped high enough to have access to both field a and b but we wanna the returned err path to be on a, in this case having a fieldPath .foo.test.a will be great.
Hope that would make sense to you. Thank you^^

Edit: I have also added explain in the doc with the example. Thank you

content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md

jpbetz · 2023-07-25T18:15:02Z

/approve
For technical content. This all looks accurate to me. Thanks @cici37

jpbetz · 2023-07-25T18:15:33Z

/lgtm

k8s-ci-robot · 2023-07-25T18:15:39Z

LGTM label has been added.

Git tree hash: b052a7422411ba0ecde37f95cb38283d837143ba

cici37 · 2023-07-25T18:17:11Z

@sftim The PR has done with technical review and all comments have been addressed. It is ready for doc approval. Thank you!

sftim

/approve

k8s-ci-robot · 2023-08-01T23:12:51Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jpbetz, sftim

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/en/OWNERS~~ [sftim]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

Update doc for KEP 2876

Update doc for KEP 2876

0f66ee5

k8s-ci-robot added this to the 1.28 milestone Jul 20, 2023

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Jul 20, 2023

k8s-ci-robot requested review from roycaihw and sttts July 20, 2023 23:16

k8s-ci-robot added language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Jul 20, 2023

cici37 mentioned this pull request Jul 20, 2023

[KEP-2876] Placeholder doc PR for kep 2876 #42043

Closed

k8s-ci-robot added the sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. label Jul 20, 2023

k8s-ci-robot assigned jpbetz Jul 20, 2023

windsonsea reviewed Jul 21, 2023

View reviewed changes

Address comments

4391c3b

sftim reviewed Jul 23, 2023

View reviewed changes

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Jul 25, 2023

Address comments

61d5b61

cici37 force-pushed the 2876 branch from 36c1ebb to 61d5b61 Compare July 25, 2023 03:50

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jul 25, 2023

sftim reviewed Aug 1, 2023

View reviewed changes

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Aug 1, 2023

k8s-ci-robot merged commit 9ffbb3e into kubernetes:dev-1.28 Aug 1, 2023

carlory mentioned this pull request Aug 4, 2023

CRD Validation Expression Language kubernetes/enhancements#2876

Closed

21 tasks

Rishit-dagli pushed a commit to Rishit-dagli/website that referenced this pull request Aug 12, 2023

Merge pull request kubernetes#42120 from cici37/2876

69b7e82

Update doc for KEP 2876

cici37 deleted the 2876 branch August 14, 2023 18:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update doc for KEP 2876 #42120

Update doc for KEP 2876 #42120

cici37 commented Jul 20, 2023

netlify bot commented Jul 20, 2023 •

edited

Loading

cici37 commented Jul 20, 2023

cici37 commented Jul 20, 2023

windsonsea left a comment

cici37 commented Jul 21, 2023

sftim left a comment

sftim Jul 23, 2023

cici37 Jul 25, 2023

cici37 Jul 25, 2023

jpbetz commented Jul 25, 2023

jpbetz commented Jul 25, 2023

k8s-ci-robot commented Jul 25, 2023

cici37 commented Jul 25, 2023

sftim left a comment

k8s-ci-robot commented Aug 1, 2023

-#### The reason and fieldPath fields
-Besides the `message` and `messageExpression` fields, which defines the string reported for a validation rule failure,
-we have also added two more fields under `validation`:
-- `reason` field which allows user to specify a machine-readable validation failure reason when a request fails this validation rule.
-- `fieldPath` field which specify the field path returned when the validation fails.
+Setting `messageExpression` is optional.
+#### The `message` field {#field-message}
+If you want to set a static message, you can supply `message` rather than `messageExpression`.
+The value of `message` is used as an opaque error string if validation fails.
+Setting `message` is optional.
+#### The `reason` field {#field-reason}
+You can add a machine-readable validation failure reason within a `validation`, to be returned
+whenever a request fails this validation rule.
+<!-- an example here would be nice, but is hard to add using GitHub suggestions -->
+Setting `reason` is optional.
+#### The `fieldPath` field {#field-field-path}
+You can specify the path to the data that have failed to validate.

Update doc for KEP 2876 #42120

Update doc for KEP 2876 #42120

Conversation

cici37 commented Jul 20, 2023

netlify bot commented Jul 20, 2023 • edited Loading

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

cici37 commented Jul 20, 2023

cici37 commented Jul 20, 2023

windsonsea left a comment

Choose a reason for hiding this comment

cici37 commented Jul 21, 2023

sftim left a comment

Choose a reason for hiding this comment

sftim Jul 23, 2023

Choose a reason for hiding this comment

cici37 Jul 25, 2023

Choose a reason for hiding this comment

cici37 Jul 25, 2023

Choose a reason for hiding this comment

jpbetz commented Jul 25, 2023

jpbetz commented Jul 25, 2023

k8s-ci-robot commented Jul 25, 2023

cici37 commented Jul 25, 2023

sftim left a comment

Choose a reason for hiding this comment

k8s-ci-robot commented Aug 1, 2023

netlify bot commented Jul 20, 2023 •

edited

Loading