Expose CEL/OpenAPI validation rules as documentation to users

[howardjohn]

What would you like to be added:

Expose validation rules to reference documentation on the website (and/or so it shows up in kubectl explain

Why this is needed:

Users have asked for this: istio/istio#52225

[kovaxur]

Is there a reason why we have this limit in the API? Shouldn't the limits be enforced by the implementation of the gateway controller?

[youngnick]

The main reasons to have this in the API rather than the implementations are:

• Users get feedback earlier, at apply time, rather than having the apply succeed and then their configuration (or even worse, only some of their configuration), fail to work.
• Allowing implementations to control this themselves would allow implementations to choose their own numbers here, which would break portability - since a Gateway that was valid in one implementation might not be in another, based on the number of Listeners.

That's why this is done at the API level.

As to why there are limits - the main reasons are the etcd size limit (records stored in etcd can't be over a certain size, which is 1MB by default, and records that exceed this size simply won't be accepted by Kubernetes), and the complexity which would ensue if you could have n Listeners x m Attached Routes x l Route rules x o Matches inside Rules. The complexity goes up very quickly with that sort of multiplicative relationship.

[shaneutt]

/triage needs-information