Package Values

UDS Packages expose configuration through Zarf Values, a structured mechanism for passing Helm chart values at deploy time. In general, expose most non-sensitive chart values and restrict values that would break package integrity or weaken security, such as image references, ingress, or security settings.

Note

Zarf Values is currently an Alpha feature and may change as it matures (see zarf-dev/zarf#3946). UDS Core requires UDS CLI v0.34.0 or later for its values workflow. Use values for package configuration; retain Zarf Variables only when required for backwards compatibility.

Values structure

Define the top-level values key in your root zarf.yaml and reference:

• A zarf-values.yaml for defaults
• A zarf-values.schema.json for validation

The schema should follow JSON Schema. You should use uds zarf dev generate-schema to generate it from the package definition, chart values, and value mappings.

Add value mappings (sourcePath and targetPath) near your chart definitions (commonly in common/zarf.yaml). Keep mappings as flat as practical and expose the highest sensible node in the values tree.

If the list of mappings gets unwieldy, consider inverting the mappings using higher level keys with excludePaths instead.

Use values for package configuration. Use ###ZARF_VAR_<NAME>### in ordinary valuesFiles only when an existing variable must remain compatible. Declare that variable in the package definition, then use templatedValuesFiles with .Variables.<NAME> when explicit package values must take precedence over the variable or need a computed fallback. Keep those phases separate because Zarf substitutes variable tokens before evaluating Go templates.

Example configuration

The following example shows a complete values setup for an nginx package.

Define values and map them into chart values within the Zarf package definition:

common/zarf.yaml

kind: ZarfPackageConfig
metadata:
  name: nginx
  description: UDS Common Nginx Example

components:
  - name: nginx
    required: true
    charts:
      - name: uds-nginx-config
        namespace: nginx
        version: 0.1.0
        localPath: ../chart
        values:
          - sourcePath: .global
            targetPath: .
      - name: nginx
        version: 0.1.0
        namespace: nginx
        localPath: ../src/nginx
        valuesFiles:
          - ../values/common-values.yaml
        values:
          - sourcePath: .nginx
            targetPath: .
            excludePaths:
              - .nginx.image
              - .nginx.imagePullSecrets
              - .nginx.ingress
              - .nginx.podSecurityContext
              - .nginx.securityContext
              - .nginx.livenessProbe
              - .nginx.readinessProbe

The first mapping passes the package-level global.domain value to the uds-nginx-config chart as domain. The second mapping passes the application values to the nginx chart.

zarf.yaml

kind: ZarfPackageConfig
metadata:
  name: nginx
  description: UDS Nginx Example Package

values:
  files:
    - zarf-values.yaml
  schema: zarf-values.schema.json

components:
  - name: nginx
    required: true
    description: Deploy nginx with upstream images
    import:
      path: common
    only:
      flavor: upstream
    charts:
      - name: nginx
        valuesFiles:
          - values/upstream-values.yaml
    images:
      - nginx:1.30.0

The zarf-values.yaml provides defaults that deployers can override:

zarf-values.yaml

global:
  domain: uds.dev

nginx:
  replicaCount: 1
  service:
    type: ClusterIP
    port: 8080
  resources: {}
  autoscaling:
    enabled: false
    minReplicas: 1
    maxReplicas: 100
    targetCPUUtilizationPercentage: 80
  volumes: []
  volumeMounts: []
  nodeSelector: {}
  tolerations: []
  affinity: {}

The zarf-values.schema.json validates the defaults above:

zarf-values.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "global": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "domain": {
          "type": "string"
        }
      }
    },
    "nginx": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "replicaCount": {
          "type": "integer",
          "minimum": 0
        },
        "service": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "type": { "type": "string" },
            "port": {
              "type": "integer",
              "minimum": 1,
              "maximum": 65535
            }
          }
        },
        "resources": { "type": "object" },
        "autoscaling": { "type": "object" },
        "volumes": { "type": "array", "items": { "type": "object" } },
        "volumeMounts": { "type": "array", "items": { "type": "object" } },
        "nodeSelector": { "type": "object" },
        "tolerations": { "type": "array", "items": { "type": "object" } },
        "affinity": { "type": "object" }
      }
    }
  }
}

Related documentation

• Create a UDS Package - end-to-end guide for packaging an application as a UDS Package.
• Package testing - add journey and upgrade tests for your package.
• UDS Package Requirements - pre-publish checklist for required capabilities and standards.
• Zarf values reference - the Zarf value keys and defaults UDS Core exposes per package.