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

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

Description

WIP: Add reference 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	`068c56d`
🔍 Latest deploy log	https://app.netlify.com/projects/zarf-docs/deploys/6917a6cdaf83610008e79c1e
😎 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 1 file 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.

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.

brandtkeller · 2025-11-17T14:43:11Z

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

+            targetPath: ".config.database.host"  # Takes priority
+```
+
+#### Mapping All Values


nit: we may want to refine this section at some point to help users understand the best practices for building a package with values files that aligns to broader zarf hardening goals.

said another way - I think we should encourage using sourcePath/targetPath as a best practice for package hardening.

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.

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

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

AustinAbro321 · 2025-11-17T15:23:46Z

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

+
+## Leverage Templating Functions
+
+Use [functions](/ref/templating/) for dynamic configuration:


This should link to ref/templating/#template-functions

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

AustinAbro321 · 2025-11-17T15:50:58Z

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

+**Solution:**
+```yaml
+# Use default for optional values
+value: {{ .Values.app.missing | default "fallback" }}
+
+# Or check if exists first
+{{- if .Values.app.missing }}
+value: {{ .Values.app.missing }}
+{{- end }}
+```


Both of these solutions would not solve the error.

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

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

+
+### Quoting Problems
+
+**Problem:** YAML parsing fails with boolean-like strings


I think I understand why we would use the quote function at times, we wouldn't want a type to be interpreted as the incorrect type. Are there situations where YAML parsing would fail?

I think there's a specific yaml spec version where this was a problem, I don't know if this specifically affects Zarf though. This is probably covered under the more general guidance to quote strings.

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


		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:


		## Leverage Templating Functions

		Use [functions](/ref/templating/) for dynamic configuration:


		## Handle Missing Values Gracefully

		Protect against missing or nil values:


		### Quoting Problems

		Problem: YAML parsing fails with boolean-like strings

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

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!

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!

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