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 ¶
- Variables
- func BuildComponentFilter(optionalComponents []string) filters.ComponentFilterStrategy
- func PackageSignatureVerificationOptions(pkg *spec.Package, verificationDir, tmpDir string) (layout.PackageLayoutOptions, error)
- func ValidateConfig(cfg *UDSBundleConfig) error
- func ValidatePackageSignatureVerification(packageName string, verification *spec.PackageSignatureVerification) error
- type BundleDeployHooks
- type DeployOptions
- type DeployPackageOptions
- type DeployResult
- type Deployer
- type ExtractedArtifactPackageLayoutLoader
- type LayerPathEscapeError
- type LoadOptions
- type NilParameterError
- type PackageDeployHooks
- type PackageLayoutLoadResult
- type PackageLayoutLoader
- type PackageSource
- type RemovePackageOptions
- type RemovePackageResult
- type RemovePackageStatus
- type RemoveResult
- type Remover
- type SourcePackageLayoutLoader
- type UDSBundleConfig
- type ZarfDeployer
- type ZarfRemover
Constants ¶
This section is empty.
Variables ¶
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 ¶
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 ¶
func (l *ExtractedArtifactPackageLayoutLoader) LoadPackageLayout(ctx context.Context, pkg *spec.Package, dstDir string, opts LoadOptions) (*PackageLayoutLoadResult, error)
LoadPackageLayout stages indexed OCI layers into dstDir.
func (*ExtractedArtifactPackageLayoutLoader) PackageStagingRoot ¶
func (l *ExtractedArtifactPackageLayoutLoader) PackageStagingRoot(_ context.Context) string
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).