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
- func HasImageRules(r *Recipe) bool
- func Init(ctx context.Context, dir string, in InitInput, fetcher *source.Fetcher) error
- func Publish(ctx context.Context, res *Result, registry string, opts source.PushOptions) (*v1.PackageSource, bool, error)
- func PublishedVersion(r *Recipe) string
- func RenderChart(dir string, values map[string]any) ([]string, error)
- func RenderedImages(res *Result) ([]string, error)
- func VerifyCharts(ctx context.Context, r *Recipe, dir string, f *source.Fetcher) error
- func VerifyImages(ctx context.Context, r *Recipe, dir string, verify ImageVerifier) (unchecked []string, err error)
- type Chart
- type ChartSignature
- type ImageSignature
- type ImageVerifier
- type InitInput
- type Options
- type Patch
- type PluginCall
- type PluginInput
- type Plugins
- type Recipe
- type RecipeSpec
- type Report
- type Result
- type Selector
- type Source
- type SourceFunc
- type SourcePlugin
- type StepFunc
- type StepPlugin
- type Verify
Constants ¶
const RecipeFile = "recipe.yaml"
RecipeFile is the file a recipe directory must contain.
const RecipeKind = "Recipe"
RecipeKind is the kind of a recipe document.
Variables ¶
This section is empty.
Functions ¶
func HasImageRules ¶
HasImageRules reports whether a recipe asks to verify image signatures.
func Init ¶
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 ¶
PublishedVersion is the chart version a recipe's charts are published under: the package version and the build, 1.21.2-3.
func RenderChart ¶
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 ¶
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 ¶
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 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 ¶
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 ¶
Report is what Validate found. Errors make a recipe unfit to publish; warnings are worth fixing.
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.
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.
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.