Package Metadata

Packages published to UDS Registry and consumed by other UDS products support a set of standard metadata annotations that improve discoverability and user experience across UDS products.

These annotations are defined under metadata.annotations in your zarf.yaml package config:

kind: ZarfPackageConfig
metadata:
  annotations:
    dev.uds.title: "Example Package"
    dev.uds.categories: "Development, Testing"

Production annotations

The following annotations are recommended for production packages and are used across UDS products:

Annotation	Description	Example	Products
`dev.uds.title`	Human-readable package title	`"GitLab Runner"`	UDS Registry, UDS Fleet, UDS Portal
`dev.uds.categories`	Dynamic category list	`"Software Dev, Kubernetes (K8s)"`	UDS Registry, UDS Fleet
`dev.uds.keywords`	Search keywords	`"CI/CD Pipelines, Automation, GitLab"`	UDS Registry
`dev.uds.tagline`	Short package tagline	`"Open Source CI/CD Job Execution Tool"`	UDS Registry
`dev.uds.icon`	Base64 icon as data URI	`"data:image/png;base64,iVBORw0KGgo..."`	UDS Registry, UDS Fleet, UDS Portal

Implementation guidelines

Title (dev.uds.title)

MUST be a human-readable title-case string that clearly identifies the package.
SHOULD match the official product name when packaging existing software.

Categories (dev.uds.categories)

MUST be a comma-with-space-separated string ("Category One, Category Two").
SHOULD include 1-3 categories from these standard options:

Standard categories

AI
Cloud Native
Collaboration
Command And Control
Cybersecurity
Data Engineering
Databases
Digital Engineering
IT Management
Infrastructure
Kubernetes (K8s)
Load Balancing
Networking
Observability
Operator
Pipelines
Productivity
Security
Software Dev
Web

MAY include new categories when existing categories do not adequately describe the package.

Keywords (dev.uds.keywords)

MUST be a comma-with-space-separated string of 3-7 relevant search terms.
SHOULD include alternative terms and abbreviations users might search for.

Tagline (dev.uds.tagline)

MUST be one concise sentence (recommended 5-10 words) describing package function.

Icon (dev.uds.icon)

MUST be encoded as a base64 data URI.
SHOULD use .png or .svg (.svg recommended), square aspect ratio, transparent background.
RECOMMENDED size: 200x200px.

Provisional annotations

These annotations are experimental and may evolve over time:

Annotation	Description	Example	Products
`dev.uds.system`	Whether a package is system-level (OS/firmware) vs application-level	`"true"`	UDS Fleet
`dev.uds.compat/[label-name]`	Hardware compatibility requirement for the target cluster; `[label-name]` is a placeholder for a capability label defined by your platform integrator	`dev.uds.compat/databus: can,can-fd`	UDS Fleet

Provisional implementation guidelines

Hardware compatibility (dev.uds.compat/*)

The dev.uds.compat/* annotation scheme lets package authors declare hardware compatibility requirements that UDS Fleet enforces before making a package available for deployment to a cluster. Each annotation key targets a specific compatibility dimension; each value is the set of accepted identifiers for that dimension.

The label names and values available to you are defined by your platform integrator — the organization responsible for orchestrating the deployment ecosystem you are targeting (for example, a systems integrator coordinating a multi-vendor solution). That integrator provides an initialization process that stamps each cluster with its hardware capabilities as labels, and publishes a spec of what label names and values package authors can use.

[label-name] MUST match a label name from your platform integrator’s compatibility spec. Consult that spec for available label names and values before writing compat annotations.
Values MUST be a comma-separated list with no spaces (can,can-fd). Multiple values within one annotation use OR semantics: the cluster must match at least one.
Multiple dev.uds.compat/* annotations on the same package use AND semantics: the cluster must satisfy all of them.
A package with no dev.uds.compat/* annotations has no compatibility constraints and deploys to any cluster.

kind: ZarfPackageConfig
metadata:
  annotations:
    # Cluster must have CAN OR CAN-FD databus, AND obd2-extended telematics
    dev.uds.compat/databus: can,can-fd
    dev.uds.compat/telematics: obd2-extended

UDS Package Requirements - pre-publish checklist for required capabilities and standards.
Create a UDS Package - end-to-end guide for building a package that meets UDS requirements.