From e239a7dd33f0941c295cd632b9f9c7ba887eac1c Mon Sep 17 00:00:00 2001 From: Kermit Alexander II Date: Thu, 30 Mar 2023 22:41:48 -0500 Subject: [PATCH] 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. --- .../custom-resource-definitions.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md index c439aa35df..2bcf40bef8 100644 --- a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md +++ b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md @@ -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()` 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: