Quickstart

What you’ll accomplish

By the end of this quickstart you’ll have:

Written a uds-bundle.yaml referencing two Zarf packages
Created a bundle locally
Deployed it to a Kubernetes cluster

To understand how bundles fit into the UDS ecosystem, see Bundles.

Prerequisites

UDS CLI installed
Access to a Kubernetes cluster

Steps

Create a uds-bundle.yaml

Create a new directory and add a uds-bundle.yaml:

kind: UDSBundle
metadata:
  name: my-first-bundle
  description: A minimal UDS bundle example
  version: 0.0.1

packages:
  - name: init
    repository: ghcr.io/zarf-dev/packages/init
    ref: v0.73.1
  - name: dos-games
    repository: ghcr.io/zarf-dev/packages/dos-games
    ref: 1.3.0

This bundle deploys the Zarf init package followed by dos-games.

Create the bundle

From the directory containing your uds-bundle.yaml:
Terminal window
```
uds create .
```
UDS CLI pulls the referenced Zarf packages from their OCI registries and assembles them into a local tarball:
```
uds-bundle-my-first-bundle-amd64-0.0.1.tar.zst
```
Add --confirm to skip the creation prompt. To create directly into an OCI registry: uds create . -o ghcr.io/<your-org>/dev
Deploy the bundle
Terminal window
```
uds deploy uds-bundle-my-first-bundle-amd64-0.0.1.tar.zst --confirm
```
Omit --confirm to see a pre-deploy summary of all packages, overrides, and variables before confirming.

To deploy from an OCI registry instead:
Terminal window
```
uds deploy ghcr.io/<your-org>/dev/my-first-bundle:0.0.1 --confirm
```

Verification

After deployment, confirm the pods are running:

uds zarf tools kubectl get pods -A

Troubleshooting

Problem: Bundle architecture mismatch

Symptom: bundle architecture mismatch error during deploy.

Solution: Use -a amd64 or -a arm64 to specify the target architecture explicitly.

Problem: OCI pull errors

Symptom: Errors pulling packages from an OCI registry.

Solution: Verify registry credentials with uds zarf tools registry login.

Problem: Package deploy timeout

Symptom: A package deployment times out before completing.

Solution: Set timeout on the package in uds-bundle.yaml (e.g., timeout: 10m). To retrieve logs from the most recent operation, run uds logs.

Use Bundle Overrides: Customize package configuration at deploy time without modifying the bundle.
Use UDS Runner: Automate tasks with UDS Runner’s built-in task execution.
Monitor a Cluster: Inspect running workloads and Pepr events from the CLI.