Documentation
¶
Overview ¶
Package distro is used for creating/deploying distro package
Index ¶
- Constants
- func Build(ctx context.Context, distroPath string, opts CreateOptions) (*layout.DistroLayout, error)
- func Create(ctx context.Context, distroPath string, output string, opts CreateOptions) (_ string, err error)
- func Import(ctx context.Context, source string, opts ImportOptions) (string, error)
- func ImportLayout(ctx context.Context, source string, opts ImportOptions) (*layout.DistroLayout, error)
- func Load(ctx context.Context, source string, opts LoadOptions) (*layout.DistroLayout, error)
- func Mirror(ctx context.Context, l *layout.DistroLayout, target string, opts MirrorOptions) error
- func Publish(ctx context.Context, disLayout *layout.DistroLayout, dst registry.Reference, ...) (registry.Reference, error)
- func Pull(ctx context.Context, source, destination string, opts PullOptions) (string, error)
- func RecordRef(target, kind, name, version string) (string, error)
- type CreateOptions
- type ImportOptions
- type ListMirroredOptions
- type LoadOptions
- type MirrorOptions
- type MirrorRecord
- type PublishOptions
- type PullOptions
Constants ¶
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.
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.
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
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 ¶
func Publish(ctx context.Context, disLayout *layout.DistroLayout, dst registry.Reference, opts PublishOptions) (registry.Reference, error)
Publish used to publish a distro package to an oci registry
func Pull ¶
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
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
// 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
// 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
// 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
// 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
// VerificationStrategy for explicit definition
layout.VerificationStrategy
}
PullOptions declares optional configuration for a Pull operation.