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

Documentation for messageExpression update to KEP-2876 (#40019) 

* Add messageExpression documentation.

* Apply feedback on wording.

* Add info about casting to string.

* Use "evaluates to an error" to avoid ambiguous wording around "fails."

* Revise wording around string casting.
This commit is contained in:
Kermit Alexander II 2023-03-30 22:41:48 -05:00 committed by GitHub
parent d6350c03bb
commit e239a7dd33
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 31 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1035,6 +1035,37 @@ xref: [CEL types](https://github.com/google/cel-spec/blob/v0.6.0/doc/langdef.md#
[OpenAPI types](https://swagger.io/specification/#data-types),
[Kubernetes Structural Schemas](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema).
#### The messageExpression field
Similar to the `message` field, which defines the string reported for a validation rule failure,
`messageExpression` allows you to use a CEL expression to construct the message string.
This allows you to insert more descriptive information into the validation failure message.
`messageExpression` must evaluate a string and may use the same variables that are available to the `rule`
field. For example:
```yaml
x-kubernetes-validations:
- rule: "self.x <= self.maxLimit"
messageExpression: '"x exceeded max limit of " + string(self.maxLimit)'
```
Keep in mind that CEL string concatenation (`+` operator) does not auto-cast to string. If
you have a non-string scalar, use the `string(<value>)` function to cast the scalar to a string
like shown in the above example.
`messageExpression` must evaluate to a string, and this is checked while the CRD is being written. Note that it is possible
to set `message` and `messageExpression` on the same rule, and if both are present, `messageExpression`
will be used. However, if `messageExpression` evaluates to an error, the string defined in `message`
will be used instead, and the `messageExpression` error will be logged. This fallback will also occur if
the CEL expression defined in `messageExpression` generates an empty string, or a string containing line
breaks.
If one of the above conditions are met and no `message` has been set, then the default validation failure
message will be used instead.
`messageExpression` is a CEL expression, so the restrictions listed in [Resource use by validation functions](#resource-use-by-validation-functions) apply. If evaluation halts due to resource constraints
during `messageExpression` execution, then no further validation rules will be executed.
#### Validation functions {#available-validation-functions}
Functions available include: