api

package
v1.0.0-rc1 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: 8 Imported by: 0

Documentation

Overview

Package api defines the version-neutral Zarf package model.

Package api defines Zarf's version-neutral package model.

Index

Constants

View Source
const BuildTimestampFormat = time.RFC1123Z

BuildTimestampFormat is the timestamp format used for package build metadata.

Variables

This section is empty.

Functions

func KnownAPIVersions added in v0.87.0

func KnownAPIVersions() []string

KnownAPIVersions returns the package API versions recognized by this Zarf version, oldest first.

Types

type Action added in v0.87.0

type Action struct {
	Silent          *bool
	MaxTotalSeconds *int
	Retries         *int
	Dir             *string
	Env             []string
	Cmd             string
	Shell           *Shell
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	SetVariables     []Variable
	SetValues        []SetValue
	Description      string
	Wait             *ActionWait
	EnableTemplating bool
}

Action is a command or wait operation performed during a package lifecycle operation.

type ActionDefaults added in v0.87.0

type ActionDefaults struct {
	Silent          bool
	MaxTotalSeconds int
	Retries         int
	Dir             string
	Env             []string
	Shell           Shell
}

ActionDefaults configures every action in an ActionSet unless the action overrides it.

type ActionSet added in v0.87.0

type ActionSet struct {
	Defaults ActionDefaults
	Before   []Action
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	After     []Action
	OnSuccess []Action
	OnFailure []Action
}

ActionSet contains actions for one package lifecycle operation.

type ActionWait added in v0.87.0

type ActionWait struct {
	Cluster *ActionWaitCluster
	Network *ActionWaitNetwork
}

ActionWait specifies a cluster or network condition to wait for.

type ActionWaitCluster added in v0.87.0

type ActionWaitCluster struct {
	Kind      string
	Name      string
	Namespace string
	Condition WaitCondition
}

ActionWaitCluster specifies a cluster-level condition to wait for.

type ActionWaitNetwork added in v0.87.0

type ActionWaitNetwork struct {
	Protocol string
	Address  string
	Code     int
}

ActionWaitNetwork specifies a network-level condition to wait for.

type ArchiveImage added in v0.89.0

type ArchiveImage struct {
	Name string
	ID   string
}

ArchiveImage identifies an image selected from an archive.

type BuildData

type BuildData struct {
	// Hostname is the v1beta1 name (v1alpha1: Terminal).
	Hostname            string
	User                string
	Architecture        string
	Timestamp           string
	Version             string
	Migrations          []string
	RegistryOverrides   map[string]string
	Differential        *Differential
	Flavor              string
	Signed              *bool
	VersionRequirements []VersionRequirement
	ProvenanceFiles     []string
	AggregateChecksum   string

	// Deprecated: Only supported by deprecated v1alpha1 packages.
	DifferentialMissing []string
}

BuildData contains build metadata shared across package API versions.

type Chart added in v0.87.0

type Chart struct {
	Name string
	// LegacyVersion is kept for existing v1alpha1 packages so that we can track the chart's archive and values files.
	// The version of the chart is separately tracked in OCI source, HelmRepository, or GitSource
	//
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	LegacyVersion        string
	Namespace            string
	ReleaseName          string
	ValuesFiles          []ValuesFile
	Values               []ChartValue
	SkipSchemaValidation bool
	ServerSideApply      ServerSideApplyMode
	SkipWait             bool

	HelmRepository *HelmRepositorySource
	Git            *GitSource
	Local          *LocalSource
	OCI            *OCISource

	// Variables are required to run v1alpha1 chart actions.
	//
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Variables []ZarfChartVariable
}

Chart is the operational representation of a chart across API versions.

func (Chart) GetServerSideApply added in v0.87.0

func (c Chart) GetServerSideApply() ServerSideApplyMode

GetServerSideApply returns the configured apply strategy, defaulting to auto.

func (Chart) GitPath added in v0.87.0

func (c Chart) GitPath() string

GitPath returns the chart path within a Git source, if set.

func (Chart) LocalPath added in v0.87.0

func (c Chart) LocalPath() string

LocalPath returns the source path for a local chart.

func (Chart) RepositoryName added in v0.87.0

func (c Chart) RepositoryName() string

RepositoryName returns the named chart in a Helm repository, if set.

func (Chart) SourceURL added in v0.87.0

func (c Chart) SourceURL() string

SourceURL returns the chart source URL, if the chart is remotely sourced.

type ChartValue added in v0.87.0

type ChartValue struct {
	SourcePath   string
	TargetPath   string
	ExcludePaths []string
}

ChartValue maps a source path to a target path.

type ChecksumAlgorithm added in v0.88.0

type ChecksumAlgorithm string

ChecksumAlgorithm identifies the hash used for a file checksum.

const (
	ChecksumSHA256 ChecksumAlgorithm = "sha256"
	ChecksumSHA512 ChecksumAlgorithm = "sha512"
)

Supported file checksum algorithms.

type Component added in v0.87.0

type Component struct {
	Name          string
	Description   string
	Optional      bool
	Selector      ComponentSelector
	Target        ComponentTarget
	Import        ComponentImport
	Service       Service
	Manifests     []Manifest
	Charts        []Chart
	Files         []File
	Images        []Image
	ImageArchives []ImageArchive
	Repositories  []Repository
	StateAccess   []StateAccessKey
	Actions       ComponentActions

	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Default bool
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Group string
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	DataInjections []ZarfDataInjection
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	HealthChecks []NamespacedObjectKindReference
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Distros []string
}

Component is the version-neutral representation of a package component.

func (Component) GetImages added in v0.87.0

func (c Component) GetImages() []string

GetImages returns all images specified by this component, including image archives.

func (Component) RequiresCluster added in v0.87.0

func (c Component) RequiresCluster() bool

RequiresCluster reports whether this component requires a cluster connection.

type ComponentActions added in v0.87.0

type ComponentActions struct {
	OnCreate ActionSet
	OnDeploy ActionSet
	OnRemove ActionSet
}

ComponentActions are the actions associated with each package lifecycle operation.

type ComponentImport added in v0.87.0

type ComponentImport struct {
	// Local and Remote support the multiple imports accepted by v1beta1.
	Local  []ComponentImportLocal
	Remote []ComponentImportRemote

	// Name identifies a v1alpha1 imported component. Path and URL are projected onto
	// Local and Remote by the v1alpha1 converter.
	//
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Name string
}

ComponentImport carries imports from any API version.

type ComponentImportLocal added in v0.87.0

type ComponentImportLocal struct {
	Path string
}

ComponentImportLocal references a local component config file.

type ComponentImportRemote added in v0.87.0

type ComponentImportRemote struct {
	URL string
}

ComponentImportRemote references a remote (OCI) component config.

type ComponentSelector added in v0.87.0

type ComponentSelector struct {
	Architecture string
	Flavor       string
}

ComponentSelector filters a component during package creation.

type ComponentTarget added in v0.87.0

type ComponentTarget struct {
	OS string
}

ComponentTarget filters a component to a target OS at deploy time.

type Constant added in v0.87.0

type Constant struct {
	Name        string
	Value       string
	Description string
	AutoIndent  bool
	Pattern     string
}

Constant is a value that can be used to dynamically template resources or run in actions.

type Differential added in v0.89.0

type Differential struct {
	FromVersion string
}

Differential identifies the base package used to create a differential package. A nil Differential indicates a full package.

type File added in v0.87.0

type File struct {
	Source           string
	Checksum         FileChecksum
	Destination      string
	Executable       bool
	Symlinks         []string
	ExtractPath      string
	EnableTemplating bool
}

File is the version-neutral representation of a package file.

type FileChecksum added in v0.88.0

type FileChecksum struct {
	Algorithm ChecksumAlgorithm
	Digest    string
}

FileChecksum is a file checksum with its algorithm and digest.

func ParseFileChecksum added in v0.88.0

func ParseFileChecksum(value string) FileChecksum

ParseFileChecksum converts a wire-format checksum, defaulting to SHA-256.

func (FileChecksum) GetAlgorithm added in v0.88.0

func (c FileChecksum) GetAlgorithm() ChecksumAlgorithm

GetAlgorithm returns SHA-256 when no algorithm is specified.

func (FileChecksum) IsSet added in v0.88.0

func (c FileChecksum) IsSet() bool

IsSet reports whether a file checksum was provided.

func (FileChecksum) String added in v0.88.0

func (c FileChecksum) String() string

String returns the checksum in the package definition's wire format.

type GitRef added in v0.87.0

type GitRef struct {
	Tag    string
	Branch string
	Commit string
}

GitRef selects a single Git reference.

type GitSource added in v0.87.0

type GitSource struct {
	URL  string
	Path string
	Ref  *GitRef
}

GitSource represents a chart stored in a Git repository.

type HelmRepositorySource added in v0.87.0

type HelmRepositorySource struct {
	Name    string
	URL     string
	Version string
}

HelmRepositorySource represents a chart stored in a Helm repository.

type Image added in v0.87.0

type Image struct {
	ID     string
	Name   string
	Source ImageSource
}

Image represents an OCI image in the package.

type ImageArchive added in v0.87.0

type ImageArchive struct {
	Path   string
	Images []ArchiveImage
}

ImageArchive defines a tar archive of images to include in the package.

type ImageSource added in v0.88.0

type ImageSource string

ImageSource identifies where an image is read during package creation.

const (
	// ImageSourceRegistry reads an image from a registry.
	ImageSourceRegistry ImageSource = "registry"
	// ImageSourceDaemon reads an image from the local container daemon.
	ImageSourceDaemon ImageSource = "daemon"
	// ImageSourceRegistryDaemonFallback reads from a registry, then tries the local container daemon.
	ImageSourceRegistryDaemonFallback ImageSource = "registry-daemon-fallback"
)

func (ImageSource) GetSource added in v0.88.0

func (s ImageSource) GetSource() ImageSource

GetSource returns the registry source when no source is specified.

type InteractiveVariable added in v0.87.0

type InteractiveVariable struct {
	Variable
	Description string
	Default     string
	Prompt      bool
}

InteractiveVariable is a variable that can prompt a user for more information.

type KustomizeManifest added in v0.87.0

type KustomizeManifest struct {
	Files             []string
	AllowAnyDirectory bool
	EnablePlugins     bool
}

KustomizeManifest holds kustomization settings for a manifest.

type LocalSource added in v0.87.0

type LocalSource struct {
	Path string
}

LocalSource represents a chart stored locally.

type Manifest added in v0.87.0

type Manifest struct {
	Name             string
	Namespace        string
	Files            []string
	Kustomize        KustomizeManifest
	SkipWait         bool
	ServerSideApply  ServerSideApplyMode
	EnableTemplating bool
}

Manifest is the version-neutral representation of a manifest entry.

func (Manifest) GetServerSideApply added in v0.87.0

func (m Manifest) GetServerSideApply() ServerSideApplyMode

GetServerSideApply returns the configured apply strategy, defaulting to auto.

type NamespacedObjectKindReference added in v0.87.0

type NamespacedObjectKindReference struct {
	APIVersion string
	Kind       string
	Namespace  string
	Name       string
}

NamespacedObjectKindReference references a cluster resource targeted by a health check.

type OCIRef added in v0.87.0

type OCIRef struct {
	Tag    string
	Digest string
}

OCIRef selects a single OCI reference.

type OCISource added in v0.87.0

type OCISource struct {
	URL string
	Ref *OCIRef
}

OCISource represents a chart stored in an OCI registry.

type Package added in v0.87.0

type Package struct {
	// APIVersion identifies the source package schema. An empty value is the legacy v1alpha1 form.
	APIVersion  string
	Kind        PackageKind
	Metadata    PackageMetadata
	Build       BuildData
	Components  []Component
	Values      Values
	Attachments map[string]string

	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Variables []InteractiveVariable
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Constants []Constant
	// contains filtered or unexported fields
}

Package is the version-neutral representation used by package operations and converters.

func (Package) ComponentSelectors added in v1.0.0

func (p Package) ComponentSelectors() ([]string, bool)

ComponentSelectors returns a detached copy of the normalized, ordered deployment selectors applied to this package. The boolean distinguishes default selection from no recorded selection.

func (Package) GetAPIVersion added in v0.87.0

func (p Package) GetAPIVersion() string

GetAPIVersion returns the package API version, treating the legacy omitted value as v1alpha1.

func (Package) HasComponentSelection added in v1.0.0

func (p Package) HasComponentSelection() bool

HasComponentSelection reports whether deployment selection was applied, including an empty selector list that uses required components and defaults.

func (Package) HasImages added in v0.87.0

func (p Package) HasImages() bool

HasImages reports whether a package contains images or image archives.

func (Package) IsInitConfig added in v0.87.0

func (p Package) IsInitConfig() bool

IsInitConfig reports whether this is a Zarf init package.

func (Package) IsSBOMAble added in v0.87.0

func (p Package) IsSBOMAble() bool

IsSBOMAble reports whether this package contains content that can have an SBOM.

func (*Package) OverrideNamespace added in v0.87.0

func (p *Package) OverrideNamespace(namespace string) error

OverrideNamespace overrides component namespaces when the package permits it.

func (*Package) RemoveImages added in v0.87.0

func (p *Package) RemoveImages()

RemoveImages removes images and image archives from every component.

func (*Package) RemoveRepositories added in v0.87.0

func (p *Package) RemoveRepositories()

RemoveRepositories removes git repositories from every component.

func (*Package) SetComponentSelectors added in v1.0.0

func (p *Package) SetComponentSelectors(selectors []string)

SetComponentSelectors records a successful deployment selection. Filtering supplies normalized selectors; assembly may restore them after an in-memory definition crosses a serialization boundary.

func (Package) Validate added in v0.87.0

func (p Package) Validate() error

Validate rejects fields that cannot be represented by the package's API version. An omitted apiVersion is assumed v1alpha1. This does not validate field values correctness

type PackageKind added in v0.87.0

type PackageKind string

PackageKind identifies the kind of a Zarf package.

const (
	// ZarfInitConfig is the package kind used during zarf init.
	ZarfInitConfig PackageKind = "ZarfInitConfig"
	// ZarfPackageConfig is the default package kind.
	ZarfPackageConfig PackageKind = "ZarfPackageConfig"
)

type PackageMetadata added in v0.87.0

type PackageMetadata struct {
	Name                     string
	Description              string
	Version                  string
	Uncompressed             bool
	Architecture             string
	Annotations              map[string]string
	PreventNamespaceOverride bool

	// Deprecated: Only supported by deprecated v1alpha1 packages.
	URL string
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Image string
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	YOLO bool
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Authors string
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Documentation string
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Source string
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Vendor string
}

PackageMetadata contains metadata from all supported package API versions.

type Repository added in v0.87.0

type Repository struct {
	URL string
	Ref *GitRef
	// LegacyURL retains the original v1alpha1 URL, including an inline ref, so
	// repositories retain the directory names used by existing package layouts
	// For instance, GitRef can't express ref/tags/v1.0 vs only v1.0
	//
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	LegacyURL string
}

Repository defines a Git repository and the optional reference to retrieve.

type ServerSideApplyMode added in v0.87.0

type ServerSideApplyMode string

ServerSideApplyMode controls when server-side apply is used during deploy.

const (
	// ServerSideApplyEnabled always uses server-side apply.
	ServerSideApplyEnabled ServerSideApplyMode = "true"
	// ServerSideApplyDisabled always uses client-side apply.
	ServerSideApplyDisabled ServerSideApplyMode = "false"
	// ServerSideApplyAuto uses server-side apply for fresh installs and matches the prior strategy on upgrade.
	ServerSideApplyAuto ServerSideApplyMode = "auto"
)

type Service added in v0.87.0

type Service struct {
	Name ServiceName
}

Service identifies a Zarf-managed cluster service provided by a component.

type ServiceName added in v0.88.0

type ServiceName string

ServiceName identifies a Zarf-managed cluster service.

const (
	ServiceRegistry     ServiceName = "registry"
	ServiceSeedRegistry ServiceName = "seed-registry"
	ServiceInjector     ServiceName = "injector"
	ServiceAgent        ServiceName = "agent"
	ServiceGitServer    ServiceName = "git-server"
)

Service identifiers used by components that provide Zarf-managed cluster services.

type SetValue added in v0.87.0

type SetValue struct {
	Key string
	// Deprecated: Only supported by deprecated v1alpha1 packages.
	Value any
	Type  SetValueType
}

SetValue declares how command output is stored in the package values map.

type SetValueType added in v0.87.0

type SetValueType string

SetValueType declares the expected output format of an action command.

const (
	// SetValueYAML parses command output as YAML.
	SetValueYAML SetValueType = "yaml"
	// SetValueJSON parses command output as JSON.
	SetValueJSON SetValueType = "json"
	// SetValueString stores command output without parsing.
	SetValueString SetValueType = "string"
)

type Shell added in v0.87.0

type Shell struct {
	Windows string
	Linux   string
	Darwin  string
}

Shell identifies the preferred command shell on each supported operating system.

type StateAccessKey added in v0.87.0

type StateAccessKey string

StateAccessKey identifies a named group of sensitive state fields available in Go templates.

const (
	// StateAccessRegistryCredentials unlocks registry credentials in .State.
	StateAccessRegistryCredentials StateAccessKey = "registryCredentials"
	// StateAccessGitCredentials unlocks Git credentials in .State.
	StateAccessGitCredentials StateAccessKey = "gitCredentials"
	// StateAccessAgentCerts unlocks agent certificates in .State.
	StateAccessAgentCerts StateAccessKey = "agentCerts"
)

type Values added in v0.87.0

type Values struct {
	Files  []string
	Schema string
}

Values defines values files and schema.

type ValuesFile added in v0.87.0

type ValuesFile struct {
	Path             string
	EnableTemplating bool
}

ValuesFile is a values file merged into a Helm chart, optionally rendered with Zarf templating.

type Variable added in v0.87.0

type Variable struct {
	Name       string
	Sensitive  bool
	AutoIndent bool
	Pattern    string
	Type       VariableType
}

Variable represents a variable that has a value set programmatically.

type VariableType added in v0.87.0

type VariableType string

VariableType represents a type of a Zarf package variable.

const (
	// RawVariableType is the default type for a Zarf package variable.
	RawVariableType VariableType = "raw"
	// FileVariableType loads a variable's contents from a file.
	FileVariableType VariableType = "file"
)

type VersionRequirement

type VersionRequirement struct {
	Version string
	Reason  string
}

VersionRequirement specifies a minimum Zarf version needed.

type WaitCondition added in v0.87.0

type WaitCondition struct {
	Expression string
	Default    WaitDefault
}

WaitCondition carries both an explicit condition and the semantic default used when it is empty.

type WaitDefault added in v0.87.0

type WaitDefault string

WaitDefault is the behavior used when a cluster wait condition is omitted.

const (
	// WaitForExistence waits for a resource to exist when no condition is supplied.
	WaitForExistence WaitDefault = "existence"
	// WaitForReadiness waits for a resource to be reconciled when no condition is supplied.
	WaitForReadiness WaitDefault = "readiness"
)

type ZarfChartVariable added in v0.87.0

type ZarfChartVariable struct {
	Name        string
	Description string
	Path        string
}

ZarfChartVariable represents a variable that can be set for Helm chart overrides.

type ZarfContainerTarget added in v0.87.0

type ZarfContainerTarget struct {
	Namespace string
	Selector  string
	Container string
	Path      string
}

ZarfContainerTarget defines the destination info for a ZarfDataInjection target.

type ZarfDataInjection added in v0.87.0

type ZarfDataInjection struct {
	Source   string
	Target   ZarfContainerTarget
	Compress bool
}

ZarfDataInjection is a data-injection definition.

Directories

Path Synopsis
Package convert is the public conversion boundary between wire schemas and api.Package.
Package convert is the public conversion boundary between wire schemas and api.Package.
Package v1alpha1 holds the definition of the v1alpha1 Zarf Package
Package v1alpha1 holds the definition of the v1alpha1 Zarf Package
Package v1beta1 holds the definition of the v1beta1 Zarf Package.
Package v1beta1 holds the definition of the v1beta1 Zarf Package.

Jump to

Keyboard shortcuts

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