source

package
v1.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 12, 2026 License: Apache-2.0 Imports: 34 Imported by: 0

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

View Source
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.

View Source
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.

View Source
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.

View Source
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

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound is returned by Download for a 404.

View Source
var ErrTagChanged = errors.New("tag already published with different content")

ErrTagChanged is returned when an immutable tag already holds different content.

Functions

func CheckRegistryHost added in v1.3.0

func CheckRegistryHost(host string) error

CheckRegistryHost refuses what is not a registry host, host or host:port, such as a URL or a path.

func Compose

func Compose(tree, base string, spec ChartSpec, dst string) (string, string, error)

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 CopyTree

func CopyTree(src, dst string) error

CopyTree copies the regular files under src to dst.

func DirDigest

func DirDigest(dir string) (string, error)

DirDigest hashes file paths and contents in a stable order.

func DockerConfigCredentials

func DockerConfigCredentials(load func(ctx context.Context) ([][]byte, error)) auth.CredentialFunc

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 Download

func Download(ctx context.Context, u string, limit int64) ([]byte, error)

Download GETs u and fails on a non-200 status or beyond limit bytes.

func FetchFile

func FetchFile(ctx context.Context, u, sum string) ([]byte, error)

FetchFile downloads url and checks it against sha256 (hex, with or without the sha256: prefix). Build sources are always pinned.

func MergeValues

func MergeValues(base, over map[string]any) map[string]any

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

func MirrorPath(location string) string

MirrorPath is where a published location lives under a mirror.

func MirrorRef

func MirrorRef(mirror, ref string) (string, error)

MirrorRef returns where an oci:// reference (tag, digest or both) lives under mirror.

func Pack

func Pack(dir string) ([]byte, string, error)

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

func SetChartMeta(dir, name, version string) error

SetChartMeta sets the name and version in a chart's Chart.yaml, as PushChart publishes it.

func Untar

func Untar(r io.Reader, dst string) error

Untar unpacks a gzipped tarball into dst with the same limits as package trees: no links, no escapes, bounded size.

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

func MirrorChart(mirror string, c Chart) Chart

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
	// PlainHTTPRegistries are registry hosts reached without TLS whatever
	// PlainHTTP says, so a local registry does not take every other
	// registry off TLS with it. The set may change while it is in use.
	PlainHTTPRegistries *Registries
	// 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

func (f *Fetcher) Fetch(ctx context.Context, ref string) (dir, digest string, err error)

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

func (f *Fetcher) FetchChart(ctx context.Context, c Chart) (dir, digest string, err error)

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.

type Registries added in v1.3.0

type Registries struct {
	// contains filtered or unexported fields
}

Registries is a set of registry hosts, host or host:port, that may change while it is in use: the operator keeps the plain HTTP registries of every Repository in one. The zero value is empty and ready to use; a nil *Registries is empty too.

func NewRegistries added in v1.3.0

func NewRegistries(hosts ...string) *Registries

NewRegistries returns a set holding hosts under the owner "".

func (*Registries) Has added in v1.3.0

func (r *Registries) Has(host string) bool

Has reports whether any owner lists host.

func (*Registries) HasRef added in v1.3.0

func (r *Registries) HasRef(ref string) bool

HasRef reports whether the registry of an oci:// reference or a registry path is in the set.

func (*Registries) Set added in v1.3.0

func (r *Registries) Set(owner string, hosts []string)

Set replaces the hosts an owner contributes; no hosts removes the owner.

Jump to

Keyboard shortcuts

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