Documentation
¶
Overview ¶
Package source fetches package trees and composes charts from them.
A package tree is published as a single-layer OCI artifact in the shape Flux uses (`flux push artifact`): one gzipped tarball of the packages directory. kubepkg reads these artifacts without needing Flux to be installed.
Index ¶
- Constants
- Variables
- func Compose(tree, base string, spec ChartSpec, dst string) (string, string, error)
- func CopyTree(src, dst string) error
- func DirDigest(dir string) (string, error)
- func DockerConfigCredentials(load func(ctx context.Context) ([][]byte, error)) auth.CredentialFunc
- func Download(ctx context.Context, u string, limit int64) ([]byte, error)
- func FetchFile(ctx context.Context, u, sum string) ([]byte, error)
- func MergeValues(base, over map[string]any) map[string]any
- func MirrorPath(location string) string
- func MirrorRef(mirror, ref string) (string, error)
- func Pack(dir string) ([]byte, string, error)
- func SetChartMeta(dir, name, version string) error
- func Untar(r io.Reader, dst string) error
- type Chart
- type ChartSpec
- type Fetcher
- func (f *Fetcher) ChartArchive(ctx context.Context, c Chart) (archive []byte, digest string, err error)
- func (f *Fetcher) ChartProvenance(ctx context.Context, c Chart) (prov []byte, filename string, err error)
- func (f *Fetcher) Fetch(ctx context.Context, ref string) (dir, digest string, err error)
- func (f *Fetcher) FetchChart(ctx context.Context, c Chart) (dir, digest string, err error)
- type PushOptions
- type PushResult
- func Push(ctx context.Context, dir, ref string, opts PushOptions) (PushResult, error)
- func PushChart(ctx context.Context, dir, repository, name, version string, opts PushOptions) (PushResult, error)
- func PushChartArchive(ctx context.Context, archive []byte, repository, name, version string, ...) (PushResult, error)
Constants ¶
const ( ChartMediaType = "application/vnd.cncf.helm.chart.content.v1.tar+gzip" ChartConfigMediaType = "application/vnd.cncf.helm.config.v1+json" )
Media types of a Helm chart in a registry.
const ( FluxConfigMediaType = "application/vnd.cncf.flux.config.v1+json" FluxContentMediaType = "application/vnd.cncf.flux.content.v1.tar+gzip" )
Media types of a Flux artifact, so Flux and kubepkg both read what kubepkg publishes.
const AnnotationContentDigest = "dev.kubepkg.content.digest"
AnnotationContentDigest on a published tree is the sha256 of its uncompressed tarball. The compressed layer depends on the compressor, which changes between Go releases; the content does not.
const ProvenanceMediaType = "application/vnd.cncf.helm.chart.provenance.v1.prov"
ProvenanceMediaType is the layer of a Helm chart's provenance file in a registry.
Variables ¶
var ErrNotFound = errors.New("not found")
ErrNotFound is returned by Download for a 404.
var ErrTagChanged = errors.New("tag already published with different content")
ErrTagChanged is returned when an immutable tag already holds different content.
Functions ¶
func Compose ¶
Compose builds a chart directory under dst from a tree and returns the chart directory and a digest of its content. The digest changes exactly when the chart Helm would load changes, so the operator can tell a real upgrade from a no-op.
func DockerConfigCredentials ¶
DockerConfigCredentials returns the credentials for a registry from Docker config files, as kubernetes.io/dockerconfigjson Secrets hold them. load is called on every lookup, so rotated credentials take effect without a restart.
func FetchFile ¶
FetchFile downloads url and checks it against sha256 (hex, with or without the sha256: prefix). Build sources are always pinned.
func MergeValues ¶
MergeValues deep-merges over into base: maps merge key by key, anything else in over replaces what base had. Neither input is modified.
func MirrorPath ¶
MirrorPath is where a published location lives under a mirror.
func MirrorRef ¶
MirrorRef returns where an oci:// reference (tag, digest or both) lives under mirror.
func Pack ¶
Pack makes a gzipped tarball of dir with sorted entries, zero timestamps and fixed ownership, and returns it with the digest of the uncompressed tarball. The content digest is the same for the same tree everywhere; the compressed bytes are the same only with the same compressor.
func SetChartMeta ¶
SetChartMeta sets the name and version in a chart's Chart.yaml, as PushChart publishes it.
Types ¶
type Chart ¶
type Chart struct {
// Repository is an http(s):// Helm repository or an oci:// path.
Repository string
Name string
// Version is exact.
Version string
// Digest, sha256:<hex> of the archive, is verified when set.
Digest string
}
Chart identifies one version of a published Helm chart.
func MirrorChart ¶
MirrorChart returns where a published chart lives under mirror. The digest stays: the copy is the same archive.
type ChartSpec ¶
type ChartSpec struct {
// Path of the chart inside the tree, relative to the base path.
Path string
// Libraries maps a library name to its path inside the tree; each is
// placed under the chart's charts/<name>.
Libraries map[string]string
// ValuesFiles are file names inside the chart. The first replaces
// values.yaml, the rest are merged over it in order.
ValuesFiles []string
}
ChartSpec says how to build one component's chart from a tree.
type Fetcher ¶
type Fetcher struct {
CacheDir string
// PlainHTTP talks to registries without TLS (local test registries):
// to every registry, or only to PlainHTTPHosts when that is set.
PlainHTTP bool
PlainHTTPHosts []string
// CredentialsFile is a Docker config with registry credentials; empty
// means anonymous access.
CredentialsFile string
// Credentials, when set, is asked first for a registry's credentials,
// for example from Secrets in the cluster; an empty answer falls back
// to CredentialsFile.
Credentials auth.CredentialFunc
// Mirror, an oci:// registry path, is where every chart and package
// tree is fetched from instead of where it was published; see
// MirrorPath. Digests are verified as usual.
Mirror string
// contains filtered or unexported fields
}
Fetcher downloads package trees and charts and caches them by digest, under trees/ and charts/ of CacheDir.
func (*Fetcher) ChartArchive ¶
func (f *Fetcher) ChartArchive(ctx context.Context, c Chart) (archive []byte, digest string, err error)
ChartArchive downloads a chart archive, from the mirror when the fetcher has one, and checks it against the pinned digest.
func (*Fetcher) ChartProvenance ¶
func (f *Fetcher) ChartProvenance(ctx context.Context, c Chart) (prov []byte, filename string, err error)
ChartProvenance downloads the provenance file the upstream published with a chart, and the archive file name it signs.
func (*Fetcher) Fetch ¶
Fetch resolves an oci:// reference and returns the directory the tree is unpacked into and the manifest digest. Unpacked trees are immutable and keyed by digest, so a tag that moves produces a new directory.
func (*Fetcher) FetchChart ¶
FetchChart downloads a chart and returns the directory it is unpacked into and the archive digest. Charts are cached by digest, so a pinned chart that is already cached needs no network at all.
type PushOptions ¶
type PushOptions struct {
Source string
Revision string
PlainHTTP bool
// CredentialsFile is a Docker config with registry credentials.
CredentialsFile string
// Immutable refuses to move a tag: when the tag already holds the same
// content, the published artifact is reused; different content is an
// error.
Immutable bool
}
PushOptions describe where a tree came from; they end up in annotations.
func (PushOptions) Open ¶
func (o PushOptions) Open(ref string) (*remote.Repository, error)
Open opens the OCI repository of an oci:// reference with the push options' transport and credentials.
type PushResult ¶
type PushResult struct {
// Digest is the manifest digest the tag points at.
Digest string
// LayerDigest is the digest of the single layer: for a chart, the
// digest of the chart archive.
LayerDigest string
// Reused is true when the tag already held the same content and
// nothing was pushed.
Reused bool
}
PushResult describes a push.
func Push ¶
func Push(ctx context.Context, dir, ref string, opts PushOptions) (PushResult, error)
Push packs dir into a reproducible gzipped tarball and pushes it as a single-layer artifact to ref (oci://host/repo:tag).
func PushChart ¶
func PushChart(ctx context.Context, dir, repository, name, version string, opts PushOptions) (PushResult, error)
PushChart publishes the chart in dir as a Helm chart in an OCI registry, at <repository>/<name>:<version>, the way helm push does, with name and version set in its Chart.yaml. Helm, Flux, Argo CD and werf all install it as it is. LayerDigest of the result is the digest of the chart archive.
func PushChartArchive ¶
func PushChartArchive(ctx context.Context, archive []byte, repository, name, version string, opts PushOptions) (PushResult, error)
PushChartArchive publishes a chart archive exactly as it is at <repository>/<name>:<version>, so the copy keeps the archive digest a package pins. It is how kubepkg bundle import fills a mirror.