zarf-dev · mkcp · Aug 28, 2025 · Aug 28, 2025 · Aug 28, 2025 · Aug 28, 2025
@@ -0,0 +1,6 @@
+apiVersion: v2
+name: example-chart
+version: 0.1.0
+appVersion: "0.1.0"
+description: A simple example chart for overriding helm values with zarf values.
+type: application
@@ -0,0 +1,27 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ .Values.appName }}-config
+  namespace: {{ .Release.Namespace }}
+  labels:
+    app: {{ .Values.appName }}
+    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    release: {{ .Release.Name }}
+    replicas: "{{ .Values.replicaCount }}"
+data:
+  # Test basic mappings
+  app-name: "{{ .Values.appName }}"
+  replica-count: "{{ .Values.replicaCount }}"
+  image-tag: "{{ .Values.image.tag }}"
+
+  # Test nested object mapping
+  database-host: "{{ .Values.config.database.host }}"
+  database-port: "{{ .Values.config.database.port }}"
+
+  # Test default values (not mapped)
+  log-level: "{{ .Values.config.app.logLevel }}"
+  debug-mode: "{{ .Values.config.app.debug }}"
+
+  # Test resource values
+  cpu-limit: "{{ .Values.resources.limits.cpu }}"
+  memory-limit: "{{ .Values.resources.limits.memory }}"
@@ -0,0 +1,24 @@
+# Chart default values - these will be overridden by Zarf value mappings on the chart definition
+appName: "default-app"
+replicaCount: 1
+
+image:
+  repository: nginx
+  tag: "latest"
+  pullPolicy: IfNotPresent
+
+config:
+  database:
+    host: "localhost"
+    port: 3306
+  app:
+    debug: false
+    logLevel: "info"
+
+resources:
+  limits:
+    cpu: 100m
+    memory: 128Mi
+  requests:
+    cpu: 50m
+    memory: 64Mi
@@ -0,0 +1,77 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: nginx-configmap
+  namespace: nginx
+  labels:
+    app: nginx
+data:
+  01_http.conf: |
+    add_header X-Kubernetes-Pod $hostname;
+  index.html: |
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>Welcome to {{ .Values.site.name }}!</title>
+        <style>
+          {{ .Values.site.styles }}
+        </style>
+      </head>
+      <body>
+        <!-- Test two separate values on the same line -->
+        <h1>Welcome to the {{ .Values.site.name }}!</h1><h2>Brought to you by {{ .Values.site.organization }}.</h2>
+
+        <!-- Import Variables and Constants into new go-templates, to help with migrating over to the new Values feature
+        and templating syntax -->
+        <pre>Imported variable from .Variables.EXAMPLE_VAR {{ .Variables.EXAMPLE_VAR }}</pre>
+        <pre>Imported constant from .Constants.EXAMPLE_CONST {{ .Constants.EXAMPLE_CONST }}</pre>
+
+        <!-- Sprig Function Examples -->
+        <h3>Sprig Function Examples</h3>
+
+        <!-- String manipulation functions -->
+        <h4>String Functions:</h4>
+        <pre>Original: {{ .Values.site.message | quote }}</pre>
+        <pre>Upper: {{ .Values.site.message | upper | quote }}</pre>
+        <pre>Title: {{ .Values.site.message | title | quote }}</pre>
+        <pre>Kebab: {{ .Values.site.title | kebabcase | quote }}</pre>
+        <pre>Snake: {{ .Values.site.title | snakecase | quote }}</pre>
+
+        <!-- List/array functions -->
+        <h4>List Functions:</h4>
+        <pre>Items: {{ .Values.app.features | join ", " | quote }}</pre>
+        <pre>Count: {{ .Values.app.features | len }}</pre>
+        <pre>First: {{ .Values.app.features | first | quote }}</pre>
+        <pre>Last: {{ .Values.app.features | last | quote }}</pre>
+        <pre>Sorted: {{ .Values.app.features | sortAlpha | join ", " | quote }}</pre>
+        <pre>Reversed: {{ .Values.app.features | reverse | join ", " | quote }}</pre>
+
+        <!-- Default value functions -->
+        <h4>Default & Conditional Functions:</h4>
+        <pre>Required Field: {{ .Values.app.required_setting | default "fallback value" | quote }}</pre>
+        <pre>Optional Field (empty): {{ .Values.app.optional_setting | default "default value" | quote }}</pre>
+        <pre>Environment: {{ .Values.app.environment | upper | quote }}</pre>
+
+        <!-- Math functions -->
+        <h4>Math Functions:</h4>
+        <pre>Replicas: {{ .Values.app.replicas }}</pre>
+        <pre>Add 2: {{ add .Values.app.replicas 2 }}</pre>
+        <pre>Multiply: {{ mul .Values.app.replicas 10 }}</pre>
+        <pre>Max Port: {{ max .Values.app.port1 .Values.app.port2 .Values.app.port3 }}</pre>
+        <pre>Min Port: {{ min .Values.app.port1 .Values.app.port2 .Values.app.port3 }}</pre>
+
+        <!-- Encoding/hashing functions -->
+        <h4>Encoding & Hashing Functions:</h4>
+        <pre>Base64: {{ .Values.app.config_data | b64enc }}</pre>
+        <pre>SHA256: {{ .Values.app.config_data | sha256sum }}</pre>
+
+        <!-- Type conversion and formatting -->
+        <h4>Type & Format Functions:</h4>
+        <pre>Ports as String: {{ .Values.app.ports | join "," | quote }}</pre>
+        <pre>Items Count: {{ .Values.app.features | len | toString }}</pre>
+        <pre>Repeat and Indent Example:</pre>
+        <pre>{{ .Values.site.message | repeat 3 | indent 4 }}</pre>
+
+        {{ .Values.site.footer }}
+      </body>
+    </html>
@@ -0,0 +1,55 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx
+  namespace: nginx
+  labels:
+    app: nginx
+    # Sprig example: Convert environment to lowercase and kebab-case
+    environment: {{ .Values.app.environment | lower }}
+    # Sprig example: Create a hash-based identifier
+    config-hash: {{ .Values.app.config_data | sha256sum | trunc 8 }}
+  annotations:
+    # Sprig example: Base64 encode sensitive data references
+    config.zarf.dev/data-hash: {{ .Values.app.config_data | b64enc }}
+spec:
+  selector:
+    matchLabels:
+      app: nginx
+  # Sprig example: Use configured replica count with a sensible default
+  replicas: {{ .Values.app.replicas | default 1 }}
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:latest
+        ports:
+        - containerPort: 80
+          name: http
+        env:
+        # Sprig example: Environment variables with transformations
+        - name: ENVIRONMENT
+          value: {{ .Values.app.environment | upper | quote }}
+        - name: APP_NAME
+          value: {{ .Values.site.title | kebabcase | quote }}
+        - name: CONFIG_HASH
+          value: {{ .Values.app.config_data | sha256sum | trunc 16 | quote }}
+        resources:
+          limits:
+            # Sprig example: Calculate CPU based on replica count
+            cpu: {{ mul .Values.app.replicas 100 }}m
+            memory: 512Mi
+        volumeMounts:
+        - name: nginx-config
+          mountPath: /etc/nginx/conf.d/01_http.conf
+          subPath: 01_http.conf
+        - name: nginx-config
+          mountPath: /usr/share/nginx/html/index.html
+          subPath: index.html
+      volumes:
+      - name: nginx-config
+        configMap:
+          name: nginx-configmap
@@ -0,0 +1,19 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: nginx-connect
+  namespace: nginx
+  annotations:
+    zarf.dev/connect-description: "Launch the nginx static site."
+  labels:
+    zarf.dev/connect-name: nginx
+    zarf.dev/example-var: {{ .Variables.EXAMPLE_VAR }}
+    zarf.dev/example-const: {{ .Constants.EXAMPLE_CONST }}
+spec:
+  ports:
+  - port: 8080
+    name: http
+    protocol: TCP
+    targetPort: 80
+  selector:
+    app: nginx
@@ -0,0 +1,47 @@
+# Constants are defined on package create and do not change on deploy
+# This demonstrates setting the nginx version to bake into the package using a package variable (PKG_TMPL)
+site:
+  # The name of the site you are deploying
+  name: "Zarf Values Example Website"
+  # Sets the CSS styles for the site, and provides an example of a multi-line value
+  styles: >-
+    body { font-family: sans-serif; color: white; background: #0a0e2e; }
+    pre { color: white; background: black; }
+  # The organization providing the site
+  organization: "Zarf-Dev"
+  # The footer to be added to the site, overrides the default with whatever you want.
+  footer: ""
+  # Additional metadata for sprig examples
+  title: "my awesome app"
+  message: "hello world from zarf"
+
+# Application deployment configuration
+app:
+  environment: "production"
+  replicas: 3
+  # Configuration data that can be hashed for integrity checks
+  config_data: "important application configuration data"
+  # Optional field to demonstrate default values
+  optional_setting: ""  # Will use default value in templates
+  required_setting: "configured value"
+  # List of supported features for list function examples
+  features:
+    - "templating"
+    - "sprig-functions"
+    - "kubernetes-deployment"
+    - "value-substitution"
+  # Network ports for the application
+  ports: [80, 443, 8080]
+  port1: 80
+  port2: 443
+  port3: 8080
+  # Helm chart overrides
+  name: "helm-overrides-app"  # Maps to .appName in helm chart
+  image:
+    tag: "v2.1.0"             # Maps to .image.tag in helm chart
+
+# Database configuration for helm chart
+database:
+  host: "postgres.zarf.local-schmocal" # Maps to .config.database.host in helm chart
+  host2: "postgres.zarf.local" # Also maps to .config.database.host, but takes priority because it's mapped afterwards
+
@@ -0,0 +1,95 @@
+kind: ZarfPackageConfig
+metadata:
+  name: values-templating
+  description: Example nginx package to demonstrate Zarf Values templating
+values:
+  files:
+    - values.yaml
+
+# 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:
+      # NOTE: Pkgtemplates aren't yet available with value and go-templates.
+      - "nginx:latest"
+    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: ".app.image.tag"
+            targetPath: ".image.tag"
+          - 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"
+
+
+# YAML keys starting with `x-` are custom keys that are ignored by the Zarf CLI
+# The `x-mdx` key is used to render the markdown content for https://docs.zarf.dev/ref/examples
+x-mdx: |
+  # [ALPHA] Values & Templates Example
+
+  This example demonstrates the pre-release alpha version of Zarf's values templating system, including support for **Sprig functions** for advanced template processing and **Helm chart value overrides**.
+
+  ## Features Demonstrated
+
+  - **Basic templating** with `{{ .Values.* }}`, `{{ .Build.* }}`, `{{ .Metadata.* }}`, `{{ .Constants.* }}`, and `{{ .Variables.* }}`
+  - **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:
+
+    ```bash
+    # Create and deploy the package (features="values=true" flag required until general release of values)
+    zarf package create . --confirm --features="values=true"
+    zarf package deploy zarf-package-values-templating-*.tar.zst --confirm --features="values=true"
+
+    # 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
+    ```
@@ -257,7 +257,7 @@ require (
 	github.com/DataDog/zstd v1.5.5 // indirect
 	github.com/MakeNowJust/heredoc v1.0.0 // indirect
 	github.com/Masterminds/goutils v1.1.1 // indirect
-	github.com/Masterminds/sprig/v3 v3.3.0 // indirect
+	github.com/Masterminds/sprig/v3 v3.3.0
 	github.com/Masterminds/squirrel v1.5.4 // indirect
 	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/Microsoft/hcsshim v0.11.7 // indirect

@@ -32,6 +32,7 @@ zarf package deploy [ PACKAGE_SOURCE ] [flags]
       --shasum string               Shasum of the package to deploy. Required if deploying a remote https package.
       --skip-signature-validation   Skip validating the signature of the Zarf package
       --timeout duration            Timeout for health checks and Helm operations such as installs and rollbacks (default 15m0s)
+  -v, --values strings              [alpha] Values files to use for templating and Helm overrides. Multiple files can be passed in as a comma separated list, and the flag can be provided multiple times.
 ```
 
 ### Options inherited from parent commands