values-templating

[BETA] Values & Templates Example

This example demonstrates Zarf’s beta values templating system, including support for Sprig functions for advanced template processing, Helm chart value overrides, and cluster state access via .State.

Features Demonstrated

Basic templating with {{ .Values.* }}, {{ .Build.* }}, {{ .Metadata.* }}, {{ .Constants.* }}, and {{ .Variables.* }}
Cluster state with {{ .State.Registry.Address }}, {{ .State.StorageClass }}, {{ .State.IPFamily }}, and other non-sensitive runtime fields via .State
Package object access via .Pkg, including {{ (.Pkg.GetComponent "name").Images }} to look up a component by name
Sprig functions for string manipulation, lists, math, encoding, and more
File templating with both simple substitution and complex transformations
Dynamic configuration using template functions for practical Kubernetes deployments
Helm chart value overrides mapping Zarf values to Helm chart values

Sprig Functions Showcased

The example includes demonstrations of popular Sprig functions:

String functions: upper, lower, title, kebabcase, snakecase, quote
List functions: join, len, first, last, sortAlpha, reverse
Default functions: default for fallback values
Math functions: add, mul, max, min
Encoding functions: b64enc, sha256sum
Utility functions: repeat, indent, trunc, toString

Try It Out

Deploy this example to see values and templates in action:

# Optional: Inspect the manifests and chart values-files
zarf dev inspect manifests
zarf dev inspect values-files

# Create and deploy the package
zarf package create . --confirm
zarf package deploy zarf-package-values-templating-*.tar.zst --confirm

# View the nginx results
kubectl get configmap nginx-configmap -n nginx -o yaml
zarf connect nginx

# View the helm chart results
kubectl get configmap -n helm-overrides -o yaml

# Remove the package with values templating in remove actions
# Feel free to change --set-values to whatever you want!
zarf package remove values-templating --confirm --set-values="site.name=Example,app.environment=test,site.organization=ZarfDev"

zarf.yaml

kind: ZarfPackageConfig
metadata:
  name: values-templating
  description: Example nginx package to demonstrate Zarf Values templating
values:
  files:
    - values/values.yaml
  schema: values/values.schema.json

# Until Consts and Vars are fully deprecated, they'll be available in go-templates
constants:
  - name: EXAMPLE_CONST
    value: "foo"
variables:
  - name: EXAMPLE_VAR
    default: "bar"

components:
  - name: values-with-manifest
    description: This component demonstrates templating manifest files by deploying an nginx page to the cluster
    required: true
    images:
      - "docker.io/library/nginx:1.29.2"
    actions:
      onRemove:
        before:
          - cmd: |
              echo "============================================"
              echo "Removing {{ .Values.site.name }}"
              echo "Environment: {{ .Values.app.environment }}"
              echo "Organization: {{ .Values.site.organization }}"
              echo "============================================"
            template: true
    manifests:
      - name: values-with-nginx
        # Enables go-templating within the files.
        template: true
        files:
          - nginx-deployment.yaml
          - nginx-service.yaml
          - nginx-configmap.yaml

  - name: values-with-helm-chart
    description: This component demonstrates helm chart value overrides using Zarf values
    required: true
    charts:
      - name: example-chart
        version: 0.1.0
        localPath: "charts/example-chart"
        namespace: "helm-overrides"
        values:
          - sourcePath: ".app.name"
            targetPath: ".appName"
          - sourcePath: ".app.replicas"
            targetPath: ".replicaCount"
          - sourcePath: ".database.host"
            targetPath: ".config.database.host"
          # Multiple mappings are ok. They are evaluated first to last, so the latest mapping will take priority.
          - sourcePath: ".database.host2"
            targetPath: ".config.database.host"
          # excludePaths omit sourcePath sub-objects to prevent them from being mapped to the target.
          # Here we omit the image reference and hardcode it to the chart values file since it will always be the image used on create.
          - sourcePath: ".app.image"
            targetPath: ".image"
            excludePaths:
              - ".app.image.reference"

  - name: actions-with-templates
    description: "This component demonstrates using template: true to enable go-template processing in actions"
    required: true
    actions:
      onDeploy:
        before:
          # By default, templating is disabled in actions to avoid conflicts with external tools
          # Set template: true to enable Zarf's go-template processing
          - cmd: |
              echo "Organization: {{ .Values.site.organization }}"
              echo "Environment: {{ .Values.app.environment }}"
            template: true
          # Without template: true, go-template syntax is passed through unchanged
          - cmd: |
              echo "This {{ .wontBeProcessed }} stays as-is"

documentation:
  readme: readme.md