doc: add direct resource API validation guide #2610
Conversation
yuwenma
force-pushed
the
CR-validation
branch
from
96b4e5b to
b23a6e2
Compare
yuwenma
force-pushed
the
CR-validation
branch
2 times, most recently
from
2500c33 to
ce526ba
Compare
yuwenma
force-pushed
the
CR-validation
branch
2 times, most recently
from
def5fda to
b3c020f
Compare
|
|
||
| # TL;DR | ||
|
|
||
| ConfigConnector Direct Resource shall have each `spec` field validated. |
There was a problem hiding this comment.
Is Config Connector supposed to be two words?
There was a problem hiding this comment.
Good call. Changed to Config Connector instead (here and else where).
|
|
||
| ### Immutable | ||
|
|
||
| Since most parent is a reference to another resource which can either be `<kind>Ref.external `or `<kind>Ref.name` , the immutable validation needs to be done at the controller validation level. For example, switching `<kind>Ref.external `and `<kind>Ref.name `are allowed if referring to the same resource. |
There was a problem hiding this comment.
Why < here ..? Formatting seems weird
There was a problem hiding this comment.
Good catch, I used an extension to convert the google doc to Markdown.
|
|
||
| Since most parent is a reference to another resource which can either be `<kind>Ref.external `or `<kind>Ref.name` , the immutable validation needs to be done at the controller validation level. For example, switching `<kind>Ref.external `and `<kind>Ref.name `are allowed if referring to the same resource. | ||
|
|
||
| See for general reference guide; |
There was a problem hiding this comment.
Yeah, because the reference doc is not merged. added a marker as reminder
|
|
||
| See for general reference guide; | ||
|
|
||
| See for parent validation with `status.externalRef`. |
|
|
||
| OpenAPI supports `oneOf`, `anyOf` and `allOf`. Thus, in theory these should be the CRD level rules. The Direct Resource CRD is auto-generated by controller-gen, which only reads the kubebuilder tag rules. But the kubebuilder tags [do not (and most likely won’t)](https://github.com/kubernetes-sigs/controller-tools/issues/461) support `oneOf`, `anyOf` or `allOf`. | ||
|
|
||
| To set this as CRD level rule, ConfigConnector shall build its own CRD transformer. Ideally, this could be a ConfigConnector tag similar to kubebuilder, but this requires integrating with controller-gen which is a non-trivial amount of work. Other options like webhook, OpenAPI schema modifier are not self-explaining and easy enough to use, considering that Direct Resource shall be open to external contributors. Thus, ConfigConnector does not use CRD level validation for `oneOf`, `anyOf` and `allOf`. |
There was a problem hiding this comment.
Not yet. We may want to build it someday. Defer to the requirements
|
|
||
| ## Rule 1: Resource Reference | ||
|
|
||
| ConfigConnector shall validate the resource reference based on |
There was a problem hiding this comment.
Based on what..? Seems to be missing info.
There was a problem hiding this comment.
ah, looks like Docs™ to Markdown cannot render the inline google doc. Fixed
yuwenma
force-pushed
the
CR-validation
branch
from
b3c020f to
192d260
Compare
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: jasonvigil 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:
Approvers can indicate their approval by writing |
google-oss-prow
bot
merged commit 5b1307c
into
GoogleCloudPlatform:master
Change description
Fixes #
Tests you have done
make ready-prto ensure this PR is ready for review.