Variable Substitution#

Kyverno's variable substitution engine resolves {{ expression }} placeholders in policy rules against the evaluation context before the rule is applied. The engine is implemented in pkg/engine/variables/vars.go and drives all rule types — validate, mutate, generate, and preconditions.

Entry Points#

All substitution flows eventually call the private substituteAll() 1, which runs two passes in order:

1. Reference substitution (substituteReferences) — resolves $(path) self-referential pointer expressions against the current document structure 2.
2. Variable substitution (substituteVars) — resolves {{ jmespath_expr }} patterns against the evaluation context via a pluggable VariableResolver 3.

Public entry points and their use cases:

Pattern Detection#

Variable tokens are identified by regex patterns defined in pkg/engine/variables/regex/vars.go:

• RegexVariables — matches {{...}} at start-of-string or preceded by a non-backslash character 4.
• RegexVariableInit — matches {{...}} anchored at position 0, used to distinguish a variable that occupies the entire value from one that is embedded mid-string 5.
• RegexReferences — matches $(...) self-reference syntax 6.
• RegexEscpReferences — matches \$(...) escaped references that should pass through without resolution 7.

Core Substitution Loop#

substituteVariablesIfAny is the jsonUtils.Action applied to every leaf node during traversal. Its key behaviors:

• Whole-node replacement: if the entire leaf value equals the variable expression, the resolved value is returned directly as its original type (e.g., a map or slice stays a map or slice) 8.
• Embedded substitution: if the variable is embedded in a larger string, the resolved value is JSON-marshalled and string-spliced into the pattern via substituteVarInPattern.
• Nested iteration: after each substitution pass the string is re-scanned for new variables, enabling chained resolution 9.
• Delete request rewriting: request.object references are automatically rewritten to request.oldObject for DELETE admission operations 10.
• @ current-document shorthand: the @ variable is expanded into the JMESPath for the current node's path within the policy document 11.

Shallow Substitution ({{- ... }})#

Prefixing an expression with a hyphen — {{- expr }} — enables shallow substitution. The hyphen is detected by replaceBracesAndTrimSpaces, which strips the {{- ... }} delimiters and returns isShallow = true.

When shallow mode is active 12:

1. Any {{ sequences inside the resolved value are escaped to \{{ — preventing recursive variable expansion of content that may itself contain brace-delimited template strings.
2. The substitution loop is terminated after one pass (vars = []string{}), skipping the re-scan for nested variables.
3. After all variable processing completes, \{{ is unescaped back to {{ 13.

Purpose: this lets a field whose resolved value contains Kubernetes-native or app-level template syntax (e.g., https://example.com/{{user_id}}) pass through without Kyverno attempting to resolve the inner braces as JMESPath 14.

Known Bugs and Fixes#

Unsafe type assertion in shallow substitution (PR #12039 / #13805)#

Before PR #12039, the shallow-substitution escaping line was:

if shallowSubstitution {
    substitutedVar = strings.ReplaceAll(substitutedVar.(string), "{{", "\\{{")
}

The bare assertion substitutedVar.(string) panics when the resolver returns nil. The fix added a nil guard — if shallowSubstitution && substitutedVar != nil 15 — making the path safe. PR #13805 cherry-picks the same fix to the release branch 16.

forEach patchesJson6902 panic (PR #15887)#

A separate bare type assertion in the forEach mutation handler (pkg/engine/mutate/mutation.go) — fe["patchesJson6902"].(string) — would panic when a variable inside patchesJson6902 resolved to nil, crashing the background controller into a CrashLoopBackOff 17. The fix changed this to a safe assertion:

jsonPatch, _ := fe["patchesJson6902"].(string)

This is tracked under security advisory GHSA-fpjq-c37h-cqcv 17.

Template literals in resource fields misinterpreted as JMESPath (Issue #11865)#

When a resource being validated contains application-level template strings like {{user_id}} in environment variable values or annotations, Kyverno's substitution engine attempts to resolve them as JMESPath expressions and fails with Unknown key "user_id" in path 14. The {{- expr }} shallow substitution syntax was intended as a workaround but only helps when applied within the policy itself — it has no effect on literal brace sequences that already exist in the incoming resource object and are processed as part of an apiCall data payload.

Key Files#