Documentation
¶
Overview ¶
Package distro defines the API types for a distro package.
Index ¶
Constants ¶
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.
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.
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
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
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.
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 never empty.
Shasum string `json:"shasum"`
}
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.
Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
// 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.
Version string `json:"version,omitempty"`
// 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:"athors,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.
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.
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.