distro

package
v0.42.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package distro defines the API types for a distro package.

Index

Constants

View Source
const (
	// MaxNameLength bounds Metadata.Name, which becomes a repository path component.
	MaxNameLength = 64
	// MaxVersionLength bounds Metadata.Version, which becomes a tag.
	MaxVersionLength = 48
)

A package's name and version both end up inside OCI references, and those have hard limits an operator never sees until a push fails. `cargoship publish` lands a package at <registry>/<name>:<version>, so the name is a repository path component and the version is a tag; a mirror writes a record whose reference is built from both.

The limits below leave room inside the two the registry specification sets:

  • a tag is at most 128 characters: `[\w][\w.-]{0,127}`
  • a repository name is at most 255 characters in total, host excluded

What makes a bound necessary rather than tidy is that neither limit is reliably enforced on the way out. oras's tag pattern does catch an over-long tag, but its repository pattern does not implement the 255-character total -- a 300-character name parses locally and is refused by the registry, after the package has been built and carried. Bounding the name here is what moves that failure to the moment the definition is read.

The numbers are deliberately generous. The longest name in this repository is 18 characters ("rancher-k3s-multi"), so 64 is roughly three times anything real, and the pair still fits a record reference with 7 characters to spare.

View Source
const (
	// CompressionNone writes the image tarballs uncompressed. This is the default.
	CompressionNone = "none"
	// CompressionGzip writes the image tarballs with gzip compression.
	CompressionGzip = "gz"
	// CompressionZstd writes the image tarballs with zstd compression.
	CompressionZstd = "zstd"
)

Compression formats accepted by ImageConfig.Compression.

Variables

This section is empty.

Functions

func ChartManifests added in v0.36.0

func ChartManifests(engine dig.Mapping) map[string]ChartManifest

ChartManifests reads `.spec.config.engine.manifest` out of an engine mapping. It takes the mapping rather than a Config so that a package's own spec and a mapping already resolved for one node are both readable, and it never writes to it -- dig's DigMapping inserts an empty mapping for a key that is absent, which would add a bare `manifest:` to a package that has none.

func ValidateReferenceLengths added in v0.42.0

func ValidateReferenceLengths(name, version string) error

ValidateReferenceLengths reports whether a package's name and version fit the references built from them.

It is a runtime check as well as a schema constraint because the two catch different things. The schema's maxLength is what an editor and `cargoship validate` enforce, and it is the right place for the rule to be published; but the load path does not apply the schema, so without this a `cargoship create` would build the package anyway. It is also the only check that can speak for a package built by an older cargoship, where the definition is no longer available and the only thing left is the metadata inside the archive.

An empty version is not an error here. Whether a version is required is the caller's rule -- publishing demands one, mirroring tolerates a package without one -- and this function answers only the question it is named for.

Types

type Actions

type Actions struct {
	// OnCreate lists the actions cargoship runs when it creates the package.
	OnCreate zarf.ZarfComponentActionSet `json:"onCreate,omitempty"`
}

Actions defines the actions cargoship runs during specific phases of building the distro package.

type BuildData

type BuildData struct {
	// Architecture is the CPU architecture used to build the package. Populated only when the package targets a single architecture.
	Architecture api.Arch `json:"architecture,omitempty"`
	// Architectures lists the CPU architectures used to build the package.
	Architectures api.Arches `json:"architectures,omitempty"`
	// Timestamp is the time the package was created.
	Timestamp string `json:"timestamp,omitempty"`
	// Version records the distro version used to build the package.
	Version string `json:"version,omitempty"`
	// RegistryOverrides maps each original registry to the registry actually used to build the package.
	RegistryOverrides map[string]string `json:"registryOverrides,omitempty"`
	// FileOverrides maps each source URL prefix to the mirror or local directory files were
	// downloaded from instead. Like RegistryOverrides, this is the configuration the build was
	// given. For what each override actually did, see FileSources.
	FileOverrides map[string]string `json:"fileOverrides,omitempty"`
	// FileSources records every file whose source an override redirected: what the definition
	// declared, where the bytes were read from instead, and the checksum they were verified
	// against. It is empty for a build that used no overrides, so a package built without them
	// is unchanged. Entries are in the order the files were staged, which is the order they
	// appear in the definition, so a reproducible build still produces identical output.
	FileSources []FileSource `json:"fileSources,omitempty"`
	// Signed indicates whether the package was signed. A nil value means the signing status was not recorded.
	Signed *bool `json:"signed,omitempty"`
	// Reproducible indicates Build.Timestamp was pinned to a fixed value
	// (config.Timestamp) instead of the actual build time, so identical
	// package inputs produce byte-identical output.
	Reproducible bool `json:"reproducible,omitempty"`
	// ProvenanceFiles lists files in the package that checksums.txt does not cover.
	// These are files added after cargoship generates checksums, for example signature files.
	// The signed distro.yaml authenticates this list.
	ProvenanceFiles []string `json:"provenanceFiles,omitempty"`
}

BuildData holds information recorded when the package was built.

func (BuildData) Arches

func (b BuildData) Arches() api.Arches

Arches returns the CPU architectures the package was built for. It prefers Architectures and falls back to the single Architecture field.

type ChartManifest added in v0.36.0

type ChartManifest struct {
	// Enabled reports whether the chart's images are carried onto hosts. An entry
	// that does not say is enabled.
	Enabled bool
	// Images lists the offline images this chart needs, carried in the package and
	// uploaded only while the chart is enabled.
	Images []string
	// Values is the chart's Helm values: a YAML string, which is passed through as
	// the values file's contents, or a mapping, which is marshalled back to YAML.
	Values any
}

ChartManifest is one entry of the engine's manifest section: the Helm values cargoship writes to that chart's HelmChartConfig, and the images the chart needs.

type Config

type Config struct {
	// Files lists files that cargoship writes to every host, no matter which install method it uses.
	Files v1alpha1.Files `json:"files,omitempty"`
	// ImagesConfig holds settings for the images bundled with the package.
	ImagesConfig ImageConfig `json:"imageConfig,omitempty"`
	// OS holds settings applied to the host operating system.
	OS OS `json:"os,omitempty"`
	// Engine holds configuration passed through to the distro engine.
	Engine dig.Mapping `json:"engine,omitempty"`
	// Manifests lists on-host paths -- each one the Target of a Files entry -- that cargoship
	// kubectl-applies, in order, from the leader once it bootstraps. Delivery is already solved by
	// Files; this is only the marker that says "and apply this one," e.g. for a CNI a package
	// declares. A distro with no apply mechanism (rke2/k3s use HelmChartConfig instead) ignores it.
	Manifests []string `json:"manifests,omitempty"`
}

Config holds the configuration for the distro engine.

func (Config) AllImages added in v0.36.0

func (c Config) AllImages() []string

AllImages returns every image the package carries: imageConfig.images, plus the images of every chart manifest whether or not it is enabled. This is the set that has to be pulled at create time and enumerated when a package's layers are collected -- LayersFromImages fails on a declared image whose blobs are absent, so a chart's images must be in the package even when no cluster will be sent them.

func (Config) EnabledImages added in v0.36.0

func (c Config) EnabledImages() []string

EnabledImages returns the images that reach a host: imageConfig.images, plus the images of the chart manifests that are enabled. A disabled chart's images stay in the package and are not exported or uploaded.

func (Config) JSONSchemaExtend

func (Config) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend pins down the shape of the engine's manifest section, whose values are Helm values written into a HelmChartConfig: either a YAML string or a mapping cargoship serializes to YAML for the chart. Engine is otherwise a free-form mapping handed to the distro engine, so the section list stays open and every other section keeps validating as it did.

type Distro

type Distro struct {
	// APIVersion identifies the API group and version of this configuration document.
	APIVersion string `json:"apiVersion,omitempty" jsonschema:"enum=colonel-byte.dev/v1alpha1,enum=zarf.dev/v1alpha1"`
	// Kind identifies the document type. The value must be Distro, or ZarfDistro on a document written before the move to colonel-byte.dev.
	Kind v1alpha1.Kind `json:"kind" jsonschema:"enum=Distro,enum=ZarfDistro"`
	// Metadata holds identifying information for the distro package.
	Metadata Metadata `json:"metadata"`
	// Build holds information recorded when the package was built.
	Build BuildData `json:"build,omitempty"`
	// Spec holds the configuration for the distro package.
	Spec Spec `json:"spec"`
}

Distro is the root object of a distro package configuration document.

func (Distro) Arches

func (distro Distro) Arches() api.Arches

Arches returns the CPU architectures the package covers. A built package records them under build, so that is preferred; a definition that has not been built yet only carries what the metadata targets.

type FileSource

type FileSource struct {
	// Path is where the file was staged inside the package, for example "files/0/k3s". It
	// identifies the entry even when several files share a declared source.
	Path string `json:"path"`
	// Declared is the source the distro definition named.
	Declared string `json:"declared"`
	// Resolved is where cargoship read the bytes from instead: a mirror URL, or a path on
	// the build host.
	Resolved string `json:"resolved"`
	// Override is the Source prefix of the override that matched, which is the one that won
	// when several could have. It is empty when the bytes came from a local content store.
	Override string `json:"override,omitempty"`
	// Store names the local content store the bytes were read from -- a hauler store or a zarf
	// package passed to --content-store. It is empty when an override or the declared source
	// was used.
	Store string `json:"store,omitempty"`
	// Shasum is the checksum the bytes were verified against. Neither an override nor a
	// content store is accepted for a file that declares none, so this is empty only for a
	// file read from a registry, which is verified by the digests below instead.
	Shasum string `json:"shasum"`
	// ManifestDigest is the digest of the manifest an oci:// source resolved to for this
	// entry's architecture. It is empty for every other kind of source.
	ManifestDigest string `json:"manifestDigest,omitempty"`
	// LayerDigest is the digest of the layer the bytes were read from, which the registry
	// verified them against on fetch. It is empty for every other kind of source.
	LayerDigest string `json:"layerDigest,omitempty"`
}

FileSource records where one file in the package was actually read from, for a file whose declared source a --file-override redirected.

This is evidence about a build that happened, which is what separates it from BuildData.FileOverrides: an override can be configured and match nothing, and the configuration alone cannot tell you which of several overlapping prefixes won for a given file. Resolved names a path on the build host when the override pointed at a local directory, so it discloses that much of the build host's layout to whoever reads the package.

type ImageConfig

type ImageConfig struct {
	// Compression sets the compression format for the image tarballs.
	Compression string `json:"compression,omitempty" jsonschema:"default=none,enum=none,enum=gz,enum=zstd"`
	// Path is the upload destination for the image tarballs.
	Path string `json:"path,omitempty"`
	// Images lists the offline images required by the package.
	Images []string `json:"images,omitempty" jsonschema:"uniqueItems=true"`
}

ImageConfig holds settings for the images cargoship writes to a host.

func (ImageConfig) TarballSuffix

func (c ImageConfig) TarballSuffix() (string, error)

TarballSuffix returns the file suffix image tarballs get for the configured compression format. The suffixes match the archive extensions a host imports, so a compressed tarball is still picked up. An unset format means no compression. It returns an error for a format cargoship cannot write.

type Metadata

type Metadata struct {
	// Uncompressed disables compression for this package when true.
	Uncompressed bool `json:"uncompressed,omitempty"`
	// Architecture is the CPU architecture this distro package targets. Use Architectures to target more than one.
	Architecture api.Arch `json:"architecture,omitempty" jsonschema:"default=amd64"`
	// Architectures lists the CPU architectures this distro package targets. It supersedes Architecture, which stays valid for a package targeting a single architecture.
	Architectures api.Arches `json:"architectures,omitempty"`
	// Name identifies the distro package. It becomes a repository path component in every
	// reference built from the package, so it is bounded -- see MaxNameLength.
	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$,maxLength=64"`
	// Description explains what this distro package does.
	Description string `json:"description,omitempty"`
	// Version is the distro version cargoship installs. We recommend matching it to the Kubernetes version you install.
	// It becomes the tag in every reference built from the package, so it is bounded -- see MaxVersionLength.
	Version string `json:"version,omitempty" jsonschema:"maxLength=48"`
	// Annotations holds key-value pairs added to the OCI manifest.
	Annotations map[string]string `json:"annotations,omitempty"`
	// URL sets the OCI annotation for more information about the image.
	URL string `json:"url,omitempty"`
	// Authors sets the OCI annotation for the contact details of the people or organization responsible for the image.
	Authors string `json:"authors,omitempty"`
	// Documentation sets the OCI annotation for the URL to the image documentation.
	Documentation string `json:"documentation,omitempty"`
	// Source sets the OCI annotation for the URL to the image source code.
	Source string `json:"source,omitempty"`
	// Vendor sets the OCI annotation for the name of the organization or individual that distributes the image.
	Vendor string `json:"vendor,omitempty"`
	// AggregateChecksum is the checksum of the checksums.txt file, which lists the checksum for every layer in the package.
	AggregateChecksum string `json:"aggregateChecksum,omitempty"`
}

Metadata holds identifying information for a distro package.

func (Metadata) Arches

func (m Metadata) Arches() api.Arches

Arches returns the CPU architectures the package targets. It prefers Architectures and falls back to the single Architecture field, so callers never have to know which one the package set.

type OS

type OS struct {
	// Sysctl maps sysctl keys to the values cargoship applies to a host.
	Sysctl map[string]string `json:"sysctl,omitempty"`
	// FAPolicyd holds the fapolicyd config file contents cargoship writes to a host.
	FAPolicyd string `json:"fapolicyd,omitempty"`
	// SELinux holds the custom SELinux policy cargoship applies to a host.
	SELinux SELinux `json:"selinux,omitempty"`
	// Files lists files cargoship uploads to a host.
	Files v1alpha1.Files `json:"files,omitempty"`
	// Kernel lists the kernel modules cargoship enables on the host.
	Kernel []string `json:"kernel,omitempty"`
	// Environment maps environment variables cargoship sets on the host.
	Environment map[string]string `json:"env,omitempty"`
}

OS holds settings applied to a host.

func (OS) JSONSchemaExtend

func (OS) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend widens sysctl values to accept numbers alongside strings, so unquoted numeric values in YAML validate.

type SELinux

type SELinux struct {
	// Modules lists the CIL policy modules cargoship installs on a host.
	Modules []SELinuxModule `json:"modules,omitempty"`
	// Booleans maps SELinux boolean names to the values cargoship sets persistently on a host.
	Booleans map[string]bool `json:"booleans,omitempty"`
	// FileContexts lists the file context mappings cargoship adds on a host.
	FileContexts []SELinuxFileContext `json:"fileContexts,omitempty"`
}

SELinux holds the custom SELinux policy cargoship applies to hosts running SELinux in enforcing mode. Every field is optional, and a host that is not enforcing is left alone.

func (SELinux) IsZero

func (s SELinux) IsZero() bool

IsZero reports whether no SELinux policy is configured, so a phase can gate on it.

type SELinuxFileContext

type SELinuxFileContext struct {
	// Path holds the path regular expression the mapping applies to.
	Path string `json:"path" jsonschema:"example=/var/lib/rancher(/.*)?"`
	// Type names the SELinux type the matching paths are labeled with.
	Type string `json:"type" jsonschema:"example=container_var_lib_t"`
	// FileType restricts the mapping to one kind of filesystem object.
	FileType string `` /* 134-byte string literal not displayed */
}

SELinuxFileContext holds a single file context mapping cargoship adds with semanage.

type SELinuxModule

type SELinuxModule struct {
	// Name identifies the module to semodule, and names the file cargoship writes to the host.
	Name string `json:"name" jsonschema:"pattern=^[a-zA-Z0-9][a-zA-Z0-9_-]*$"`
	// Priority holds the semodule priority the module installs at.
	Priority int `json:"priority,omitempty" jsonschema:"default=400"`
	// CIL holds the Common Intermediate Language policy source semodule installs.
	CIL string `json:"cil"`
}

SELinuxModule holds a single CIL policy module cargoship installs with semodule.

type Spec

type Spec struct {
	// Type selects the distro engine: rke2, k3s, or upstream.
	Type string `json:"type" jsonschema:"enum=rke2,enum=k3s,enum=upstream"`
	// Version is the version of the distro engine.
	Version string `json:"version"`
	// Actions defines the actions cargoship runs while building the package.
	Actions Actions `json:"actions,omitempty"`
	// Config holds the distro engine configuration.
	Config Config `json:"config"`
	// Values holds the default values the package is built with, and the schema they must satisfy.
	Values Values `json:"values,omitempty"`
}

Spec holds the configuration for a distro package.

type ValueMapping

type ValueMapping struct {
	// Source is the dotted path to read from the resolved values, e.g. .cilium.encryption.enabled
	Source string `json:"source" jsonschema:"example=.cilium.encryption.enabled"`
	// Target is the dotted path to write, relative to spec.config.engine,
	// e.g. .manifest.rke2-cilium.encryption.enabled
	Target string `json:"target" jsonschema:"example=.manifest.rke2-cilium.encryption.enabled"`
}

ValueMapping projects one value onto one place in the engine configuration.

type Values

type Values struct {
	// Files lists the YAML values files cargoship merges, in order, to build the package's default values. Each entry is a path relative to the package definition, an absolute path, or a URL. A later file overrides an earlier one, key by key.
	Files []string `json:"files,omitempty" jsonschema:"example=values.yaml,example=overrides/prod.yaml,example=https://example.com/values.yaml"`
	// Schema is the JSON Schema document the merged values must satisfy. Cargoship checks the values against it when it builds the package, and refuses to build when they do not match. The schema must not use $ref.
	Schema string `json:"schema,omitempty" jsonschema:"example=values.schema.json"`
	// Mappings project values onto the engine configuration, so that one value a
	// cluster sets reaches wherever the distro needs it. Each mapping reads the
	// source path out of the resolved values and writes it to the target path,
	// which is relative to spec.config.engine. A source the values do not define
	// is left alone, so the package's own engine configuration stands as the
	// default.
	Mappings []ValueMapping `json:"mappings,omitempty"`
}

Values declares the values a package ships with. Values are the Helm-style configuration described by ZEP-0021: a nested structure addressed by dotted paths, which templates in the package read as .Values.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL