build: add variable validation in bake

Signed-off-by: David Karlsson <[email protected]>

Author: dvdksn

content/manuals/build/bake/overrides.md

@@ -288,43 +288,63 @@ which is the short commit hash generated by `git rev-parse --short HEAD`.
 Overriding non-string variables with environment variables is supported. Values
 passed as environment variables are coerced into suitable types first.
 
-The following example defines a `PORT` variable with a default value of `8080`.
-The `default` target uses a [ternary operator](expressions.md#ternary-operators)
-to set the `PORT` variable to the value of the environment variable `PORT`
-if it is greater than `1024`, otherwise it uses the default value.
-
-In this case, the `PORT` variable is coerced to an integer before the ternary
-operator is evaluated.
+The following example defines a `PORT` variable. The `backend` target uses the
+`PORT` variable as-is, and the `frontend` target uses the value of `PORT`
+incremented by one.
 
 ```hcl
-default_port = 8080
-
 variable "PORT" {
-  default = default_port
+  default = 3000
 }
 
-target "default" {
+group "default" {
+  targets = ["backend", "frontend"]
+}
+
+target "backend" {
   args = {
-    PORT = PORT > 1024 ? PORT : default_port
+    PORT = PORT
+  }
+}
+
+target "frontend" {
+  args = {
+    PORT = add(PORT, 1)
   }
 }
 ```
 
-Attempting to set the `PORT` variable with a value less than `1024` will result
-in the default value being used.
+Overriding `PORT` using an environment variable will first coerce the value
+into the expected type, an integer, before the expression in the `frontend`
+target runs.
 
 ```console
-$ PORT=80 docker buildx bake --print
+$ PORT=7070 docker buildx bake --print
 ```
 
 ```json
 {
-  "target": {
+  "group": {
     "default": {
+      "targets": [
+        "backend",
+        "frontend"
+      ]
+    }
+  },
+  "target": {
+    "backend": {
+      "context": ".",
+      "dockerfile": "Dockerfile",
+      "args": {
+        "PORT": "7070"
+      }
+    },
+    "frontend": {
       "context": ".",
       "dockerfile": "Dockerfile",
       "args": {
-        "PORT": "8080"
+        "PORT": "7071"
       }
     }
   }

content/manuals/build/bake/variables.md

@@ -78,6 +78,50 @@ $ docker buildx bake --print
 }
 ```
 
+## Validating variables
+
+To verify that the value of a variable conforms to an expected type, value
+range, or other condition, you can define custom validation rules using the
+`validation` block.
+
+In the following example, the `PORT` variable must be set to 1024 or a higher
+value.
+
+```hcl
+variable "PORT" {
+  default = 3000
+  validation {
+    condition = PORT >= 1024
+    error_message = "PORT must be 1024 or higher"
+  }
+}
+```
+
+If the `condition` expression evaluates to `false`, the variable value is
+considered invalid, whereby the build invocation fails and `error_message` is
+emitted.
+
+Values are coerced into the expected type before the validation is set. This
+ensures that any overrides set with environment variables work as expected.
+
+### Validate multiple conditions
+
+To evaluate more than one condition, define multiple `validation` blocks for
+the variable. All conditions must be `true`.
+
+```hcl
+variable "VAR" {
+  validation {
+    condition = VAR != ""
+    error_message = "VAR must not be empty"
+  }
+  validation {
+    condition = sanitize(VAR) == VAR
+    error_message = "VAR can only contain [a-zA-Z0-9-_]"
+  }
+}
+```
+
 ## Escape variable interpolation
 
 If you want to bypass variable interpolation when parsing the Bake definition,