packager

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 78 Imported by: 6

Documentation

Overview

Package packager contains high level operations for Zarf packages

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Create added in v0.56.0

func Create(ctx context.Context, packagePath string, output string, opts CreateOptions) (_ string, err error)

Create takes a path to a directory containing a ZarfPackageConfig and returns the path to the created package

func DevDeploy added in v0.56.0

func DevDeploy(ctx context.Context, packagePath string, opts DevDeployOptions) (err error)

DevDeploy creates + deploys a package in one shot

func Generate deprecated added in v0.56.0

func Generate(ctx context.Context, packageName, url, version string, opts GenerateOptions) (pkg v1alpha1.ZarfPackage, err error)

Generate a Zarf package definition using information about a Helm chart.

Deprecated: Only supported by deprecated v1alpha1 packages.

func GenerateValuesSchema added in v0.88.0

func GenerateValuesSchema(ctx context.Context, source string, opts GenerateValuesSchemaOptions) (value.SchemaDocument, error)

GenerateValuesSchema generates a values schema from defaults, rendered chart values files, and chart schemas, reconciled with any existing values schema.

func GetPackageFromSourceOrCluster added in v0.56.0

func GetPackageFromSourceOrCluster(ctx context.Context, cluster *cluster.Cluster, src string, namespaceOverride string, opts LoadOptions) (_ api.Package, err error)

GetPackageFromSourceOrCluster retrieves a package definition from a source or cluster.

func Lint added in v0.56.0

func Lint(ctx context.Context, packagePath string, opts LintOptions) error

Lint lints a Zarf package or component config.

func LoadPackage added in v0.56.0

func LoadPackage(ctx context.Context, source string, opts LoadOptions) (_ *layout.PackageLayout, err error)

LoadPackage fetches, verifies, and loads a Zarf package from the specified source.

func PackageDigest added in v0.80.0

func PackageDigest(ctx context.Context, source string, opts PackageDigestOptions) (string, error)

PackageDigest returns the SHA256 OCI manifest digest for the given package source. For OCI sources the digest is resolved directly from the registry without downloading the package. For local tarballs the manifest is computed deterministically from the package contents, producing the same digest that would result from publishing with PushPackage.

func PublishFromOCI added in v0.56.0

func PublishFromOCI(ctx context.Context, src registry.Reference, dst registry.Reference, opts PublishFromOCIOptions) (err error)

PublishFromOCI takes a source and destination registry reference and a PublishFromOCIOpts and copies the package from the source to the destination. src and dst are references to the full package ref, e.g. my-registry.com/my-namespace/my-package:0.0.1 therefore any tag manipulation happens from the calling logic

func PublishPackage added in v0.56.0

func PublishPackage(ctx context.Context, pkgLayout *layout.PackageLayout, dst registry.Reference, opts PublishPackageOptions) (registry.Reference, error)

PublishPackage takes a package layout and pushes the package to the given registry. dst is the path to the registry namespace, e.g. my-registry.com/my-namespace. The full package ref is created using the package name and returned

func PublishSkeleton deprecated added in v0.56.0

func PublishSkeleton(ctx context.Context, path string, ref registry.Reference, opts PublishSkeletonOptions) (_ registry.Reference, err error)

PublishSkeleton takes a Path to the package definition and uploads a skeleton package to the given a registry. dst is the path to the registry namespace, e.g. my-registry.com/my-namespace. The full package ref is created using the package name and returned

Deprecated: Only supported by deprecated v1alpha1 packages.

func Pull added in v0.55.0

func Pull(ctx context.Context, source, destination string, opts PullOptions) (_ string, err error)

Pull takes a source URL and destination directory, fetches the Zarf package from the given sources, and returns the path to the fetched package.

func PushImagesToRegistry added in v0.56.0

func PushImagesToRegistry(ctx context.Context, pkgLayout *layout.PackageLayout, registryInfo state.RegistryInfo, opts ImagePushOptions) error

PushImagesToRegistry pushes images in the package layout to the specified registry

func PushReposToRepository added in v0.56.0

func PushReposToRepository(ctx context.Context, pkgLayout *layout.PackageLayout, gitInfo state.GitServerInfo, opts RepoPushOptions) error

PushReposToRepository pushes Git repositories in the package layout to the Git server

func Remove added in v0.56.0

func Remove(ctx context.Context, definition api.Package, opts RemoveOptions) error

Remove runs removal actions and uninstalls recorded Helm charts for components selected by the ordered ComponentSelectors list, with the last matching selector taking precedence. An empty list selects all components. When a deployment record exists, it preserves unselected components and records progress even for local-only selections. Standalone local packages without a deployment record never create one.

func UpdateImages added in v0.66.0

func UpdateImages(ctx context.Context, packagePath string, definitionImageResults []DefinitionImageResult) error

UpdateImages updates the images field for components in a zarf.yaml.

func UpdateSchema added in v0.80.0

func UpdateSchema(ctx context.Context, packagePath string, schemaFilename string) error

UpdateSchema updates the values.schema field in a zarf.yaml to point to the given relative schema filename.

Types

type ComponentImageScan added in v0.56.0

type ComponentImageScan struct {
	ComponentName string
	Matches       []ImageMatch
	// WhyResources contains the resources where specific images were found (when Why option is used)
	WhyResources []Resource
}

ComponentImageScan contains the results of FindImages for a component.

func FindImages added in v0.56.0

func FindImages(ctx context.Context, packagePath string, opts FindImagesOptions) (_ []ComponentImageScan, err error)

FindImages iterates over the manifests and charts within each component to find any container images It returns []ComponentImageScan which contains a scan result for each component

type CreateOptions added in v0.56.0

type CreateOptions struct {
	// Architecture overrides package metadata. Empty falls back to metadata, then the host.
	Architecture      string
	Flavor            string
	RegistryOverrides []images.RegistryOverride
	// A nil value leaves the package unsigned; a non-nil value requests signing.
	SignBlobOptions         *signing.SignBlobOptions
	SetVariables            map[string]string
	MaxPackageSizeMB        int
	SBOMOut                 string
	SkipSBOM                bool
	DifferentialPackagePath string
	OCIConcurrency          int
	CachePath               string
	WithBuildMachineInfo    bool
	// applicable when output is an OCI registry
	types.RemoteOptions
	// IsInteractive decides if Zarf can interactively prompt users through the CLI
	IsInteractive bool
	// SkipVersionCheck skips version requirement validation
	SkipVersionCheck bool
}

CreateOptions are the optional parameters to create.

type DefinitionImageResult added in v0.77.0

type DefinitionImageResult struct {
	ComponentImageScan
	ImageArchives []api.ImageArchive
	Selector      api.ComponentSelector
}

DefinitionImageResult contains the results of FindDefinitionImages for a component

func FindDefinitionImages added in v0.77.0

func FindDefinitionImages(ctx context.Context, packagePath string, opts FindImagesOptions) (_ []DefinitionImageResult, err error)

FindDefinitionImages finds all images contained in a component and filters them according to images discovered in imageArchives. It returns []DefinitionImageResult

type DeployConfig added in v1.0.0

type DeployConfig = state.DeployConfig

DeployConfig is a compatibility alias for the persisted deployment configuration. ComponentSelectors is a selector list generated by Deploy as provenance from package filtering, not a deployment input.

type DeployOptions added in v0.56.0

type DeployOptions struct {
	// SetVariables supplies deploy-time variable overrides.
	SetVariables map[string]string
	// Values supplies deploy-time package value overrides.
	Values value.Values
	// NamespaceOverride overrides the namespace used by deployed resources.
	NamespaceOverride string
	// ValuesOverridesMap supplies per-component chart value overrides.
	ValuesOverridesMap ValuesOverrides
	// Connectivity controls whether deployment uses connected or air-gap mode.
	Connectivity state.PackageConnectivity
	// TakeOwnership adopts any pre-existing K8s resources into the Helm charts managed by Zarf
	TakeOwnership bool
	// Force Helm to take ownership of conflicting fields during Server-Side Apply operations
	ForceConflicts bool
	// Timeout for Helm operations
	Timeout time.Duration
	// Retries is the maximum attempts for retryable deployment operations, including transient Helm admission-webhook failures.
	Retries int
	// Number of layers to push concurrently per image
	OCIConcurrency int
	// Remote Options for image pushes
	types.RemoteOptions
	// How to configure Zarf state if it's not already been configured
	GitServer    state.GitServerInfo
	RegistryInfo state.RegistryInfo
	InjectorPort int
	// InjectorImage is the injector container image. Proxy mode defaults to the image saved in cluster state and requires an image on first init.
	InjectorImage string
	// AgentTLS allows providing user-managed TLS certificates for the agent. When nil, certs are auto-generated.
	AgentTLS *pki.GeneratedPKI
	// AgentMutationPolicy controls whether the agent mutates by default (default-mutate) or only on explicit label (default-ignore).
	AgentMutationPolicy state.MutationPolicy
	// Source identifies the resolved package source for event provenance.
	Source string
	// IsInteractive decides if Zarf can interactively prompt users through the CLI
	IsInteractive bool
	// SkipValuesSchemaValidation skips validation of the merged package values against the package schema.
	SkipValuesSchemaValidation bool
	// SkipArchitectureCheck allows application images to deploy to nodes with a different architecture.
	// The operator must configure emulation on the target nodes.
	SkipArchitectureCheck bool
	// SkipVersionCheck skips version requirement validation
	SkipVersionCheck bool
}

DeployOptions are optional parameters to Deploy. Component selection is applied by filtering the package before deployment.

func (DeployOptions) Validate added in v1.0.0

func (opts DeployOptions) Validate(pkg api.Package) error

Validate checks whether the deployment options are supported by the package.

type DeployResult added in v0.58.0

type DeployResult struct {
	DeployedComponents []state.DeployedComponent
	VariableConfig     *variables.VariableConfig
	Values             value.Values
}

DeployResult is the result of a successful deploy

func Deploy added in v0.56.0

func Deploy(ctx context.Context, pkgLayout *layout.PackageLayout, opts DeployOptions) (DeployResult, error)

Deploy deploys the components present in pkgLayout and returns their deployment records, variable configuration, and values on success. Component selection and its provenance come from the already-filtered layout.

type DevDeployOptions added in v0.56.0

type DevDeployOptions struct {
	// Architecture overrides package metadata when loading the definition.
	Architecture string
	// When true packs images and repos into the package and uses the cluster Zarf state
	// When false deploys package without repos or images and uses the default Zarf state
	AirgapMode bool
	// Flavor causes the package to only include components with a matching `.components[x].only.flavor` or no flavor `.components[x].only.flavor` specified
	Flavor string
	// RegistryURL allows for an override to the Zarf state registry URL when not in airgap mode. Important for setting the ###ZARF_REGISTRY### template
	RegistryURL string
	// RegistryOverrides overrides the basepath of an OCI image with a path to a different registry during package assembly
	RegistryOverrides []images.RegistryOverride
	// CreateSetVariables are for package templates
	CreateSetVariables map[string]string
	// DeploySetVariables are for package variables
	DeploySetVariables map[string]string
	// Values are values passed in at deploy time.
	Values value.Values
	// OptionalComponents to be deployed
	OptionalComponents string
	// Timeout for Helm operations
	Timeout time.Duration
	// Retries to preform for operations like git and image pushes
	Retries int
	// These fields are only used if in airgap mode as they are relevant to requests from the git-server / registry
	OCIConcurrency int
	CachePath      string
	// SkipVersionCheck skips version requirement validation
	SkipVersionCheck bool
	// SkipArchitectureCheck allows application images to deploy to nodes with a different architecture.
	// The operator must configure emulation on the target nodes. Only applies in airgap mode.
	SkipArchitectureCheck bool
	// TakeOwnership adopts any pre-existing K8s resources into the Helm charts managed by Zarf
	TakeOwnership bool
	types.RemoteOptions
}

DevDeployOptions are the optionalParameters to DevDeploy

type FindImagesOptions added in v0.56.0

type FindImagesOptions struct {
	// Architecture overrides package metadata; standalone components use their declared variant.
	Architecture string
	// EnableKustomizePlugins allows plugins enabled in the package definition to execute arbitrary commands.
	EnableKustomizePlugins bool
	// RepoHelmChartPath specifies the path to helm charts in git repos defined in the zarf.yaml
	RepoHelmChartPath string
	// RegistryURL specifies the value of the ###ZARF_REGISTRY### variable during templating
	RegistryURL string
	// KubeVersionOverride specifies the kubernetes version to provide the Helm chart
	KubeVersionOverride string
	// CreateSetVariables specifies the package create templates
	CreateSetVariables map[string]string
	// DeploySetVariables specifies the package deploy variables
	DeploySetVariables map[string]string
	// Values are values passed in at find-images time. They can come from the CLI, user configuration, or set directly
	// by API callers.
	Values value.Values
	// Flavor specifies the flavor to use
	Flavor string
	// Why specifies the image to look for so we can print the containing manifest
	Why string
	// SkipCosign specifies whether to skip cosign artifact lookups
	SkipCosign bool
	// CachePath is used to cache layers from skeleton package pulls
	CachePath string
	// IsInteractive decides if Zarf can interactively prompt users through the CLI
	IsInteractive bool
	types.RemoteOptions
}

FindImagesOptions declares the parameters to find images.

type GenerateOptions added in v0.56.0

type GenerateOptions struct {
	// Path to the Helm chart in the git repository
	GitPath string
	// Kube version to provide to the Helm chart
	KubeVersion string
}

GenerateOptions are the options for generating a Zarf package.

type GenerateValuesSchemaOptions added in v0.88.0

type GenerateValuesSchemaOptions struct {
	load.DefinitionOptions
	// Update writes the schema and adds its reference to the source definition when absent.
	Update bool
	// DeleteNotFound removes existing schema properties absent from the generated schema.
	DeleteNotFound bool
}

GenerateValuesSchemaOptions configures schema generation from a package or component config.

type ImageMatch added in v0.88.0

type ImageMatch struct {
	Image     api.Image
	MatchType MatchType
}

ImageMatch is an image found in a component's resources.

type ImagePushOptions added in v0.56.0

type ImagePushOptions struct {
	Cluster         *cluster.Cluster
	NoImageChecksum bool
	Retries         int
	OCIConcurrency  int
	types.RemoteOptions
}

ImagePushOptions are optional parameters to push images in a zarf package to a registry

type InspectDefinitionResourcesOptions added in v0.56.0

type InspectDefinitionResourcesOptions struct {
	// Architecture overrides package metadata; standalone components use their declared variant.
	Architecture string
	// EnableKustomizePlugins allows plugins enabled in the package definition to execute arbitrary commands.
	EnableKustomizePlugins bool
	CreateSetVariables     map[string]string
	DeploySetVariables     map[string]string
	// Values are values passed in at inspect time. They can come from the CLI, user configuration, or set directly by
	// API callers.
	Values      value.Values
	Flavor      string
	Components  string
	KubeVersion string
	// CachePath is used to cache layers from skeleton package pulls
	CachePath string
	// IsInteractive decides if Zarf can interactively prompt users through the CLI
	IsInteractive bool
	types.RemoteOptions
}

InspectDefinitionResourcesOptions are the optional parameters to InspectDefinitionResources

type InspectPackageResourcesOptions added in v0.56.0

type InspectPackageResourcesOptions struct {
	SetVariables map[string]string
	// Values merge on top of the package's values.yaml and feed chart overrides and manifest Go-templates.
	Values      value.Values
	KubeVersion string
	// SkipValuesSchemaValidation skips validation of the merged package values against the package schema.
	SkipValuesSchemaValidation bool
	// IsInteractive decides if Zarf can interactively prompt users through the CLI
	IsInteractive bool
	types.RemoteOptions
}

InspectPackageResourcesOptions are the optional parameters to InspectPackageResources

type LintOptions added in v0.56.0

type LintOptions struct {
	// Architecture overrides package metadata; standalone components use their declared variant.
	Architecture string
	SetVariables map[string]string
	Flavor       string
	CachePath    string
	types.RemoteOptions
}

LintOptions are the optional parameters to Lint

type LoadOptions added in v0.56.0

type LoadOptions struct {
	Shasum string
	// Architecture selects the target architecture for OCI sources.
	// Empty uses the host architecture. Ignored for local archives.
	Architecture      string
	VerifyBlobOptions *signing.VerifyBlobOptions
	Filter            filters.ComponentFilterStrategy
	Output            string
	// number of layers to pull in parallel
	OCIConcurrency int
	// LayerSelection specifies which optional package resources to pull from OCI.
	// A nil value selects every resource while an empty value selects only the metadata resources.
	LayerSelection *zoci.LayerSelection
	// CachePath is used to cache layers from OCI package pulls
	CachePath string
	// Connected skips pulling image layers from OCI sources
	Connected bool
	// Only applicable to OCI + HTTP
	types.RemoteOptions
	// VerificationStrategy for explicit definition
	layout.VerificationStrategy
}

LoadOptions are the options for LoadPackage.

type MatchType added in v0.88.0

type MatchType string

MatchType identifies how an image was found.

const (
	// MatchDefinite is an image identified directly in a resource or chart annotation.
	MatchDefinite MatchType = "definite"
	// MatchPossible is an image inferred from resource text and confirmed in a registry.
	MatchPossible MatchType = "possible"
	// MatchCosign is a signature or attestation image found for another match.
	MatchCosign MatchType = "cosign"
)

type PackageDigestOptions added in v0.80.0

type PackageDigestOptions struct {
	Architecture  string
	RemoteOptions types.RemoteOptions
	// Cluster is required when the source is a deployed package name (cluster source).
	Cluster *cluster.Cluster
	// NamespaceOverride is the namespace override used when the package was deployed,
	// required to locate the correct secret for cluster sources.
	NamespaceOverride string
}

PackageDigestOptions are the options for PackageDigest.

type PublishFromOCIOptions added in v0.56.0

type PublishFromOCIOptions struct {
	// OCIConcurrency configures the amount of layers to push in parallel
	OCIConcurrency int
	// Architecture is the architecture we are publishing to
	Architecture string
	// Retries is the number of times to retry a failed push
	Retries int
	types.RemoteOptions
}

PublishFromOCIOptions declares the parameters to publish a package.

type PublishPackageOptions added in v0.56.0

type PublishPackageOptions struct {
	// OCIConcurrency configures the amount of layers to push in parallel
	OCIConcurrency int
	// Retries specifies the number of retries to use
	Retries int
	types.RemoteOptions
	// Tag is an optional tag for the OCI reference separate from the package metadata.version
	Tag string
}

PublishPackageOptions declares the parameters to publish a package.

type PublishSkeletonOptions added in v0.56.0

type PublishSkeletonOptions struct {
	// Architecture selects package components, falling back to metadata and then the host.
	Architecture string
	// OCIConcurrency configures the amount of layers to push in parallel
	OCIConcurrency int
	// CachePath is used to cache layers from skeleton package pulls
	CachePath string
	// Flavor specifies the flavor to use
	Flavor string
	// Retries specifies the number of retries to use
	Retries int
	// SkipVersionCheck skips version requirement validation
	SkipVersionCheck bool
	// WithBuildMachineInfo controls whether to include build machine information (hostname and username) in the package metadata
	WithBuildMachineInfo bool
	types.RemoteOptions
	// Tag is an optional tag for the OCI reference separate from the package metadata.version
	Tag string
}

PublishSkeletonOptions declares the parameters to publish a skeleton package.

type PullOptions added in v0.55.0

type PullOptions struct {
	// SHASum uniquely identifies a package based on its contents.
	SHASum string
	// Architecture is the package architecture.
	Architecture string
	// VerifyBlobOptions configures package signature verification.
	VerifyBlobOptions *signing.VerifyBlobOptions
	// OCIConcurrency is the number of layers pulled in parallel
	OCIConcurrency int
	// CachePath is used to cache layers from OCI package pulls
	CachePath string
	types.RemoteOptions
	// VerificationStrategy for explicit definition
	layout.VerificationStrategy
}

PullOptions declares optional configuration for a Pull operation.

type RemoveConfig added in v1.0.0

type RemoveConfig = state.RemoveConfig

RemoveConfig is a compatibility alias for removal input configuration; only its digest is recorded.

type RemoveOptions added in v0.56.0

type RemoveOptions struct {
	RemoveConfig
	Cluster *cluster.Cluster
	// Timeout for Helm operations.
	Timeout          time.Duration
	SkipVersionCheck bool
}

RemoveOptions are the options for Remove.

type RepoPushOptions added in v0.56.0

type RepoPushOptions struct {
	Cluster *cluster.Cluster
	Retries int
}

RepoPushOptions are optional parameters to push repos in a zarf package to a Git server

type Resource added in v0.56.0

type Resource struct {
	Content      string
	Name         string
	ResourceType ResourceType
}

Resource contains a Kubernetes Manifest or Chart

func InspectDefinitionResources added in v0.56.0

func InspectDefinitionResources(ctx context.Context, packagePath string, opts InspectDefinitionResourcesOptions) (_ []Resource, err error)

InspectDefinitionResources templates and returns the manifests and Helm chart manifests found in the definition at the given path

func InspectPackageResources added in v0.56.0

func InspectPackageResources(ctx context.Context, pkgLayout *layout.PackageLayout, opts InspectPackageResourcesOptions) (_ []Resource, err error)

InspectPackageResources templates and returns the manifests, charts, and values files in the package as they would be on deploy

type ResourceType added in v0.56.0

type ResourceType string

ResourceType represents the different types of Zarf resources that can be inspected

const (
	ManifestResource   ResourceType = "manifest"
	ChartResource      ResourceType = "chart"
	ValuesFileResource ResourceType = "valuesfile"
)

The different types of resources that can be inspected

type ValuesOverrides added in v0.64.0

type ValuesOverrides = state.ValuesOverrides

ValuesOverrides is a compatibility alias for the persisted deploy override type.

Directories

Path Synopsis
Package actions contains functions for running component actions within Zarf packages.
Package actions contains functions for running component actions within Zarf packages.
Package assemble builds a Zarf package on disk: it resolves each component's charts, manifests, files, repos, images and data injections into the layout that package layout reads back.
Package assemble builds a Zarf package on disk: it resolves each component's charts, manifests, files, repos, images and data injections into the layout that package layout reads back.
Package filters contains core implementations of the ComponentFilterStrategy interface.
Package filters contains core implementations of the ComponentFilterStrategy interface.
Package layout contains functions for interacting with Zarf packages.
Package layout contains functions for interacting with Zarf packages.
Package load takes a ZarfPackageConfig, composes imports, and validates the con
Package load takes a ZarfPackageConfig, composes imports, and validates the con

Jump to

Keyboard shortcuts

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