artifacts/a11oy-uds/docs/UDS-BUNDLE.md

a11oy — UDS Bundle integration

The Zarf package shipped here is a first-class member of a Defense Unicorns (UDS) bundle. The shipped uds-bundle.yaml composes it as a single-package bundle so an operator can run uds deploy end-to-end without hand-writing any UDS YAML.

Bundle definition

kind: UDSBundle
metadata:
  name: a11oy
  description: |
    A11oy — governed execution fabric. Single-package UDS bundle that
    stages @a11oy/core, @a11oy/connection, provenance sidecars, and the
    v0.2 shared packages under /opt/a11oy/ on the target node via Zarf.
  version: 0.2.0
  authors: A11oy / SZL Holdings
  url: https://github.com/szl-holdings/a11oy
  architecture: multi

packages:
  - name: a11oy-uds
    path: ../../dist/a11oy-uds  # relative to artifacts/a11oy-uds/uds-bundle.yaml
    ref: 0.2.0

The path: form points at a locally-built Zarf tarball; once the package publishes to OCI it can be switched to:

packages:
  - name: a11oy-uds
    repository: ghcr.io/szl-holdings/a11oy-uds
    ref: 0.2.0

both forms are valid UDS-CLI syntax (uds-cli v0.27+).

Build the bundle

# Prereq: Zarf v0.49+, uds-cli v0.27+, and a built a11oy-uds Zarf package
# (run artifacts/a11oy-uds/scripts/build.sh first).

cd artifacts/a11oy-uds
uds create . --confirm

This produces uds-bundle-a11oy-<arch>-0.2.0.tar.zst next to the uds-bundle.yaml. The bundle tarball is self-contained — it embeds the referenced Zarf package(s) and can be moved across an air-gap.

Inspect the bundle

uds inspect uds-bundle-a11oy-<arch>-0.2.0.tar.zst

Expected output (abbreviated):

kind: UDSBundle
metadata:
  name: a11oy
  version: 0.2.0
packages:
  - name: a11oy-uds
    ref: 0.2.0
    description: A11oy — governed execution fabric ...

Deploy the bundle

uds deploy uds-bundle-a11oy-<arch>-0.2.0.tar.zst --confirm

UDS-CLI delegates each packages[*] entry to zarf package deploy under the hood — the on-node effect is identical to running zarf package deploy a11oy-uds-0.2.0.tar.zst --confirm directly.

Remove the bundle

uds remove a11oy --confirm

This invokes zarf package remove a11oy-uds --confirm for each package in the bundle (in reverse order).

Multi-package composition

The same a11oy-uds Zarf package can be added to a richer multi-product bundle alongside sentra and amaru:

kind: UDSBundle
metadata:
  name: plane-1
  version: 0.1.0
packages:
  - name: a11oy-uds
    repository: ghcr.io/szl-holdings/a11oy-uds
    ref: 0.2.0
  - name: sentra
    repository: ghcr.io/szl-holdings/sentra
    ref: <pinned>
  - name: amaru
    repository: ghcr.io/szl-holdings/amaru
    ref: <pinned>

That composition is the role of the existing szl-holdings/uds-mesh repo; the a11oy-uds package is one of the three legs it composes.

Compatibility matrix

component	tested-against version	notes
Zarf CLI	v0.49.0	zarf package create + zarf package deploy
UDS CLI	v0.27.0	uds create, uds inspect, uds deploy, uds remove
cosign	v2.4.1	blob signing + keyless OIDC verify
Kubernetes (target)	package-dependent	v0.2 stages runtime, provenance, attestations, and shared package artifacts under /opt/a11oy/

v0.2.0 is an operator proof-point package: it stages the A11oy runtime, provenance sidecars, optional attestations, and shared package artifacts. It is not a Defense Unicorns endorsement or UDS catalog acceptance claim; use zarf package inspect and the manifest/attestation verifiers before deploy.