KEP-2876: Add messageExpression (kubernetes#3747)

* Update with messageExpression info.

* Add information on variable availability/runtime cost.

* Allow both message and messageExpression to be present.

* CRD writes will succeed if both message and messageExpression are given.

* Add information on string.format checks.

* Fail if runtime cost limit is exceeded.

* Remove mention of admission policy KEP update.

* Discard messageExpression if it doesn't statically eval to a string.

* messageExpression must statically evaluate to a string, and also any runtime messageExpression errors are logged.

* Reorganize `messageExpression` rules section.

* Indent messageExpression-related topics.

* Update messageExpression example to use proper string.format syntax.

Author: DangerOnTheRanger

keps/sig-api-machinery/2876-crd-validation-expression-language/README.md

@@ -230,7 +230,7 @@ kind: CustomResourceDefinition
         spec:
           x-kubernetes-validations: 
             - rule: "self.minReplicas <= self.maxReplicas"
-              message: "minReplicas cannot be larger than maxReplicas"
+              messageExpression: "'minReplicas (%d) cannot be larger than maxReplicas (%d)'.format([self.minReplicas, self.maxReplicas])"
           type: object
           properties:
             minReplicas:
@@ -258,9 +258,26 @@ Example Validation Rules:
 
 
 - Each validator may have multiple validation rules.
-
 - Each validation rule has an optional 'message' field for the error message that
 will be surfaced when the validation rule evaluates to false.
+- As an alternative to the `message` field, there is also a
+`messageExpression` field that represents a CEL expression that evaluates to a
+string that will be used when the validation rule evaluates to false.
+  - There are several validation rules for the `messageExpression` field:
+    - The  `messageExpression` field must statically evaluate to a string.
+    - There are several compile-time checks performed on CEL's `string.format` function that can affect `messageExpression`:
+      - If the formatting string passed to `string.format` is a constant, then the formatting string will be checked at
+        compile-time that it parses correctly.
+      - If the `arg` array passed to `string.format` is a literal, and the formatting string is a constant, then
+        at compile-time `arg`'s cardinality will be checked against the formatting string. Passing too few/too many arguments
+        compared to what the formatting string expects is not allowed.
+      - Type checking of each individual  argument in `arg` will be done against what is expected in the formatting string 
+        to ensure the proper formatting clauses are used on each member of arg.
+  - The runtime cost limit must not be exceeded during `messageExpression` execution (executing `messageExpression` counts towards that limit). 
+  - If `messageExpression` results in a runtime error, then `message` will be used instead if non-empty. If `message`
+    is empty, then the default error message is used instead. In either case (if `message` or the default error message is 
+    used) the CEL error that `messageExpression` failed with will be logged.
+  - If both `message` and `messageExpression` are present, `messageExpression` will take priority.
 
 - The validator will be scoped to the location of the `x-kubernetes-validations`
 extension in the schema. In the above example, the validator is scoped to the