Skip to content
Unified Defense StackUnified Defense Stack

Package Values

UDS Packages expose configuration through Zarf Values, a structured mechanism for passing Helm chart values at deploy time. Expose deployment-specific configuration and restrict overrides of platform-critical settings that could break UDS integration or weaken security, such as image references, ingress configuration, or security settings.

Values structure

Section titled “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 MUST follow JSON Schema and 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), keeping mappings as flat as practical and exposing the highest sensible node in the values tree.

If individual mappings become unwieldy, consider mapping higher-level nodes and using excludePaths to omit settings that deployers should not override.

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

Example configuration

Section titled “Example configuration”

The following nginx example defines package values and maps them into application and UDS config charts within the Zarf package definition. The chart directories and chart-specific values files are not included; this example focuses on the package values configuration:

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, while the second passes the application values to the nginx chart.

The root zarf.yaml declares the defaults and schema files, imports the common component, and adds flavor-specific values and images:

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

Override values at deployment

Section titled “Override values at deployment”

After building a package with these mappings, you can override supported values without editing or rebuilding the package. For example, save this deployment-specific override alongside the built package:

deployment-values.yaml
nginx:
  replicaCount: 2

Deploy to your UDS Core cluster with the override file. Replace path/to/zarf-package-nginx.tar.zst with your built package archive:

Terminal window
uds zarf package deploy path/to/zarf-package-nginx.tar.zst \
  --values deployment-values.yaml

The override changes the package default nginx.replicaCount from 1 to 2. The sourcePath: .nginx mapping passes it to the nginx chart as replicaCount: 2, which sets the application’s replica count. Keep package defaults in zarf-values.yaml and deployment-specific overrides in the separate file. See Zarf Values for merge and precedence behavior.

Section titled “Related documentation”
Cookie SettingsPrivacy Policy