distro

package
v0.42.4 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: 51 Imported by: 0

Documentation

Overview

Package distro is used for creating/deploying distro package

Index

Constants

View Source
const (
	// RecordKindMirror is a record written by `cargoship mirror`.
	RecordKindMirror = "mirror"
	// RecordKindPackage is a record written by `cargoship publish`.
	RecordKindPackage = "package"
)

Record kinds, and the tag prefix each one takes.

The kind is in the tag because the two describe different things to do. A published package is one artifact to pull whole; a mirror is loose content a node reaches by its own references. A consumer looking for "where do I pull the newest rancher-rke2-multi-cilium" wants the first and would be misled by the second, so they cannot share a tag.

The `_` prefix is what keeps them out of the way of a package someone publishes into this same repository: a tag may begin with `_` but a version string does not, so `cargoship:1.0.0` and `cargoship:_pkg.rke2.1.0.0` cannot collide however the repository is otherwise used.

View Source
const MirrorRecordSchemaVersion = "1.0"

MirrorRecordSchemaVersion versions the record a mirror writes about itself. A reader handed a record with a major it does not know should say so rather than decode it. Bump the minor for a field added, the major for a field removed or given a new meaning.

View Source
const RecordRepo = "cargoship"

RecordRepo is the one repository every record lives in, under whatever prefix the target carries.

It is reserved rather than incidental. A package published with `cargoship publish` lands at <registry>/<name>:<version>, so a record written there would be the same reference as a real package and one would silently overwrite the other.

One repository rather than one per package, which is what this used to be, because discovery has to work on the registries people actually use. Finding records spread across repositories means asking for the registry's catalogue, and `/v2/_catalog` is a wider permission than pushing where it exists at all -- ghcr.io answers it with 403 DENIED and Docker Hub does not implement it, so `cargoship ls` could not list either. Records in one repository are one `/v2/<repo>/tags/list` away, which every registry serves and which needs no more than pull.

Variables

This section is empty.

Functions

func Build added in v0.39.0

func Build(ctx context.Context, distroPath string, opts CreateOptions) (*layout.DistroLayout, error)

Build assembles a distro package and returns its layout without archiving it.

It is the half of Create that produces the package; Create is Build plus the archive step. Splitting them is what lets a caller about to consume the package in this same process -- `cargoship dev apply` -- skip compressing a multi-gigabyte layout and decompressing the same bytes straight back again.

The caller owns the returned layout and must Cleanup it. That is the one thing to get right when reaching for this rather than Create, which cleans up the layout itself because the archive is the only thing meant to outlive it.

func Create

func Create(ctx context.Context, distroPath string, output string, opts CreateOptions) (_ string, err error)

Create builds a distro package, writes it to output as an archive, and returns the path to that archive.

func Import added in v0.35.0

func Import(ctx context.Context, source string, opts ImportOptions) (string, error)

Import converts an OCI Image Layout archive or directory, such as one written by `skopeo copy ... oci-archive:`, into a native Cargoship package.

func ImportLayout added in v0.35.0

func ImportLayout(ctx context.Context, source string, opts ImportOptions) (*layout.DistroLayout, error)

ImportLayout reads an OCI Image Layout archive or directory and unpacks it into a DistroLayout.

func Load

func Load(ctx context.Context, source string, opts LoadOptions) (*layout.DistroLayout, error)

Load fetches, verifies, and loads a Zarf package from the specified source.

func Mirror added in v0.39.0

func Mirror(ctx context.Context, l *layout.DistroLayout, target string, opts MirrorOptions) error

Mirror publishes the contents of a built package into target, a registry host optionally followed by a repository prefix.

This is not `publish`. Publish pushes the package as one OCI artifact, to be pulled back as a package; Mirror pushes what the package carries as individually pullable images and files, so that the registry a fleet is already pointed at holds the content its nodes will ask for.

The reference each item lands under is computed, never chosen, and the same two rules are applied by anything reading a mirror back. See images.Push and contentstore.FileRef.

func Publish

Publish used to publish a distro package to an oci registry

func Pull

func Pull(ctx context.Context, source, destination string, opts PullOptions) (string, error)

Pull takes a source URL and destination directory, fetches the Cargoship Distro package from the given sources, and returns the path to the fetched package.

func RecordRef added in v0.42.0

func RecordRef(target, kind, name, version string) (string, error)

RecordRef is where the record of one kind, package and version lives under target.

Computed, never chosen, for the same reason the references in pkg/contentstore are: the write and the read halves have to agree without consulting each other.

The name and version are bounded by the schema -- see distro.MaxNameLength -- which is what makes this safe to put in a tag. A tag is at most 128 characters, and the longest prefix here plus the two bounds comes to 121.

Types

type CreateOptions

type CreateOptions struct {
	OCIConcurrency int
	CachePath      string
	IsInteractive  bool
	// Architecture narrows a package that targets several architectures down to a single one.
	// A package that targets one architecture ignores it.
	Architecture string
	// Reproducible pins Build.Timestamp to config.Timestamp instead of the
	// current time, and is recorded on Build.Reproducible, so identical package
	// inputs produce byte-identical output.
	Reproducible      bool
	RegistryOverrides []images.RegistryOverride
	// FileOverrides redirect the file downloads a distro definition declares to an internal
	// mirror or to a directory of pre-staged assets.
	FileOverrides []fileoverride.Override
	// ContentStore is the path to a local content bundle that images and files are resolved
	// from before the network: a hauler store directory or archive, or a built zarf package.
	// The format is read from the bundle, not from the path. Empty means no store.
	ContentStore []string
	// SigningKeyPath and SigningKeyPassword sign the package as part of creation
	// when set. Empty values are a no-op -- see DistroLayout.SignPackage.
	SigningKeyPath     string
	SigningKeyPassword string
	// Tag overrides the package metadata version.
	Tag string
	types.RemoteOptions
}

CreateOptions are the optional parameters to create

type ImportOptions added in v0.35.0

type ImportOptions struct {
	Architecture         string
	Output               string
	VerifyBlobOptions    *signing.VerifyBlobOptions
	VerificationStrategy layout.VerificationStrategy
}

ImportOptions declares optional parameters for an Import operation.

type ListMirroredOptions added in v0.42.0

type ListMirroredOptions struct {
	types.RemoteOptions
	// Username and Password authenticate against the target. Empty falls back to the Docker
	// configuration file.
	Username string
	Password string
	// DialContext opens the connections the listing travels over, which is how it reaches a
	// registry only a cluster node can see. See pkg/tunnel.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
	// CABundle is trusted in addition to the system roots, which is how a listing reads a
	// registry serving a certificate from a private CA. See images.ClientOptions.CABundle.
	CABundle []byte
	// ClientCertificate is presented to a registry that requires one of every client. See
	// images.ClientCertificate.
	ClientCertificate images.ClientCertificate
	// Name scopes the listing to one package, which also avoids the registry catalogue
	// entirely. See ListMirrored.
	Name string
}

ListMirroredOptions are the optional parameters to ListMirrored. The transport half is deliberately the same set MirrorOptions carries, so that reading a mirror back reaches exactly the registries writing one can.

type LoadOptions

type LoadOptions struct {
	Shasum       string
	Architecture string
	Output       string
	// number of layers to pull in parallel
	OCIConcurrency int
	// CachePath is used to cache layers from OCI package pulls
	CachePath         string
	VerifyBlobOptions *signing.VerifyBlobOptions
	// Only applicable to OCI + HTTP
	types.RemoteOptions
	// CABundle is one or more PEM-encoded certificates to trust in addition to the system roots,
	// for a registry or an HTTP source serving a certificate the management node does not trust.
	//
	// Bytes rather than a path, so a caller holding the certificate in memory -- a controller
	// reading it out of a Kubernetes secret, say -- does not have to write it to a file first.
	// Only applicable to OCI + HTTP.
	CABundle []byte
	// ClientCertificate is presented to a registry that requires one of every client. Zero,
	// which is the usual case, presents none.
	//
	// Only applicable to OCI: an http:// source is fetched by a client that presents nothing,
	// which is the one place this and CABundle are not symmetrical.
	ClientCertificate images.ClientCertificate
	// VerificationStrategy for explicit definition
	layout.VerificationStrategy
}

LoadOptions are the options for LoadDistro.

type MirrorOptions added in v0.39.0

type MirrorOptions struct {
	types.RemoteOptions
	OCIConcurrency int
	Retries        int
	// Images and Files select what is mirrored. Both false means both, which is what a command
	// line that named neither asked for.
	Images bool
	Files  bool
	// Username and Password authenticate both halves of the mirror against the target.
	// Empty falls back to the Docker configuration file.
	Username string
	Password string
	// DialContext opens the connections both halves travel over, which is how a mirror reaches
	// a registry only a cluster node can see. See images.ClientOptions.DialContext and
	// pkg/tunnel.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
	// CABundle is trusted in addition to the system roots, which is how a mirror verifies a
	// registry serving a certificate from a private CA. See images.ClientOptions.CABundle.
	CABundle []byte
	// ClientCertificate is presented to a registry that requires one of every client. See
	// images.ClientCertificate.
	ClientCertificate images.ClientCertificate
	// NoRecord skips the record a finished mirror writes about itself. The content is pushed
	// either way; what is lost is `cargoship ls` being able to say the mirror happened, so a
	// registry populated with this set looks empty to a listing.
	NoRecord bool
}

MirrorOptions are the optional parameters to Mirror.

type MirrorRecord added in v0.42.0

type MirrorRecord struct {
	SchemaVersion string `json:"schemaVersion"`
	// Kind says what the record describes, and so what a reader should do with it: a package
	// record names one artifact to pull whole, a mirror record names loose content a node
	// reaches by its own references. It is in the stored JSON as well as the tag, so a reader
	// holding the record does not have to parse the reference it came from.
	Kind string `json:"kind"`
	Name string `json:"name"`
	// Version is the package's own version, not cargoship's. It is also the record's tag, which
	// is what lets two versions of one package be mirrored into the same registry and both be
	// listed afterwards.
	Version string   `json:"version"`
	Arches  []string `json:"arches,omitempty"`
	Engine  string   `json:"engine,omitempty"`
	// Digest is the OCI manifest digest computed over the package's contents at load. It is the
	// identity of what was mirrored, and it survives the package being repacked.
	Digest           string `json:"digest,omitempty"`
	CargoshipVersion string `json:"cargoshipVersion,omitempty"`
	// MirroredAt is when the mirror finished, which makes the record deliberately
	// non-reproducible: mirroring the same package twice writes a different manifest to the
	// same tag, and the later one is the one that is true.
	MirroredAt time.Time `json:"mirroredAt"`
	// Images and Files count what was pushed on the run that wrote this record. A run given
	// --images or --files mirrored one half, so a zero here is "not this run" rather than
	// "the package carries none".
	Images int `json:"images"`
	Files  int `json:"files"`

	// Reference is where this record was read from. It is set by ListMirrored and is not part
	// of the stored JSON, which cannot know the registry it would end up in.
	Reference string `json:"-"`
}

MirrorRecord is what a mirror records about itself: which cargoship package's contents populated the registry, and when.

It exists because nothing else in a mirror says. Images keep their original repository paths and files land under a reference computed from their source, so a registry holding a few hundred repositories answers "what images are here" and not "is k3s 1.36.1 loaded". One record per package and version makes it answerable, at a cost of a few kilobytes.

The record is advisory, not a trust anchor. The distro.yaml it carries is a copy, and the signature that makes a package's own distro.yaml the root of trust lives in the package bundle rather than here -- so a reader learns what was mirrored, never that the content is intact.

func ListMirrored added in v0.42.0

func ListMirrored(ctx context.Context, target string, opts ListMirroredOptions) ([]MirrorRecord, error)

ListMirrored returns the record of every cargoship package mirrored into target, newest first.

With a Name it reads one repository's tags. Without one it has to ask the registry for its catalogue, which is a wider permission than pushing: credentials that can populate a mirror are not always allowed to enumerate it, and the error says so rather than reporting an empty registry.

A listing is what was recorded, not what is still there. Nothing reconciles a record against the images and files it describes, so content deleted from the registry by hand leaves a record behind that still claims it.

type PublishOptions

type PublishOptions struct {
	// OCIConcurrency configures the amount of layers to push in parallel
	OCIConcurrency int
	// Retries specifies the number of retries to use
	Retries int
	// SignBlobOptions holds all signing configuration. Use signing.DefaultSignBlobOptions() as a base.
	SignBlobOptions signing.SignBlobOptions
	CachePath       string
	IsInteractive   bool
	Registry        *registry.Reference
	types.RemoteOptions
	// Tag is an optional tag for the OCI reference separate from the package metadata.version
	Tag string
	// Username and Password authenticate the push. Empty, which is the usual case for the
	// command line, reads the Docker configuration file instead.
	Username string
	Password string
	// DialContext opens the connections the push travels over, which is how it reaches a
	// registry only a cluster node can see. See pkg/tunnel and pkg/kubetunnel.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
	// CABundle is trusted in addition to the system roots, which is how a push reaches a
	// registry serving a certificate from a private CA. See images.ClientOptions.CABundle.
	CABundle []byte
	// ClientCertificate is presented to a registry that requires one of every client. See
	// images.ClientCertificate.
	ClientCertificate images.ClientCertificate
	// Record writes a record of the published package, so that `cargoship ls` can find it and
	// a consumer can resolve the newest version of a package without being told where it is.
	//
	// Off by default, unlike the record a mirror writes. Publishing is the older half of this
	// and a registry somebody already publishes into should not quietly gain a second artifact
	// per package on an upgrade.
	Record bool
}

PublishOptions are the optional parameters to publish

type PullOptions

type PullOptions struct {
	// SHASum uniquely identifies a package based on its contents.
	SHASum string
	// Architecture is the package architecture.
	Architecture string
	// Deprecated: Use VerifyBlobOptions instead. PublicKeyPath validates the create-time signage of a package.
	PublicKeyPath string
	// VerifyBlobOptions configures package signature verification.
	VerifyBlobOptions *signing.VerifyBlobOptions
	// OCIConcurrency is the number of layers pulled in parallel
	OCIConcurrency int
	// CachePath is used to cache layers from OCI package pulls
	CachePath string
	types.RemoteOptions
	// CABundle is trusted in addition to the system roots. See LoadOptions.CABundle.
	CABundle []byte
	// ClientCertificate is presented to a registry that requires one. See
	// LoadOptions.ClientCertificate.
	ClientCertificate images.ClientCertificate
	// VerificationStrategy for explicit definition
	layout.VerificationStrategy
}

PullOptions declares optional configuration for a Pull operation.

Jump to

Keyboard shortcuts

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