feat: add HELMFILE_DISABLE_VALS env var to skip vals processing (#2471)

Signed-off-by: Jim Robinson <1643772+jimmyR@users.noreply.github.com>
Signed-off-by: yxxhero <aiopsclub@163.com>
Co-authored-by: yxxhero <aiopsclub@163.com>

docs/remote-secrets.md

@@ -54,4 +54,66 @@ service:
   login: svc-login # fetched from vault
   password: pass
 
-```
+```
+
+
+## Disabling vals
+
+You can disable the built-in vals processing using environment variables:
+
+### Pass-through mode
+
+Set `HELMFILE_DISABLE_VALS=true` to disable internal vals processing. Any `ref+` values will pass through unchanged, allowing you to validate them with a policy tool such as [conftest](https://www.conftest.dev/) before they are resolved:
+
+```bash
+HELMFILE_DISABLE_VALS=true helmfile template | conftest test -
+```
+
+### Strict mode
+
+Set `HELMFILE_DISABLE_VALS_STRICT=true` to disable vals and error if any `ref+` values are detected. This is useful when you want to prevent users from using vals references:
+
+```bash
+HELMFILE_DISABLE_VALS_STRICT=true helmfile sync
+# Error: vals is disabled via HELMFILE_DISABLE_VALS_STRICT environment variable
+```
+
+Note: If both are set, strict mode takes precedence.
+
+Strict mode detects any `ref+<provider>://` or `secretref+<provider>://` expression, including nested ones in maps and arrays. Plain strings that merely contain the text `ref+` (without a provider scheme) are not vals references and do not trigger the error.
+
+### Validating ref+ expressions with conftest
+
+You can use `HELMFILE_DISABLE_VALS=true` with [conftest](https://www.conftest.dev/) to validate that all `ref+` expressions conform to your security policy before processing them.
+
+Example rego policy (`policy/vals_refs.rego`):
+
+```rego
+package main
+
+allowed_refs := {
+    "ref+tfstates3://my-terraform-state/networking/eu-west-2/vpc/vpc_id",
+    "ref+tfstates3://my-terraform-state/networking/eu-west-2/vpc/private_subnet_ids",
+    "ref+tfstates3://my-terraform-state/platform/eu-west-2/eks/cluster_endpoint",
+}
+
+deny[msg] {
+    value := input[_]
+    startswith(value, "ref+tfstates3://")
+    not allowed_refs[value]
+    msg := sprintf("ref+ expression references an unapproved tfstates3 URI: %s", [value])
+}
+
+deny[msg] {
+    value := input[_]
+    startswith(value, "ref+")
+    not startswith(value, "ref+tfstates3://")
+    msg := sprintf("only tfstates3 ref+ expressions are permitted, got: %s", [value])
+}
+```
+
+Run against your rendered values:
+
+```bash
+HELMFILE_DISABLE_VALS=true helmfile template | conftest test -
+```

docs/templating.md

@@ -62,6 +62,8 @@ Helmfile uses some OS environment variables to override default behaviour:
 
 * `HELMFILE_DISABLE_INSECURE_FEATURES` - disable insecure features, expecting `true` lower case
 * `HELMFILE_DISABLE_RUNNER_UNIQUE_ID` - disable unique logging ID, expecting any non-empty value
+* `HELMFILE_DISABLE_VALS` - disable internal vals processing, `ref+` values pass through unchanged for use with external vals, expecting `true` lower case
+* `HELMFILE_DISABLE_VALS_STRICT` - disable vals and error if any `ref+` values are detected, expecting `true` lower case
 * `HELMFILE_SKIP_INSECURE_TEMPLATE_FUNCTIONS` - disable insecure template functions, expecting `true` lower case
 * `HELMFILE_USE_HELM_STATUS_TO_CHECK_RELEASE_EXISTENCE` - expecting non-empty value to use `helm status` to check release existence, instead of `helm list` which is the default behaviour
 * `HELMFILE_EXPERIMENTAL` - enable experimental features, expecting `true` lower case