bundle

package
v1.3.1 Latest Latest
Warning

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

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

Documentation

Overview

Package bundle carries packages into clusters that cannot reach the places they were published: a bundle holds the signed repository files, the charts, package trees and images of the chosen packages, and is checked against the repository's signatures again before anything from it is copied into a mirror registry.

Index

Constants

View Source
const (
	ManifestFile = "bundle.yaml"
	// SBOMFile is a CycloneDX description of the bundle\'s packages.
	SBOMFile = "sbom.cdx.json"
)

Layout of a bundle directory.

Variables

This section is empty.

Functions

func NodeMirrors

func NodeMirrors(mirror string, plainHTTP bool, registries []string) (map[string]string, string, error)

NodeMirrors returns registry mirror settings that send image pulls for registries to the mirror: a containerd hosts.toml per registry, keyed by registry, and a Talos machine config patch.

func Pack

func Pack(dir string, w io.Writer) error

Pack writes the bundle directory dir as a tar stream. Images are compressed already, so the stream is not.

func Unpack

func Unpack(r io.Reader, dir string) error

Unpack extracts a bundle tar stream into dir, refusing entries that leave it and anything but files and directories.

Types

type Chart

type Chart struct {
	Repository string `json:"repository"`
	Name       string `json:"name"`
	Version    string `json:"version"`
	Digest     string `json:"digest"`
}

Chart is a chart archive, stored as charts/<hex>.tgz.

type CreateOptions

type CreateOptions struct {
	// Charts downloads chart archives.
	Charts *source.Fetcher
	// Registry opens image and tree repositories.
	Registry images.Resolver
	// Warn receives notes about images no repository pins.
	Warn io.Writer
	Now  time.Time
}

CreateOptions say how to fetch what goes into a bundle.

type Image

type Image struct {
	// Ref is registry/repository:tag@sha256:...
	Ref string `json:"ref"`
	// Pinned is true when the repository pins the image in a package's
	// images; otherwise the bundle found it in the charts and pinned it at
	// the time it was made, and only the bundle vouches for it.
	Pinned   bool     `json:"pinned"`
	Packages []string `json:"packages"`
}

Image is a container image, stored in the OCI layout under Ref.

type ImportOptions

type ImportOptions struct {
	// Mirror is the oci:// registry path to copy into; the operator's
	// --mirror (chart value mirror) points at the same path.
	Mirror string
	// Push carries the registry transport and credentials.
	Push source.PushOptions
	// SiteDir receives each repository's files, <SiteDir>/<repository>/,
	// to serve over HTTP inside the air gap.
	SiteDir string
}

ImportOptions say where a verified bundle goes.

type ImportResult

type ImportResult struct {
	Charts, Trees, Images int
	// Registries are the image registries the mirror now stands in for.
	Registries []string
}

ImportResult says what was copied.

func Import

func Import(ctx context.Context, v *Verified, o ImportOptions) (*ImportResult, error)

Import copies a verified bundle into the mirror registry and writes the repositories' files for serving. Copies keep their digests, so the signed index serves unchanged.

type Manifest

type Manifest struct {
	APIVersion   string       `json:"apiVersion"`
	Kind         string       `json:"kind"`
	Created      metav1.Time  `json:"created"`
	Repositories []Repository `json:"repositories"`
	Packages     []Package    `json:"packages"`
	Charts       []Chart      `json:"charts,omitempty"`
	Trees        []Tree       `json:"trees,omitempty"`
	Images       []Image      `json:"images,omitempty"`
}

Manifest describes a bundle. It is a table of contents, not a source of trust: everything in it is checked against the signed index on import.

func Create

func Create(ctx context.Context, dir string, rec *Recorded, sel []Selection, o CreateOptions) (*Manifest, error)

Create writes a bundle of the selected package versions into dir.

func Read

func Read(dir string) (*Manifest, error)

Read loads a bundle's manifest from dir.

type Package

type Package struct {
	Name       string `json:"name"`
	Version    string `json:"version"`
	Build      int32  `json:"build,omitempty"`
	Repository string `json:"repository"`
	// Digest is the version's spec digest in the index.
	Digest string `json:"digest"`
}

Package is one version of a package in the bundle.

type Recorded

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

Recorded holds the repository files fetched while loading sources.

func Load

func Load(ctx context.Context, sources []Source, fetchers repo.Fetchers, now time.Time, warn io.Writer) (*repo.Store, *Recorded, error)

Load loads the sources with the same checks a cluster applies, signatures and roots included, and records every file it fetched. Versions left out of an index are reported to warn.

type Repository

type Repository struct {
	Name     string `json:"name"`
	URL      string `json:"url"`
	Priority int32  `json:"priority,omitempty"`
	// Files are paths next to the index, e.g. index.yaml, index.yaml.sig,
	// root.yaml, root/1.yaml.
	Files []string `json:"files"`
}

Repository is a repository's published files, as fetched.

type Selection

type Selection struct {
	Repository string
	Name       string
	Version    repo.Version
}

Selection is a package version to put in a bundle.

type Source

type Source struct {
	Name string
	Spec v1.RepositorySpec
}

Source is a repository to take packages from, as a cluster would.

type Tree

type Tree struct {
	// Ref is the oci:// reference the package points at, with its digest.
	Ref string `json:"ref"`
}

Tree is a package tree, stored in the OCI layout.

type Verified

type Verified struct {
	Dir      string
	Manifest *Manifest
	// Specs are the signed specs of the bundle's packages, by name.
	Specs map[string]v1.PackageSourceSpec
}

Verified is a bundle whose contents match its signed repositories.

func Verify

func Verify(ctx context.Context, dir string, trust v1.RepositorySpec, now time.Time, allowUnpinned bool) (*Verified, error)

Verify checks a bundle against its repositories, trusted as trust says (public keys or a root of trust, never what the bundle itself carries), the way a cluster would: signatures, roots and expiry. Every chart, tree and image must be what the signed packages pin. Images found in charts rather than pinned by a repository are refused unless allowUnpinned.

Jump to

Keyboard shortcuts

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