Package Values

This guide provides best practices for using Package Values in your Zarf packages.

Organize Values Logically

Group related values together using nested structures. This makes your values files easier to understand and maintain:

app:
  name: "my-app"
  environment: "production"
  replicas: 3

database:
  host: "db.example.com"
  port: 5432
  name: "appdb"

monitoring:
  enabled: true
  retention: "30d"

Benefits:

Clear ownership and grouping of related configuration
Easier to override specific sections
Better aligns with Helm chart structures for value mapping

Use Meaningful Defaults

Provide sensible defaults in your package values files that work out-of-the-box:

app:
  replicas: 3  # Default for production
  logLevel: "info"
  resources:
    limits:
      cpu: "1000m"
      memory: "512Mi"

# Optional settings with safe defaults
features:
  experimental: false
  debug: false

Guidelines:

Defaults should work for the most common use case (usually production)
Use conservative resource limits to avoid cluster issues
Disable experimental or debug features by default
Make optional features opt-in rather than opt-out

Separate Environment-Specific Values

Use multiple values files for different environments:

# values.yaml (base configuration)
app:
  name: "my-app"
  replicas: 1

# values-production.yaml (production overrides)
app:
  replicas: 3
  logLevel: "warn"

# values-development.yaml (development overrides)
app:
  replicas: 1
  logLevel: "debug"
  features:
    debug: true

Deploy with environment-specific values:

# Production deployment
zarf package deploy my-package.tar.zst \
  --features="values=true" \
  -f values-production.yaml

# Development deployment
zarf package deploy my-package.tar.zst \
  --features="values=true" \
  -f values-development.yaml

Use Schema Validation

Define a JSON schema to validate values and catch errors early:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "app": {
      "type": "object",
      "properties": {
        "replicas": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10,
          "description": "Number of application replicas"
        },
        "environment": {
          "type": "string",
          "enum": ["development", "staging", "production"],
          "description": "Deployment environment"
        },
        "logLevel": {
          "type": "string",
          "enum": ["debug", "info", "warn", "error"],
          "default": "info"
        }
      },
      "required": ["replicas", "environment"]
    }
  },
  "required": ["app"]
}

Reference the schema in your package:

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

Benefits:

Catch configuration errors before deployment
Provide clear error messages to users
Document valid values and constraints
Enable IDE autocomplete and validation

Leverage Templating Functions

Use functions for dynamic configuration:

# In manifests with template: true
metadata:
  name: {{ .Values.app.name | kebabcase }}
  labels:
    app: {{ .Values.app.name | kebabcase }}
    environment: {{ .Values.app.environment | upper }}
    version: {{ .Values.app.version | quote }}

spec:
  # Use defaults for optional values
  replicas: {{ .Values.app.replicas | default 1 }}

  # Conditional configuration:
  {{- if .Values.monitoring.enabled }}
  annotations:
    prometheus.io/scrape: "true"
  {{- end }}

See the Templating Reference for complete function documentation.

Avoid Sensitive Data in Values Files

Don’t commit sensitive data to your values files:

# ❌ BAD: Secrets in values files
database:
  password: "super-secret-password"
  apiKey: "sk-1234567890"

# ✅ GOOD: Reference secrets or use setValues
database:
  passwordSecretName: "db-credentials"
  passwordSecretKey: "password"

For dynamic secrets, use setValues in actions:

components:
  - name: dynamic-secrets
    actions:
      onDeploy:
        before:
          - cmd: kubectl get secret db-creds -o jsonpath='{.data.password}' | base64 -d
            setValues:
              - name: database.password

Test Your Values

Use zarf dev inspect manifests to preview templated resources without deploying:

# Test with default values
zarf dev inspect manifests --features="values=true"

# Test with custom values
zarf dev inspect manifests \
  --features="values=true" \
  -f custom-values.yaml \
  --set-values="app.replicas=5"

This helps you:

Verify templates render correctly
Catch syntax errors before deployment
Test different value combinations
Review the final Kubernetes manifests

Package Values Reference - Complete Package Values documentation
Templating Reference - Template syntax and functions
values-templating Example - Working examples