zarf

package
v0.36.0 Latest Latest
Warning

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

Go to latest
Published: Aug 25, 2026 License: AGPL-3.0 Imports: 42 Imported by: 0

Documentation

Overview

Package zarf deploys, removes, verifies, and stages Zarf packages used by UDS bundles.

It loads package metadata from bundle artifacts or source declarations, resolves local and remote package sources, applies component filters from the bundle configuration, rebuilds package layouts from stored OCI descriptors, and calls the upstream Zarf APIs that perform package-level operations. When upstream Zarf exposes a higher-level package-layout method, prefer that over reading the layout through ORAS directly.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrNotImplemented               = errors.New("not yet implemented")
	ErrPackageNotDeployed           = errors.New("package not deployed")
	ErrInvalidSignatureVerification = errors.New("invalid package signature verification")
	ErrPackageRequired              = errors.New("package is required")
	ErrCreateVerificationMaterial   = errors.New("creating verification material directory")
	ErrWriteVerificationMaterial    = errors.New("writing verification material")
	ErrBundleValidation             = errors.New("bundle validation failed")
	ErrBuildDependencyGraph         = errors.New("failed to build dependency graph")
	ErrComputeDeploymentLevels      = errors.New("failed to compute deployment levels")
	ErrLoadPackage                  = errors.New("loading package")
	ErrIngestPackage                = errors.New("ingesting package")
	ErrDeployPackage                = errors.New("deploying package")
	ErrRemovePackage                = errors.New("removing package")
	ErrPackageHook                  = errors.New("package hook failed")
	ErrBundleHook                   = errors.New("bundle hook failed")
	ErrConnectCluster               = errors.New("connecting to cluster")
	ErrReadDeployedPackages         = errors.New("reading deployed packages")
	ErrResolvePackageManifest       = errors.New("resolving package manifest")
	ErrReadPackageManifest          = errors.New("reading package manifest")
	ErrWritePackageManifest         = errors.New("writing package manifest")
	ErrMarshalPackageManifest       = errors.New("marshaling package manifest")
	ErrCopyPackageContent           = errors.New("copying package content")
	ErrCreatePackageWorkspace       = errors.New("creating package workspace")
	ErrFetchPackageMetadata         = errors.New("fetching package metadata")
	ErrApplyComponentFilter         = errors.New("applying component filter")
	ErrAssemblePackageLayers        = errors.New("assembling package layers")
	ErrCreateOCIRemote              = errors.New("creating OCI remote")
	ErrResolveRootManifest          = errors.New("resolving root manifest")
	ErrFetchRootManifest            = errors.New("fetching root manifest")
	ErrResolvePackageLayers         = errors.New("resolving package layers")
	ErrPullPackage                  = errors.New("pulling package")
	ErrReadCanonicalManifest        = errors.New("reading canonical package manifest")
	ErrStagePackage                 = errors.New("staging package")
	ErrResolveDestinationDirectory  = errors.New("resolving destination directory")
	ErrResolveLayerTitle            = errors.New("resolving layer title")
	ErrCheckLayerTitle              = errors.New("checking layer title")
	ErrLocalSourcePathRequired      = errors.New("local package source path is empty")
	ErrInvalidLocalPackageSource    = errors.New("unsupported local package source")
	ErrUnsupportedPackageSymlink    = errors.New("unsupported symlink in local package")
	ErrCopyLocalPackage             = errors.New("copying local package")
	ErrExtractLocalPackage          = errors.New("extracting local package archive")
	ErrStatLocalPackage             = errors.New("stating local package source")
	ErrInvalidManifestDigest        = errors.New("invalid package manifest digest")
	ErrPackageNotFoundInArtifact    = errors.New("package not found in bundle artifact")
	ErrMissingLayerTitle            = errors.New("package layer is missing its title annotation")
	ErrCreateLayerDirectory         = errors.New("creating package layer directory")
	ErrStagePackageLayer            = errors.New("staging package layer")
	ErrOrchestratedBundleDeploy     = errors.New("orchestrated deployer does not support bundle deployment")
	ErrCreateTemporaryDirectory     = errors.New("creating temporary directory")
	ErrTemplateValues               = errors.New("templating package values")
	ErrParseValues                  = errors.New("parsing package values")
	ErrFlattenVariables             = errors.New("flattening package variables")
	ErrReadValuesFile               = errors.New("reading values file")
	ErrParseValuesTemplate          = errors.New("parsing values template")
	ErrRenderValues                 = errors.New("rendering values file")
	ErrCreateTemporaryValuesFile    = errors.New("creating temporary values file")
	ErrWriteTemporaryValuesFile     = errors.New("writing temporary values file")
	ErrCloseTemporaryValuesFile     = errors.New("closing temporary values file")
	ErrBundleDirRequired            = errors.New("bundle directory is required")
	ErrStatPackageManifest          = errors.New("stating package manifest")
	ErrOpenOCILayout                = errors.New("opening OCI layout")
)

Functions

func BuildComponentFilter

func BuildComponentFilter(optionalComponents []string) filters.ComponentFilterStrategy

BuildComponentFilter creates a component filter strategy from optional component names. When optionalComponents is empty, only Required and Default Zarf components are included. When optionalComponents lists component names, those are explicitly included alongside Required components. Use the "-name" prefix to explicitly exclude a component.

func PackageSignatureVerificationOptions

func PackageSignatureVerificationOptions(pkg *spec.Package, verificationDir, tmpDir string) (layout.PackageLayoutOptions, error)

PackageSignatureVerificationOptions translates a package signature policy into Zarf layout options.

func ValidateConfig

func ValidateConfig(cfg *UDSBundleConfig) error

ValidateConfig validates configuration used by the private Zarf integration.

func ValidatePackageSignatureVerification

func ValidatePackageSignatureVerification(packageName string, verification *spec.PackageSignatureVerification) error

ValidatePackageSignatureVerification validates the create-time signature policy for a package.

Types

type BundleDeployHooks

type BundleDeployHooks struct {
	// PreDeploy runs before package deployment begins.
	PreDeploy func(context.Context, *spec.UDSBundle, *DeployOptions) error
	// PostDeploy runs after every selected package deploys successfully.
	PostDeploy func(context.Context, *spec.UDSBundle) error
}

BundleDeployHooks provides deployment extension points for a bundle.

type DeployOptions

type DeployOptions struct {
	// Config is the resolved deployment configuration.
	Config *UDSBundleConfig
	// BundlePath identifies the bundle definition.
	BundlePath string
	// BundleDir resolves package-relative paths.
	BundleDir string
	// Packages restricts deployment when non-empty.
	Packages           []string
	BundleDeployHooks  BundleDeployHooks
	PackageDeployHooks PackageDeployHooks
	// PackageDeployFn replaces the complete per-package deployment path when non-nil.
	PackageDeployFn func(context.Context, *spec.Package, DeployPackageOptions) error
}

DeployOptions contains private options for deploying a bundle.

type DeployPackageOptions

type DeployPackageOptions struct {
	// Config is the merged configuration and is always non-nil.
	Config *UDSBundleConfig
	// BundleDir resolves package-relative paths.
	BundleDir string
	// PackageDeployHooks supplies optional package callbacks.
	PackageDeployHooks PackageDeployHooks
	// IsPartial reports whether the loaded layout omits checksum-referenced layers.
	IsPartial bool
	// ClusterDeployFn performs the cluster-side deployment; nil uses Zarf.
	ClusterDeployFn func(context.Context, *layout.PackageLayout, *packager.DeployOptions, bool) error
	// Streams carries operation diagnostics.
	Streams iostreams.IOStreams
	// contains filtered or unexported fields
}

DeployPackageOptions contains options for deploying a single package.

func (DeployPackageOptions) Validate

func (o DeployPackageOptions) Validate() error

Validate checks that DeployPackageOptions is valid.

type DeployResult

type DeployResult struct {
	BundleName string
	Packages   []string
}

DeployResult represents the result of deploying a bundle.

type Deployer

type Deployer interface {
	// DeployPackage deploys one package after its dependencies are available.
	DeployPackage(context.Context, *spec.Package, DeployPackageOptions) error
	// DeployBundle deploys packages in dependency order with bounded parallelism.
	DeployBundle(context.Context, *spec.UDSBundle, DeployOptions) (*DeployResult, error)
}

Deployer deploys individual packages or complete bundles.

type ExtractedArtifactPackageLayoutLoader

type ExtractedArtifactPackageLayoutLoader struct {
	OCIDir           string
	PackageManifests map[string]ocispec.Descriptor
}

ExtractedArtifactPackageLayoutLoader reads package OCI blobs from an extracted bundle artifact.

func (*ExtractedArtifactPackageLayoutLoader) LoadPackageLayout

LoadPackageLayout stages indexed OCI layers into dstDir.

func (*ExtractedArtifactPackageLayoutLoader) PackageStagingRoot

PackageStagingRoot returns the artifact workspace so package layers can be staged alongside their OCI blobs using rooted hard links.

type LayerPathEscapeError

type LayerPathEscapeError struct{ Title string }

func (LayerPathEscapeError) Error

func (e LayerPathEscapeError) Error() string

type LoadOptions

type LoadOptions struct {
	// Streams carries diagnostics for the loader.
	Streams iostreams.IOStreams
	// IsPartial reports whether the loaded package may omit checksum-referenced layers.
	IsPartial bool
}

LoadOptions carries options for package layout loading.

type NilParameterError

type NilParameterError struct{ Name string }

func (NilParameterError) Error

func (e NilParameterError) Error() string

type PackageDeployHooks

type PackageDeployHooks struct {
	// PreDeploy runs after layout loading and before cluster deployment. A
	// returned error skips deployment and PostDeploy.
	PreDeploy func(context.Context, *spec.Package, *layout.PackageLayout, *packager.DeployOptions, *DeployPackageOptions) error
	// PostDeploy runs after a successful package deployment.
	PostDeploy func(context.Context, *spec.Package) error
}

PackageDeployHooks provides deployment extension points per package.

type PackageLayoutLoadResult

type PackageLayoutLoadResult struct {
	Layout    layout.PackageLayout
	IsPartial bool
}

PackageLayoutLoadResult is the return type of LoadPackageLayout

type PackageLayoutLoader

type PackageLayoutLoader interface {
	LoadPackageLayout(context.Context, *spec.Package, string, LoadOptions) (*PackageLayoutLoadResult, error)
}

PackageLayoutLoader loads a package into a deployable Zarf layout.

type PackageSource

type PackageSource interface {
	// PullFiltered retrieves a deployable layout using the supplied filter.
	PullFiltered(context.Context, string, layout.PackageLayoutOptions) (*layout.PackageLayout, error)
	// IngestFiltered copies filtered package content into an OCI store.
	IngestFiltered(context.Context, filters.ComponentFilterStrategy, *udsoci.Store) ([]ocispec.Descriptor, error)
	// VerifyAndIngestFiltered verifies the retrieved package before ingestion.
	VerifyAndIngestFiltered(context.Context, string, layout.PackageLayoutOptions, *udsoci.Store) ([]ocispec.Descriptor, error)
}

PackageSource abstracts local and OCI package retrieval.

func NewPackageSource

func NewPackageSource(source string, opts bundleinternal.ConfigOptions, bundleDir string, streams iostreams.IOStreams) PackageSource

NewPackageSource returns a PackageSource for the given source string. OCI references (detected by IsOCIReference) use zoci.NewRemote; everything else is treated as a local path resolved against bundleDir. streams carries the leveled logger used for ingest/pull diagnostics.

type RemovePackageOptions

type RemovePackageOptions struct {
	// Config is the resolved removal configuration.
	Config *UDSBundleConfig
	// Force bypasses dependency-safety validation.
	Force bool
}

RemovePackageOptions contains options for removing one package.

func (RemovePackageOptions) Validate

func (o RemovePackageOptions) Validate() error

Validate checks that RemovePackageOptions is valid.

type RemovePackageResult

type RemovePackageResult struct {
	Name   string
	Status RemovePackageStatus
}

RemovePackageResult reports the outcome for one package.

type RemovePackageStatus

type RemovePackageStatus string

RemovePackageStatus identifies a package removal outcome.

const (
	RemovePackageStatusRemoved RemovePackageStatus = "removed"
	RemovePackageStatusSkipped RemovePackageStatus = "skipped"
)

type RemoveResult

type RemoveResult struct {
	BundleName string
	Packages   []RemovePackageResult
}

RemoveResult represents the result of removing a bundle.

type Remover

type Remover interface {
	// RemovePackage removes one package from a target.
	RemovePackage(context.Context, *spec.Package, RemovePackageOptions) error
	// RemoveBundle removes selected packages in reverse dependency order.
	RemoveBundle(context.Context, *spec.UDSBundle, []string, RemovePackageOptions) (*RemoveResult, error)
}

Remover removes individual packages or complete bundles.

type SourcePackageLayoutLoader

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

SourcePackageLayoutLoader loads packages from their declared local or OCI sources.

func (*SourcePackageLayoutLoader) LoadPackageLayout

func (l *SourcePackageLayoutLoader) LoadPackageLayout(ctx context.Context, pkg *spec.Package, dstDir string, opts LoadOptions) (*PackageLayoutLoadResult, error)

LoadPackageLayout pulls a package source into a deployable layout.

type UDSBundleConfig

type UDSBundleConfig struct {
	Options   *bundleinternal.ConfigOptions `hcl:"options,block"`
	Variables bundleinternal.Variables
	Remain    hcl.Body `hcl:",remain"`
}

UDSBundleConfig is the private resolved deployment configuration.

type ZarfDeployer

type ZarfDeployer struct {

	// Loader overrides source loading for each package when non-nil.
	Loader PackageLayoutLoader
	// contains filtered or unexported fields
}

ZarfDeployer implements Deployer using the Zarf Go library.

func NewZarfDeployer

func NewZarfDeployer(streams iostreams.IOStreams, loader PackageLayoutLoader) *ZarfDeployer

NewZarfDeployer creates a ZarfDeployer. When loader is nil, packages are loaded from their declared source using SourcePackageLayoutLoader. For local artifact deploys, provide a PackageLayoutLoader implementation that loads packages from the extracted artifact's OCI layout instead of pulling from the declared source.

func (*ZarfDeployer) DeployBundle

func (d *ZarfDeployer) DeployBundle(ctx context.Context, b *spec.UDSBundle, opts DeployOptions) (*DeployResult, error)

DeployBundle deploys the bundle's packages in topological order, parallelising within levels and serialising across them.

func (*ZarfDeployer) DeployPackage

func (d *ZarfDeployer) DeployPackage(ctx context.Context, pkg *spec.Package, opts DeployPackageOptions) error

DeployPackage deploys a single Zarf package using the Zarf Go library.

type ZarfRemover

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

ZarfRemover implements Remover using the Zarf Go library.

func NewZarfRemover

func NewZarfRemover(streams iostreams.IOStreams) *ZarfRemover

NewZarfRemover creates a new ZarfRemover. streams carries the diagnostic sink (streams.ErrOut, typically the command's Streams.ErrOut) used for the Zarf logger during removal, and the leveled logger for UDS-side diagnostics.

func (*ZarfRemover) RemoveBundle

func (r *ZarfRemover) RemoveBundle(ctx context.Context, b *spec.UDSBundle, packages []string, opts RemovePackageOptions) (*RemoveResult, error)

RemoveBundle removes the bundle's packages from the cluster, calling RemovePackage for each package in REVERSE topological order. When packages is non-empty, only those package names are removed. Packages that are not currently deployed are skipped via the ErrPackageNotDeployed sentinel.

func (*ZarfRemover) RemovePackage

func (r *ZarfRemover) RemovePackage(ctx context.Context, pkg *spec.Package, opts RemovePackageOptions) error

RemovePackage removes a single Zarf package from the cluster. Returns ErrPackageNotDeployed if the package is not present on the cluster.

The bundle's pkg.Name is the HCL block label (a bundle-internal identifier constrained to be a valid HCL traversal name), which need not equal the Zarf package's metadata.name. To find the deployed package on the cluster we load metadata from pkg.Source and look up by (zarfMetadataName, namespace).

Jump to

Keyboard shortcuts

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