docs(values,templating): add reference and best practices pages #4368

mkcp · 2025-11-14T20:29:46Z

Description

Add reference and best practices documentation for package values and templating.

Related Issue

Relates to #3946

Checklist before merging

Test, docs, adr added or updated as needed
Contributor Guide Steps followed

Signed-off-by: Kit Patella <[email protected]>

netlify · 2025-11-14T20:29:52Z

✅ Deploy Preview for zarf-docs ready!

Name	Link
🔨 Latest commit	`0b8a742`
🔍 Latest deploy log	https://app.netlify.com/projects/zarf-docs/deploys/695ff475545bba00084d0c26
😎 Deploy Preview	https://deploy-preview-4368--zarf-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

codecov · 2025-11-14T20:35:26Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
see 52 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Signed-off-by: Kit Patella <[email protected]>

…em rather than duplicating the same content Signed-off-by: Kit Patella <[email protected]>

Signed-off-by: Kit Patella <[email protected]>

…nd config file imports and --set-values Signed-off-by: Kit Patella <[email protected]>

Signed-off-by: Kit Patella <[email protected]>

a1994sc

LGTM

brandtkeller · 2025-11-17T14:33:30Z

site/src/content/docs/best-practices/package-values.mdx

+
+See the [Templating Reference](/ref/templating/) for complete function documentation.
+
+## Avoid Sensitive Data in Values Files


Generally this is good advice but I do think it is worth calling out that values files will be the primary mechanism for orchestrating sensitive values. Given the declarative delivery model - all secrets have to originate from somewhere.

It will be important for sunsetting zarf variables as it will provide a way to break these out of zarf config files.

We may want to delineate between sensitive values defaults getting "baked" into the package - for which you had a few good examples of different environment overrides that would align to that story telling.

This is a good callout - I rewrote this section to highlight not committing secrets to package defaults, and gave examples of how they can be passed in.

brandtkeller · 2025-11-17T14:35:21Z

site/src/content/docs/best-practices/templating.mdx

+
+## Common Errors and Solutions
+
+### Template Parse Errors


++ I like that we are making errors in docs discoverable.

site/src/content/docs/ref/package-values.mdx

brandtkeller · 2025-11-17T14:47:18Z

site/src/content/docs/ref/templating.mdx

+
+:::
+
+Zarf supports Go template syntax and `text/template` engine with powerful features including control flow and functions. Zarf includes the full library of [Sprig functions](http://masterminds.github.io/sprig/) and some builtins for dynamic configuration in manifests, files, and actions. This powerful templating system enables complex transformations, conditional logic, and data manipulation beyond simple string substitution.


This may be a good place to identify what is different between zarf templating and helm templating.

I added some notes about the similarities and differences here

AustinAbro321

Leaving comments on the review so far, I'll aim to do a review on the ref section at another point

AustinAbro321 · 2025-11-17T14:55:28Z

site/src/content/docs/best-practices/package-values.mdx

Across this PR we reference zarf package inspect, zarf dev inspect and using the values schema however none of these features are merged into Zarf as of yet. IMO we should wait until a feature is merged before documenting it

I believe that this is addressed now

AustinAbro321 · 2025-11-17T15:17:42Z

site/src/content/docs/best-practices/templating.mdx

+
+## Provide Defaults for Optional Values
+
+Use the `default` function to provide fallback values:


While defaults are generally a good practice, I don't think they really make sense in the context of Zarf since we always validate that there is a value for template. I could be missing scenarios but AFAIK there is no way for the default to come into play

site/src/content/docs/best-practices/package-values.mdx

site/src/content/docs/best-practices/templating.mdx

AustinAbro321 · 2025-11-17T15:37:30Z

site/src/content/docs/best-practices/templating.mdx

+data:
+  # Numbers must be strings in ConfigMaps
+  port: {{ .Values.app.port | toString | quote }}
+  replicas: {{ .Values.app.replicas | toString | quote }}
+
+  # Booleans to strings
+  debug: {{ .Values.app.debug | toString | quote }}
+
+# ❌ RISKY: Type mismatch errors
+data:
+  port: {{ .Values.app.port }}  # May fail if port is a number


Numbers don't have to be strings in configmaps, Kubernetes will store either

Thoughts on generalizing the example a bit then, like "explicit type conversion may be necessary?"

AustinAbro321 · 2025-11-17T15:39:56Z

site/src/content/docs/best-practices/templating.mdx

+
+## Handle Missing Values Gracefully
+
+Protect against missing or nil values:


I don't think this advice makes sense in the context of Zarf, the "good" example will still fail if .values.monitoring.enabled is not set

Yeah I agree, I don't like encouraging conditional blocks like this either. Removed in latest

site/src/content/docs/best-practices/templating.mdx

Signed-off-by: Kit Patella <[email protected]>

brandtkeller

Minor comments as I iterate through some tests - otherwise I like how clean and comprehensive this is.

brandtkeller · 2026-01-09T14:35:18Z

site/src/content/docs/best-practices/package-values.mdx

+
+## Do Not Commit Sensitive Values in Package
+
+Values are the best way to pass secrets into your Zarf package, but those secrets should not be baked into the values files a package is created with:


brandtkeller · 2026-01-09T14:50:43Z

site/src/content/docs/ref/package-values.mdx

+
+:::
+
+Package Values provide a familiar way to define and reusable configuration data in your Zarf packages. Unlike the legacy [Variables and Constants](/ref/values/) system that uses string substitution with `###ZARF_VAR_###` syntax, Package Values uses Go templates with access to structured data and types, [go's templating engine](https://pkg.go.dev/text/template), and custom functions like those offered by [Sprig](/ref/templating/).


Minor grammatical item:

a familiar way to define and reusable configuration data

brandtkeller · 2026-01-09T14:56:46Z

site/src/content/docs/ref/package-values.mdx

+- `name`: The path where the value should be stored (e.g., `database.password`)
+- `type`: The format of the output - `string` (default), `json`, or `yaml`
+
+Values set via `setValues` are available in subsequent actions and manifests within the same deployment.


Making a note in-passing that an example here may be valuable (is that a pun?) - will resolve if included elsewhere.

brandtkeller · 2026-01-09T15:05:01Z

site/src/content/docs/best-practices/package-values.mdx

+  order: 10
+---
+
+This guide provides best practices for using [Package Values](/ref/package-values/) in your Zarf packages.


It's briefly touched on in the ref document - but If I think of the ref document as the "how" and best practices as the "why" - I wonder if a good addition here could be the mention of why the use of granular sourcePath/targetPath. Security considerations and treating it as an allow list as well as traceability when we think about potential collisions with on-deployment values files and the future of imports.

brandtkeller · 2026-01-09T15:20:37Z

site/src/content/docs/ref/package-values.mdx

+  --features="values=true" \
+  -f custom-values.yaml
+
+# Multiple values files (later files override earlier ones)


Is the shorthand for this flag -v? (doesn't exist in dev deploy yet but -f is used already in dev deploy)

AustinAbro321 · 2026-01-09T17:29:25Z

site/src/content/docs/ref/templating.mdx

+
+## Using Helm charts within Zarf:
+- Helm templating happens inside chart templates (standard Helm behavior)
+- Zarf templating happens at the package level


The sentence Zarf templating happens a the package level, feels like it doesn't quite fit. In the flow of deploying a Helm chart, Zarf templating never happens, instead we forward values to the Helm chart for templating to occur

rough draft of new docs reference pages

ee5a359

Signed-off-by: Kit Patella <[email protected]>

github-project-automation bot added this to Zarf Nov 14, 2025

mkcp self-assigned this Nov 14, 2025

mkcp added the documentation 📘 Improvements or additions to documentation label Nov 14, 2025

mkcp added 2 commits November 14, 2025 12:52

update helm mappings section and edit for flow

6e7fcd9

Signed-off-by: Kit Patella <[email protected]>

give users an overview but lean on examples more by linking out to th…

76db932

…em rather than duplicating the same content Signed-off-by: Kit Patella <[email protected]>

mkcp moved this to In progress in Zarf Nov 14, 2025

mkcp added 5 commits November 14, 2025 12:56

unused imports

64175e5

Signed-off-by: Kit Patella <[email protected]>

update ref/templating.md for flow

8108622

Signed-off-by: Kit Patella <[email protected]>

fix build, some of those imports were used

1976c7d

Signed-off-by: Kit Patella <[email protected]>

update package-values.mdx with schema guidance and more info on CLI a…

b9e02ae

…nd config file imports and --set-values Signed-off-by: Kit Patella <[email protected]>

add package values best practices

aafc9fc

Signed-off-by: Kit Patella <[email protected]>

mkcp changed the title ~~docs(values,templating): add reference pages for package values and templating~~ docs(values,templating): add reference and best practices pages for package values and templating Nov 14, 2025

mkcp changed the title ~~docs(values,templating): add reference and best practices pages for package values and templating~~ docs(values,templating): add reference and best practices pages Nov 14, 2025

make templating best practices

068c56d

Signed-off-by: Kit Patella <[email protected]>

mkcp marked this pull request as ready for review November 14, 2025 22:13

mkcp requested review from a team as code owners November 14, 2025 22:13

a1994sc previously approved these changes Nov 14, 2025

View reviewed changes

mkcp added this pull request to the merge queue Nov 14, 2025

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Nov 14, 2025

brandtkeller requested changes Nov 17, 2025

View reviewed changes

AustinAbro321 requested changes Nov 17, 2025

View reviewed changes

mkcp moved this from In progress to Next in Zarf Dec 2, 2025

brandtkeller added this to the v0.67.1 Release milestone Dec 4, 2025

remove some extras from templating best practices

7af5c0c

Signed-off-by: Kit Patella <[email protected]>

mkcp dismissed a1994sc’s stale review via 7af5c0c January 6, 2026 17:14

editing pass over the values and templating docs

475af70

Signed-off-by: Kit Patella <[email protected]>

incorporate some review feedback and do some more editing

0b8a742

Signed-off-by: Kit Patella <[email protected]>

mkcp moved this from Next to PR Review in Zarf Jan 8, 2026

brandtkeller requested changes Jan 9, 2026

View reviewed changes

github-project-automation bot moved this from PR Review to In progress in Zarf Jan 9, 2026

AustinAbro321 reviewed Jan 9, 2026

View reviewed changes


		See the [Templating Reference](/ref/templating/) for complete function documentation.

		## Avoid Sensitive Data in Values Files


		:::

		Zarf supports Go template syntax and `text/template` engine with powerful features including control flow and functions. Zarf includes the full library of [Sprig functions](http://masterminds.github.io/sprig/) and some builtins for dynamic configuration in manifests, files, and actions. This powerful templating system enables complex transformations, conditional logic, and data manipulation beyond simple string substitution.


		## Provide Defaults for Optional Values

		Use the `default` function to provide fallback values:


		## Handle Missing Values Gracefully

		Protect against missing or nil values:


		## Do Not Commit Sensitive Values in Package

		Values are the best way to pass secrets into your Zarf package, but those secrets should not be baked into the values files a package is created with:


		:::

		Package Values provide a familiar way to define and reusable configuration data in your Zarf packages. Unlike the legacy [Variables and Constants](/ref/values/) system that uses string substitution with `###ZARF_VAR_###` syntax, Package Values uses Go templates with access to structured data and types, [go's templating engine](https://pkg.go.dev/text/template), and custom functions like those offered by [Sprig](/ref/templating/).

docs(values,templating): add reference and best practices pages #4368

Are you sure you want to change the base?

docs(values,templating): add reference and best practices pages #4368

Conversation

mkcp commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue

Checklist before merging

Uh oh!

netlify bot commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for zarf-docs ready!

Uh oh!

codecov bot commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

a1994sc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AustinAbro321 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

brandtkeller left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mkcp commented Nov 14, 2025 •

edited

Loading

netlify bot commented Nov 14, 2025 •

edited

Loading

codecov bot commented Nov 14, 2025 •

edited

Loading