docs(values,templating): add reference and best practices pages by mkcp · Pull Request #4368 · zarf-dev/zarf

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 <kit@defenseunicorns.com>

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

✅ Deploy Preview for zarf-docs ready!

Name	Link
🔨 Latest commit	`95ee80f`
🔍 Latest deploy log	https://app.netlify.com/projects/zarf-docs/deploys/69680635138af500084a6a0c
😎 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 54 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 <kit@defenseunicorns.com>

…em rather than duplicating the same content Signed-off-by: Kit Patella <kit@defenseunicorns.com>

Signed-off-by: Kit Patella <kit@defenseunicorns.com>

…nd config file imports and --set-values Signed-off-by: Kit Patella <kit@defenseunicorns.com>

Signed-off-by: Kit Patella <kit@defenseunicorns.com>

a1994sc

LGTM

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

+
+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

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


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

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

+
+:::
+
+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

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

+
+## 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

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

+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

+
+## 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

Signed-off-by: Kit Patella <kit@defenseunicorns.com>

brandtkeller

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

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

+
+## 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:56:46Z

+- `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

+  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.

Signed-off-by: Kit Patella <kit@defenseunicorns.com>

brandtkeller · 2026-07-28T21:54:02Z

Closing as completed in #5090

rough draft of new docs reference pages

ee5a359

Signed-off-by: Kit Patella <kit@defenseunicorns.com>

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 <kit@defenseunicorns.com>

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 <kit@defenseunicorns.com>

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 <kit@defenseunicorns.com>

update ref/templating.md for flow

8108622

Signed-off-by: Kit Patella <kit@defenseunicorns.com>

fix build, some of those imports were used

1976c7d

Signed-off-by: Kit Patella <kit@defenseunicorns.com>

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 <kit@defenseunicorns.com>

add package values best practices

aafc9fc

Signed-off-by: Kit Patella <kit@defenseunicorns.com>

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 <kit@defenseunicorns.com>

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 <kit@defenseunicorns.com>

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 <kit@defenseunicorns.com>

incorporate some review feedback and do some more editing

0b8a742

Signed-off-by: Kit Patella <kit@defenseunicorns.com>

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

Comment thread site/src/content/docs/ref/templating.mdx Outdated

fix some flags and clarify sections

95ee80f

Signed-off-by: Kit Patella <kit@defenseunicorns.com>

brandtkeller removed this from the v0.67.1 Release milestone Jul 28, 2026

brandtkeller closed this Jul 28, 2026

github-project-automation Bot moved this from In progress to Done in Zarf Jul 28, 2026


		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:

Uh oh!

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!

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 commented Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mkcp commented Nov 14, 2025 •

edited

Loading

netlify Bot commented Nov 14, 2025 •

edited

Loading

codecov Bot commented Nov 14, 2025 •

edited

Loading