build

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: 33 Imported by: 0

Documentation

Overview

Package build turns recipes into installable packages.

A recipe is to kubepkg what a debian/ directory is to Debian: it names upstream sources pinned by digest, says how to make charts of them, adds our own values and files on top, and carries the package metadata. The result is a package tree of ready charts, published as an OCI artifact, and the PackageSource that installs it. Installing never touches the upstream again.

Index

Constants

View Source
const RecipeFile = "recipe.yaml"

RecipeFile is the file a recipe directory must contain.

View Source
const RecipeKind = "Recipe"

RecipeKind is the kind of a recipe document.

Variables

This section is empty.

Functions

func HasImageRules

func HasImageRules(r *Recipe) bool

HasImageRules reports whether a recipe asks to verify image signatures.

func Init

func Init(ctx context.Context, dir string, in InitInput, fetcher *source.Fetcher) error

Init writes dir/recipe.yaml for an upstream chart or release manifests, with every source pinned: it downloads them to compute digests, takes the description from the chart, drops Namespaces from manifests, and lists the CRDs they ship. Review and adjust the result, then run Validate.

func Publish

func Publish(ctx context.Context, res *Result, registry string, opts source.PushOptions) (*v1.PackageSource, bool, error)

Publish pushes every built chart to registry (oci://host/path) as a Helm chart, oci://host/path/<package>/<chart>:<version>-<build>, and points the package's components at them by archive digest. Helm, Flux, Argo CD and werf install such charts as they are, so a built package does not need kubepkg to be installed. Tags are immutable: when a tag already holds the same content, built perhaps with another compressor, the published chart is reused; reused is true when all of them were.

func PublishedVersion

func PublishedVersion(r *Recipe) string

PublishedVersion is the chart version a recipe's charts are published under: the package version and the build, 1.21.2-3.

func RenderChart

func RenderChart(dir string, values map[string]any) ([]string, error)

RenderChart renders a chart with values over its defaults, as helm install would, and returns the documents it installs: templates of the chart and its enabled subcharts, and their crds/ directories.

func RenderedImages

func RenderedImages(res *Result) ([]string, error)

RenderedImages lists the images the built charts run with their default values. Images an operator in the package deploys on its own do not appear in any chart; package.images lists them by hand.

func VerifyCharts

func VerifyCharts(ctx context.Context, r *Recipe, dir string, f *source.Fetcher) error

VerifyCharts checks the chart sources the recipe names against their upstream's provenance files: the signature, by a key in the keyring, and the archive's hash in the signed message.

func VerifyImages

func VerifyImages(ctx context.Context, r *Recipe, dir string, verify ImageVerifier) (unchecked []string, err error)

VerifyImages checks the signatures of the recipe's pinned images. It returns the images no rule covers; an image a rule covers but that is not signed that way is an error.

Types

type Chart

type Chart struct {
	// From names the sources. One source that is a chart is used as the
	// chart; anything else must be Kubernetes manifests, which are wrapped
	// into a chart in the order given.
	From []string `json:"from"`
	// Values are merged over the chart's values.yaml: the package's
	// defaults, which users can still override.
	Values map[string]any `json:"values,omitempty"`
	// Overlay is a directory next to the recipe whose files replace or add
	// files in the chart, for changes values cannot express.
	Overlay string `json:"overlay,omitempty"`
	// Exclude drops objects from wrapped manifests, e.g. the Namespace an
	// upstream bundle creates, which kubepkg creates itself. For a chart
	// source it drops objects from the crds/ directories of the chart and
	// its subcharts; templates are rendered at install time and cannot be
	// edited here.
	Exclude []Selector `json:"exclude,omitempty"`
	// Patches change objects of wrapped manifests with JSON merge patches
	// (RFC 7386; null removes a field): the recipe's equivalent of a
	// Debian patch to the upstream. For a chart source they apply to the
	// crds/ directories, like Exclude.
	Patches []Patch `json:"patches,omitempty"`
	// CRDsDir puts the CRDs of wrapped manifests in the chart's crds/
	// directory instead of its templates. Helm keeps templates in its
	// release record, which holds about 1 MiB, so large CRDs only fit in
	// crds/; Helm installs those but does not upgrade them, which
	// install.upgradeCRDs: CreateReplace arranges.
	CRDsDir bool `json:"crdsDir,omitempty"`
	// Steps run step plugins on the finished chart, in order: what a
	// distribution needs beyond values and overlays, such as moving images
	// to its own registry.
	Steps []PluginCall `json:"steps,omitempty"`
}

Chart says how to make one chart of the sources.

type ChartSignature

type ChartSignature struct {
	// Sources names chart sources of the recipe.
	Sources []string `json:"sources"`
	// Keyring is a GPG public keyring file next to the recipe.
	Keyring string `json:"keyring"`
}

ChartSignature checks chart sources against the .prov files their upstream publishes, as helm verify does.

type ImageSignature

type ImageSignature struct {
	// Repositories the rule covers, registry/path, with * standing for
	// one path element: quay.io/jetstack/*.
	Repositories []string `json:"repositories"`
	// Key is a public key file next to the recipe.
	Key string `json:"key,omitempty"`
	// Identity and Issuer check a keyless signature: the certificate's
	// subject and the OIDC issuer that vouched for it.
	Identity string `json:"identity,omitempty"`
	Issuer   string `json:"issuer,omitempty"`
	// SignatureDigest is the digest the upstream signs with, when it is
	// not sha256: sha384 or sha512.
	SignatureDigest string `json:"signatureDigest,omitempty"`
	// IgnoreTransparencyLog accepts signatures the upstream does not
	// record in a transparency log, for upstreams that sign that way,
	// such as cert-manager. The key alone then vouches for them.
	IgnoreTransparencyLog bool `json:"ignoreTransparencyLog,omitempty"`
}

ImageSignature is how the images of some repositories are signed: with a key, or keyless by an identity that an OIDC issuer vouched for.

type ImageVerifier

type ImageVerifier func(ctx context.Context, image string, rule ImageSignature, recipeDir string) error

ImageVerifier checks that image carries the signature rule describes.

func CosignVerifier

func CosignVerifier(binary string) ImageVerifier

CosignVerifier checks signatures with the cosign executable.

type InitInput

type InitInput struct {
	Name      string
	Version   string // default: the chart's appVersion or version
	Namespace string // default: Name
	// Chart is an upstream chart: repository, name and version.
	Chart *source.Chart
	// Manifests are URLs of upstream release manifests.
	Manifests   []string
	Description string // default: the chart's description
	Home        string // default: the chart's home
	// Images pins the images the upstream runs; nil leaves package.images
	// for kubepkg images to fill.
	Images *images.Resolver
}

InitInput describes the recipe Init writes. Exactly one of Chart and Manifests is set.

type Options

type Options struct {
	// Fetcher downloads charts; its cache is reused across builds.
	Fetcher *source.Fetcher
	// WorkDir receives the sources and the package tree.
	WorkDir string
	// Plugins extend the sources and steps a recipe can use.
	Plugins Plugins
	// VerifyImages checks the image signatures a recipe asks for; nil
	// refuses recipes that ask.
	VerifyImages ImageVerifier
}

Options control a build.

type Patch

type Patch struct {
	Selector `json:",inline"`
	Merge    map[string]any `json:"merge"`
}

Patch is a JSON merge patch for the objects Selector matches.

type PluginCall

type PluginCall struct {
	Plugin string         `json:"plugin"`
	With   map[string]any `json:"with,omitempty"`
}

PluginCall runs a named step plugin with parameters.

type PluginInput

type PluginInput struct {
	// With holds the recipe's parameters for this call.
	With map[string]any
	// RecipeDir is the recipe directory, read-only.
	RecipeDir string
	// Out is an empty directory a source plugin fills.
	Out string
	// Chart is the chart directory a step plugin changes.
	Chart string
	// Package and Version identify the package being built.
	Package, Version string
}

PluginInput is what a plugin gets.

type Plugins

type Plugins struct {
	Sources map[string]SourcePlugin
	Steps   map[string]StepPlugin
}

Plugins are the plugins a build can call by name. Names not registered here are looked up as executables on PATH: kubepkg-source-<name> and kubepkg-step-<name>.

type Recipe

type Recipe struct {
	APIVersion string            `json:"apiVersion"`
	Kind       string            `json:"kind"`
	Metadata   metav1.ObjectMeta `json:"metadata"`
	Spec       RecipeSpec        `json:"spec"`
}

Recipe describes how to build one version of a package.

func LoadRecipe

func LoadRecipe(dir string) (*Recipe, error)

LoadRecipe reads dir/recipe.yaml and checks it.

type RecipeSpec

type RecipeSpec struct {
	// Version is the upstream version being packaged.
	Version string `json:"version"`
	// Build numbers our packagings of that version.
	Build int32 `json:"build,omitempty"`
	// Sources are the upstream inputs, by name.
	Sources map[string]Source `json:"sources"`
	// Charts are built into the package tree, one directory each, by name.
	Charts map[string]Chart `json:"charts"`
	// Package is the PackageSource spec. Its components refer to built
	// charts by path; version, build and sourceRef are filled in by the
	// build.
	Package v1.PackageSourceSpec `json:"package"`
	// Verify says how the maintainers check what the upstream publishes,
	// the way a Debian package checks the upstream's signing key: it runs
	// when the recipe is validated and built, and the repository's own
	// signature vouches for the result from then on.
	Verify *Verify `json:"verify,omitempty"`
}

RecipeSpec is the body of a recipe.

type Report

type Report struct {
	Recipe   string
	Errors   []string
	Warnings []string
}

Report is what Validate found. Errors make a recipe unfit to publish; warnings are worth fixing.

func Validate

func Validate(ctx context.Context, dir string, opts Options) Report

Validate builds the recipe in dir without publishing it, so every source is fetched and checked, renders its charts with their default values, and checks the package metadata against what the charts ship.

func (Report) OK

func (r Report) OK() bool

OK is true when there are no errors.

type Result

type Result struct {
	Recipe *Recipe
	// TreeDir holds one chart directory per built chart.
	TreeDir string
	// Source installs the tree once SourceRef is set by Publish.
	Source v1.PackageSource
}

Result is a built package before publishing.

func Build

func Build(ctx context.Context, dir string, opts Options) (*Result, error)

Build reads the recipe in dir and builds its package tree.

type Selector

type Selector struct {
	Kind string `json:"kind,omitempty"`
	Name string `json:"name,omitempty"`
}

Selector matches manifest objects; empty fields match anything.

type Source

type Source struct {
	// URL is a file or a .tar.gz/.tgz archive, checked against SHA256.
	URL    string `json:"url,omitempty"`
	SHA256 string `json:"sha256,omitempty"`
	// Path selects a file or directory inside an archive.
	Path string `json:"path,omitempty"`
	// Chart is a published Helm chart; it is pinned by digest.
	Chart *v1.ChartRef `json:"chart,omitempty"`
	// Dir is a directory next to the recipe, for charts we maintain.
	Dir string `json:"dir,omitempty"`
	// Plugin fetches the source with a source plugin, e.g. from git or an
	// internal artifact store; With is passed to it. A plugin must produce
	// the same files every time for the same With.
	Plugin string         `json:"plugin,omitempty"`
	With   map[string]any `json:"with,omitempty"`
}

Source is one upstream input. Exactly one of URL, Chart, Dir and Plugin is set.

type SourceFunc

type SourceFunc func(ctx context.Context, in PluginInput) error

SourceFunc and StepFunc adapt functions to the plugin interfaces.

func (SourceFunc) Fetch

func (f SourceFunc) Fetch(ctx context.Context, in PluginInput) error

Fetch implements SourcePlugin.

type SourcePlugin

type SourcePlugin interface {
	Fetch(ctx context.Context, in PluginInput) error
}

SourcePlugin fills Out with the files of a source.

type StepFunc

type StepFunc func(ctx context.Context, in PluginInput) error

SourceFunc and StepFunc adapt functions to the plugin interfaces.

func (StepFunc) Run

func (f StepFunc) Run(ctx context.Context, in PluginInput) error

Run implements StepPlugin.

type StepPlugin

type StepPlugin interface {
	Run(ctx context.Context, in PluginInput) error
}

StepPlugin changes the chart in Chart in place.

type Verify

type Verify struct {
	// Images are the signatures the pinned images must carry, checked
	// with cosign by digest.
	Images []ImageSignature `json:"images,omitempty"`
	// Charts are the published chart sources the upstream signs with
	// Helm provenance files, and the keyring to check them with.
	Charts []ChartSignature `json:"charts,omitempty"`
}

Verify lists the checks a recipe makes on its upstream.

Jump to

Keyboard shortcuts

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