Manifest reference

Status: packtrix.io/v1alpha1, an alpha API. Fields and defaults may still change in later releases; the release notes say what changed.

Packtrix reads packtrix.yaml from the current directory by default. Use -f <file> to choose another file.

Minimal manifest

apiVersion: packtrix.io/v1alpha1
kind: OfflineRepository
metadata:
  name: datacenter
spec:
  targets:
    - distro: ubuntu-24.04
    - distro: rocky-9
  packages: [curl, jq, nfs-common]

Everything else has a default.

Editor support

A JSON Schema of the manifest, schemas/v1alpha1/offlinerepository.json, lets editors complete fields and values, show what each field does and its default, and mark mistakes as you type. Editors that use the YAML language server, such as VS Code with Red Hat’s YAML extension, or Neovim, find it through a comment in the manifest:

# yaml-language-server: $schema=https://raw.githubusercontent.com/packtrix/packtrix/main/schemas/v1alpha1/offlinerepository.json

Other editors can map the schema to packtrix.yaml in their settings. The schema checks each field like packtrix validate, but not the rules across fields, such as unique target names or only naming an existing target: packtrix validate still has the last word. It is generated from the API types, with make update-schema.

Full structure

apiVersion: packtrix.io/v1alpha1
kind: OfflineRepository
metadata:
  name: datacenter
spec:
  targets:                                   # which machines (required)
    - name: ubuntu-gpu                       # default: the distro name
      distro: ubuntu-24.04                   # built-in distro …
      architectures: [amd64, arm64]          # default: [amd64]
      extraRepos: []                         # … plus your own repositories
    - name: oracle-9
      repos: []                              # … or a distro defined from scratch

  packages: []                               # what the machines need (required)

  autoRepos:                                 # automatic vendor repositories
    enabled: true
    deny: []

  resolve:                                   # how dependencies are resolved
    baseline: minimal
    recommends: false
    alternatives: first
    exclude: []

  updates:                                   # how updates are picked up
    check: ""
    accept: all
    minAge: 0s
    publish: approval

  publish:                                   # where and how repositories are written
    path: ./repos
    signing: {}
    keepSnapshots: 3

  export:                                    # how bundles are written
    format: tar.zst
    splitSize: ""

spec.targets

A list of targets. A target is either a short form - distro: <name> or an object:

distro as an object

Use the object form only to change a distro’s defaults:

distro:
  name: rocky-9
  components: [baseos, appstream, crb]
  mirror: https://nexus.internal/repository/
  auth: { … }

Repository object

Used in extraRepos and repos:

extraRepos:
  - name: internal-tools
    type: apt
    url: https://pkgs.internal/apt
    suite: stable
    components: [main]
    gpgKey: keys/internal.gpg

Auth object

Used in distro.auth and in repository objects:

A secret reference is env:NAME (read an environment variable) or file:/path (read a file). Secrets themselves never appear in the manifest.

spec.packages

A list of packages, written once for all targets. An entry is either a string (the package name) or an object:

Version constraints

Versions are compared with each format’s native rules (dpkg ordering for deb; rpm ordering, including epochs, for rpm).

Always quote versions. Unquoted, YAML reads 1.30 as the number 1.3. Packtrix rejects unquoted numeric versions rather than guess.

spec.autoRepos

spec.resolve

spec.updates

spec.publish

spec.export

Validation rules

packtrix validate and packtrix plan reject a manifest when:

• it contains an unknown or duplicated field. A typo such as architecture: instead of architectures: is an error, never silently ignored;
• a target has both distro and repos, or neither;
• two targets have the same name;
• only or except names an unknown target;
• an entry has both only and except;
• a target’s repositories disagree on distribution, release or format;
• a listed package isn’t available for a target it applies to;
• a package from a versioned vendor repository (e.g. Kubernetes) has no version;
• a package matches several unrelated vendor repositories and has no repo.

Every error names the target, the package and what to change.

Examples

• examples/k8s-node-prereqs.yaml: Kubernetes node prerequisites for Ubuntu 24.04, Ubuntu 22.04 and Debian 12
• examples/mixed-fleet.yaml: Ubuntu, Rocky and RHEL with Docker, Kubernetes and NVIDIA packages
• examples/custom-repos.yaml: an internal repository and a distro defined from scratch