From f187c3757466d0db9bd865eb8dcd2d8a97e65a3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20=C5=81askawiec?= Date: Sun, 15 Nov 2026 08:43:07 +0100 Subject: [PATCH] docs(next): document supported HCL helper functions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Sebastian Ɓaskawiec --- docs/reference/next/bundle-uds-hcl.mdx | 2 +- docs/reference/next/config-uds-hcl.mdx | 2 + docs/reference/next/helper-functions.mdx | 51 ++++++++++++++++++++++++ 3 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 docs/reference/next/helper-functions.mdx diff --git a/docs/reference/next/bundle-uds-hcl.mdx b/docs/reference/next/bundle-uds-hcl.mdx index 7cbcb4ada..26ccdb15a 100644 --- a/docs/reference/next/bundle-uds-hcl.mdx +++ b/docs/reference/next/bundle-uds-hcl.mdx @@ -97,7 +97,7 @@ package "app" { } ``` -Local names must be unique. References to an undefined local and cyclic local dependencies fail during parsing. The `file(path)` function is also available in a file-backed bundle definition. Relative paths are resolved from the directory containing `bundle.uds.hcl`; absolute paths are used as-is. The function returns regular UTF-8 file contents. +Local names must be unique. References to an undefined local and cyclic local dependencies fail during parsing. The `file(path)` function is also available in a file-backed bundle definition. Relative paths are resolved from the directory containing `bundle.uds.hcl`; absolute paths are used as-is. The function returns regular UTF-8 file contents. See the [HCL helper function reference](/cli/reference/next/helper-functions/) for supported contexts and error behavior. ## `package ""` diff --git a/docs/reference/next/config-uds-hcl.mdx b/docs/reference/next/config-uds-hcl.mdx index 6c7091ef2..59aa290ae 100644 --- a/docs/reference/next/config-uds-hcl.mdx +++ b/docs/reference/next/config-uds-hcl.mdx @@ -7,6 +7,8 @@ sidebar: `config.uds.hcl` supplies consumer-owned settings when UDS CLI Next operates on a bundle. It is read with `--config` and is not part of the bundle artifact. Use it for settings that can change between environments, such as registry options, signature trust material, and deploy-time variables. +For exact `file()` and `sensitive()` behavior and supported HCL contexts, see the [HCL helper function reference](/cli/reference/next/helper-functions/). + This file is distinct from `bundle.uds.hcl`, which defines the bundle, and `defaults.uds.hcl`, which stores bundle-provided default variables. ## Supported top-level attributes diff --git a/docs/reference/next/helper-functions.mdx b/docs/reference/next/helper-functions.mdx new file mode 100644 index 000000000..b3430ea44 --- /dev/null +++ b/docs/reference/next/helper-functions.mdx @@ -0,0 +1,51 @@ +--- +title: Next HCL helper functions +description: Reference the helper functions available in file-backed Next bundle, defaults, and config HCL files. +sidebar: + order: 4.600 +--- + +Next supports `file()` in file-backed `bundle.uds.hcl`, `defaults.uds.hcl`, and `config.uds.hcl` inputs. It supports `sensitive()` only for values in the `variables` object of `defaults.uds.hcl` and `config.uds.hcl`. These are the only registered HCL helper functions; `base64encode()` and `base64decode()` are not available. These HCL functions do not extend Go text/template functions used in package values files. + +| Function | Supported context | +|---|---| +| `file(path)` | Expressions in file-backed `bundle.uds.hcl`; `variables` in file-backed `defaults.uds.hcl`; string-valued expressions throughout file-backed `config.uds.hcl`, including options and trust fields. | +| `sensitive(value)` | Values inside `variables` in `defaults.uds.hcl` and `config.uds.hcl`. | + +## `file(path)` + +`file(path)` reads a regular UTF-8 file and returns its contents as a string. The argument must be a string. Relative paths resolve from the directory containing the HCL file; absolute paths are used as-is. The CLI process must be able to access the path. + +Use it in bundle expressions, including `locals`, metadata, and package fields. In `config.uds.hcl`, a trust field can load a public key. The example needs `keys/cosign.pub` under the directory containing the config file: + +```hcl title="config.uds.hcl" +signature_verification { + public_key = file("keys/cosign.pub") +} +``` + +The path must exist and identify a regular file containing valid UTF-8. A missing or unreadable file, directory, invalid UTF-8, or invalid argument makes HCL evaluation fail. `file()` is unavailable when parsing in-memory bundle or defaults bytes because those inputs have no source directory. + +## `sensitive(value)` + +`sensitive(value)` accepts one value of any supported variable type, returns that value unchanged, and marks it sensitive. Use it inside `variables` in `config.uds.hcl` or `defaults.uds.hcl`: + +```hcl title="config.uds.hcl" +variables = { + password = sensitive(file("secrets/password.txt")) + registry = { token = sensitive("replace-me") } +} +``` + +For the file-backed example, create `secrets/password.txt` beside `config.uds.hcl`. + +A mark anywhere inside a top-level variable marks that entire variable. Sensitivity metadata survives defaults, config, and `--set` merging. `--set` values cannot call `sensitive()`; mark the corresponding value in a HCL variables file. + +Sensitivity is metadata, not encryption. The value passed to templates and Zarf is unchanged. Marked values are omitted from CLI-managed deployment diagnostics and errors, and exact known values are redacted from standard logs. Redaction can miss transformed or partial values, or redact matching text in unrelated logs; direct stdout/stderr and explicit loggers that bypass the standard logger are not covered. Materializing `sensitive(file(...))` embeds the file contents as plaintext while preserving the sensitivity mark. + +Calling `sensitive()` outside the `variables` object in those two files is invalid. In particular, it is not available in `bundle.uds.hcl` or structured config fields such as `options` and `signature_verification`. + +## Related documentation + +- [Bundle definition reference](/cli/reference/next/bundle-uds-hcl/) - Bundle fields, locals, and package expressions. +- [Config reference](/cli/reference/next/config-uds-hcl/) - Deploy-time options, trust settings, variables, and precedence.