feat: expose UDS Core config as native Zarf values

.github/actions/autogenerated-check/action.yaml

@@ -32,6 +32,9 @@ runs:
         # Update Velero CRDs
         uds run -f src/velero/tasks.yaml update-crds
 
+        # Generate Zarf values schemas
+        uds run -f tasks/lint.yaml values-generate
+
     - name: Check generated files for diffs
       shell: bash
       run: |
@@ -62,6 +65,16 @@ runs:
           echo -e "\033[33m⚠️ Velero CRDs are not up to date, please run \`uds run -f src/velero/tasks.yaml update-crds\` and commit the changes.\033[0m"
         fi
 
+        if [ ! -z "$(git status -s packages/*/zarf-values.schema.json)" ]; then
+          # Diffs for Zarf values schemas
+          DIFFS=true
+          echo -e "\033[33m⚠️ Zarf values schemas are not up to date, please run \`uds run -f tasks/lint.yaml values-generate\` and commit the changes.\033[0m"
+          echo "Changed schema files:"
+          git status --short -- packages/*/zarf-values.schema.json
+          git diff --stat -- packages/*/zarf-values.schema.json
+          echo "This check runs against the pull request merge ref. If local generation is clean, sync the branch with main and regenerate the schemas."
+        fi
+
         if [ "${DIFFS}" = "true" ]; then
           echo -e "\033[31m❌ ERROR: Ensure that all generated file changes are up to date and committed (see warnings above).\033[0m"
           exit 1

.github/workflows/pull-request-conditionals.yaml

@@ -173,6 +173,9 @@ jobs:
           - package: all
             flavor: unicorn
             test_type: upgrade
+          - package: all
+            flavor: upstream
+            test_type: values
         # Portal is not available in registry1; skip single-layer tests for that flavor
         exclude:
           - package: portal

.github/workflows/test-cli-matrix.yaml

@@ -34,15 +34,16 @@ jobs:
     strategy:
       matrix:
         include:
-          # Both versions intentionally frozen on last compatible CLI version
+          # The install phase uses the last compatible CLI for the released package.
+          # The upgrade phase must support native values in the current branch.
           - scenario: old-old
             flavor: upstream
-            install_cli: v0.32.0
-            upgrade_cli: v0.32.0
-          # install_cli intentionally frozen (last compatible version); upgrade_cli tracks new releases via Renovate
+            install_cli: v0.34.0
+            upgrade_cli: v0.34.0
+          # Install with the minimum values-capable CLI; upgrade_cli tracks new releases via Renovate.
           - scenario: old-new
             flavor: upstream
-            install_cli: v0.32.0
+            install_cli: v0.34.0
             # renovate: datasource=github-tags depName=defenseunicorns/uds-cli versioning=semver
             upgrade_cli: v0.34.2
 
@@ -56,7 +57,7 @@ jobs:
           ghToken: ${{ secrets.GITHUB_TOKEN }}
           installK3d: 'true'
 
-      # Override the CLI installed by setup with the install-phase version (old CLI)
+      # Override the CLI installed by setup with the install-phase version.
       - name: Install CLI for install phase
         uses: defenseunicorns/setup-uds@ab842abcad1f7a3305c2538e3dd1950d0daacfa5 # v1.0.1
         with:
@@ -71,7 +72,7 @@ jobs:
       - name: Deploy latest release test resources
         run: uds run -f tasks/deploy.yaml latest-release-test-resources --set FLAVOR=${{ matrix.flavor }} --no-progress
 
-      # Switch to the upgrade-phase CLI version before building and deploying current branch
+      # Switch to the values-capable CLI before building and deploying the current branch.
       - name: Install CLI for upgrade phase
         uses: defenseunicorns/setup-uds@ab842abcad1f7a3305c2538e3dd1950d0daacfa5 # v1.0.1
         with:
@@ -96,7 +97,7 @@ jobs:
   cli-install:
     runs-on: uds-ubuntu-big-boy-8-core
     timeout-minutes: 30
-    name: "Test Install (old, upstream)"
+    name: "Test Install (minimum supported, upstream)"
 
     steps:
       - name: Checkout repository
@@ -108,17 +109,16 @@ jobs:
           ghToken: ${{ secrets.GITHUB_TOKEN }}
           installK3d: 'true'
 
-      # Override the CLI installed by setup with the old CLI to verify current branch installs cleanly without new CLI
-      # Intentionally frozen — represents the last compatible CLI version
-      - name: Install old CLI
+      # Use the minimum CLI version that supports the current package's native values.
+      - name: Install minimum supported CLI
         uses: defenseunicorns/setup-uds@ab842abcad1f7a3305c2538e3dd1950d0daacfa5 # v1.0.1
         with:
-          version: v0.32.0
+          version: v0.34.0
 
       - name: Print CLI version for debug
         run: uds version
 
-      - name: Test UDS Core Install (old CLI)
+      - name: Test UDS Core Install (minimum supported CLI)
         run: uds run test:uds-core-e2e --set FLAVOR=upstream --no-progress
 
       - name: Debug Output

.github/workflows/test.yaml

@@ -61,7 +61,7 @@ jobs:
           registry1Username: ${{ (inputs.flavor == 'registry1') && secrets.IRON_BANK_ROBOT_USERNAME || '' }}
           registry1Password: ${{ (inputs.flavor == 'registry1') && secrets.IRON_BANK_ROBOT_PASSWORD || '' }}
           chainguardIdentity: ${{ (inputs.flavor == 'unicorn') && secrets.CHAINGUARD_IDENTITY || '' }}
-          installK3d: 'true'
+          installK3d: "true"
 
       - name: Test a single layer package
         # Guard against portal+registry1 since workflow_dispatch and workflow_call triggers bypass matrix excludes
@@ -76,6 +76,10 @@ jobs:
         if: ${{ inputs.package == 'all' && inputs.test_type == 'upgrade' }}
         run: uds run test-uds-core-upgrade --set FLAVOR=${{ inputs.flavor }} --set EXCLUDED_PACKAGES=${{ inputs.flavor == 'registry1' && 'portal' || '' }} --no-progress
 
+      - name: Test UDS Core values deploy equivalency
+        if: ${{ inputs.package == 'all' && inputs.test_type == 'values' }}
+        run: uds run test:uds-core-values-e2e --set FLAVOR=${{ inputs.flavor }} --no-progress
+
       - name: Debug Output
         if: ${{ always() }}
         uses: ./.github/actions/debug-output

bundles/base-shim/README.md

@@ -2,4 +2,4 @@
 
 The Base Shim bundle is used exclusively in dev/CI testing to provide a baseline bundle with access to overrides. By using a bundle we have access to set values for testing that are more complex (maps and lists) and cannot be currently handled with Zarf variables.
 
-This shim bundle should be replaced by proper Zarf variables once [ZEP 0021](https://github.com/zarf-dev/proposals/tree/main/0021-zarf-values) is fully implemented.
+For direct package deployments, use [Zarf Values](https://docs.zarf.dev/ref/examples/values-templating/) for configuration, including structured overrides such as maps and lists. Existing [Zarf Variables](https://docs.zarf.dev/ref/examples/variables/) remain supported for backwards compatibility.

docs/concepts/configuration-and-packaging/package-requirements.mdx

@@ -32,9 +32,9 @@ UDS Packages must meet a set of standards to ensure they are secure, maintainabl
 - **MUST** include package documentation in a root-level `docs` folder (for configuration and dependencies) and include it in the Zarf package under the [`documentation` key](https://docs.zarf.dev/schema/v1alpha1-package/#ZarfPackage).
 - **MUST** include application metadata for UDS Registry publishing. See [Package Metadata](/concepts/configuration-and-packaging/package-metadata/).
 - **SHOULD** follow the [Package Values](/concepts/configuration-and-packaging/package-values/) guidance for exposing package configuration.
-  > [Zarf Values](https://docs.zarf.dev/ref/examples/values-templating/) is currently an **Alpha** feature and may change as it matures (see [zarf-dev/zarf#3946](https://github.com/zarf-dev/zarf/issues/3946)). This guidance will evolve with the feature and as such, packages **MAY** still use [Zarf Variables](https://docs.zarf.dev/ref/examples/variables/). If you adopt Values today, feedback in the [Zarf repository](https://github.com/zarf-dev/zarf) is strongly encouraged.
+  > [Zarf Values](https://docs.zarf.dev/ref/examples/values-templating/) is currently an **Alpha** feature and may change as it matures (see [zarf-dev/zarf#3946](https://github.com/zarf-dev/zarf/issues/3946)). Use values for package configuration. Retain existing [Zarf Variables](https://docs.zarf.dev/ref/examples/variables/) when needed for backwards compatibility, and combine them with explicit values through `templatedValuesFiles`.
 - **SHOULD** limit the use of [Zarf Variables](https://docs.zarf.dev/ref/examples/variables/) and prioritize configuring packages via [Zarf Values](https://docs.zarf.dev/ref/examples/values-templating/).
-  > This ensures that the package has more flexibility and avoids any side effect issues of Zarf's `###` templating (which is planned to be deprecated and removed once Zarf Values is stable).
+  > Use values for package configuration whenever possible. Keep raw `###ZARF_VAR_*###` tokens in ordinary `valuesFiles`; use `.Variables.*` in `templatedValuesFiles` only when existing variables must remain compatible or the package must apply precedence or compute a fallback.
 - **SHOULD** implement or allow for multiple flavors (ideally with common definitions in a common directory).
   > This allows for different images or configurations to be delivered consistently to customers.
 

docs/concepts/configuration-and-packaging/package-values.mdx

@@ -8,7 +8,7 @@ sidebar:
 UDS Packages expose configuration through [Zarf Values](https://docs.zarf.dev/ref/examples/values-templating/), 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](https://github.com/zarf-dev/zarf/issues/3946)). This guidance will evolve with the feature. Packages **MAY** still use [Zarf Variables](https://docs.zarf.dev/ref/examples/variables/). If you adopt Values today, feedback in the [Zarf repository](https://github.com/zarf-dev/zarf) is strongly encouraged.
+> Zarf Values is currently an **Alpha** feature and may change as it matures (see [zarf-dev/zarf#3946](https://github.com/zarf-dev/zarf/issues/3946)). UDS Core requires UDS CLI `v0.34.0` or later for its values workflow. Use values for package configuration; retain [Zarf Variables](https://docs.zarf.dev/ref/examples/variables/) only when required for backwards compatibility.
 
 ## Values structure
 
@@ -17,16 +17,15 @@ 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](https://json-schema.org/) and focus on validating common user-facing values. Keep deeply nested validation practical to avoid fragile schemas as charts and Kubernetes APIs evolve.
-
-> [!TIP]
-> There is an open Zarf issue to support schema generation: [zarf-dev/zarf#4918](https://github.com/zarf-dev/zarf/issues/4918).
+The schema should follow [JSON Schema](https://json-schema.org/). 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.
 
-For shared values across multiple charts (for example `domain`), use a shared key to reduce configuration drift.
+For values shared across multiple charts, use the reserved top-level `global` key to reduce configuration drift. For example, use `global.domain` rather than repeating `domain` under each chart.
+
+Use values for package configuration. Use `###ZARF_VAR_<NAME>###` in ordinary `valuesFiles` only when an existing variable must remain compatible. Use `templatedValuesFiles` with `.Variables.<NAME>` when explicit package values must take precedence over an existing variable or need a computed fallback. Keep those phases separate because Zarf substitutes variable tokens before evaluating Go templates.
 
 ## Example configuration
 
@@ -101,7 +100,8 @@ The `zarf-values.yaml` provides defaults that deployers can override:
 
 ```yaml title="zarf-values.yaml"
 uds-nginx-config:
-  domain: uds.dev
+  global:
+    domain: uds.dev
 
 nginx:
   replicaCount: 1
@@ -176,3 +176,4 @@ The `zarf-values.schema.json` validates the defaults above:
 - [Create a UDS Package](/how-to-guides/packaging-applications/create-uds-package/) - end-to-end guide for packaging an application as a UDS Package.
 - [Package testing](/how-to-guides/packaging-applications/package-testing/) - add journey and upgrade tests for your package.
 - [UDS Package Requirements](/concepts/configuration-and-packaging/package-requirements/) - pre-publish checklist for required capabilities and standards.
+- [Zarf values reference](/reference/configuration/zarf-values/) - the Zarf value keys and defaults UDS Core exposes per package.

docs/how-to-guides/packaging-applications/create-uds-package.mdx

@@ -93,7 +93,7 @@ The template repository provides the standard directory structure:
 
    The root `zarf.yaml` defines package metadata and per-flavor components. Each flavor imports from `common/zarf.yaml` and adds its own values file and container images:
 
-   The `variables` block declares Zarf package variables that deployers can set at deploy time via `uds-config.yaml` or `--set` flags. They are injected into Helm values using the `###ZARF_VAR_<NAME>###` syntax; you can see this in `chart/values.yaml` where `domain: "###ZARF_VAR_DOMAIN###"` picks up the deployer-supplied domain at deploy time. Use `sensitive: true` on variables that contain secrets so their values are never logged. See the [Zarf variables reference](https://docs.zarf.dev/ref/packages/#variables) for all available options.
+   Use Zarf Values for package configuration and let deployers provide overrides with `--values` or `--set-values`. Keep the `variables` block for existing variable-based workflows or values that cannot yet be migrated. When a variable must remain compatible, use `###ZARF_VAR_<NAME>###` in ordinary `valuesFiles`; use `templatedValuesFiles` with `.Variables.<NAME>` when explicit package values must take precedence or a template needs a computed fallback. Use `sensitive: true` on variables that contain secrets so their values are never logged. See the [Zarf variables reference](https://docs.zarf.dev/ref/packages/#variables) for the remaining variable options.
 
    ```yaml title="zarf.yaml"
    kind: ZarfPackageConfig

docs/reference/configuration/overview.mdx

@@ -24,4 +24,9 @@ Configuration surfaces exposed by UDS Core components: the fields, defaults, and
     Storage backend, bucket names, schema versioning, and bundle overrides for Loki log storage.
     <LinkCard title="View reference" href="/reference/configuration/loki-storage/" />
   </Card>
+
+  <Card title="Zarf values" icon="setting">
+    Override UDS Core configuration with native Zarf values when deploying packages directly, plus the per-package value keys and defaults.
+    <LinkCard title="View reference" href="/reference/configuration/zarf-values/" />
+  </Card>
 </CardGrid>