layout

package
v0.87.0 Latest Latest
Warning

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

 Go to latest Published: Oct 1, 2026 License: Apache-2.0 Imports: 38 Imported by: 8

Documentation

Overview

Package layout contains functions for interacting with Zarf packages.

Index

Constants

View Source 
const (
	ZarfYAML          = "zarf.yaml"
	ZarfGeneratedYAML = "zarf.gen.yaml"
	// Deprecated: legacy signature format superseded by Bundle (zarf.bundle.sig) since v0.71.0 and no longer produced as of v0.81.0.
	// This field is retained to ensure backwards compatibility with verification of older packages.
	Signature    = "zarf.yaml.sig"
	Bundle       = "zarf.bundle.sig"
	Checksums    = "checksums.txt"
	ValuesYAML   = "values.yaml"
	ValuesSchema = "values.schema.json"

	ImagesDir     = "images"
	ComponentsDir = "components"

	SBOMDir = "zarf-sbom"
	SBOMTar = "sboms.tar"

	DocumentationTar = "documentation.tar"

	IndexJSON = "index.json"
	OCILayout = "oci-layout"
)

Constants used in the default package layout.

View Source 
const (
	// ZarfLayerMediaTypeBlob is the media type for all Zarf package layer blobs.
	ZarfLayerMediaTypeBlob = "application/vnd.zarf.layer.v1.blob"
	// ZarfConfigMediaType is the media type for the Zarf package manifest config.
	ZarfConfigMediaType = "application/vnd.zarf.config.v1+json"
	// ZarfComponentConfigMediaType is the media type for a v1beta1 Zarf component config OCI artifact.
	ZarfComponentConfigMediaType = "application/vnd.zarf.component.config.v1+json"
	// ComponentResourceMountPathAnnotation identifies where a component resource is mounted in its OCI artifact.
	ComponentResourceMountPathAnnotation = "dev.zarf.mountPath"
	// OCITimestampFormat is the format used for the OCI timestamp annotation
	OCITimestampFormat = time.RFC3339
)

Variables

View Source 
var (
	// IndexPath is the path to the index.json file
	IndexPath = filepath.Join(ImagesDir, IndexJSON)
	// ImagesBlobsDir is the path to the directory containing the image blobs in the OCI package.
	ImagesBlobsDir = filepath.Join(ImagesDir, "blobs", "sha256")
	// OCILayoutPath is the path to the oci-layout file
	OCILayoutPath = filepath.Join(ImagesDir, OCILayout)
)
View Source 
var ErrNoVerificationMaterial = errors.New("no verification material available")

ErrNoVerificationMaterial is returned when there is nothing to verify against. VerifyIfPossible tolerates this; all other verification errors are always fatal.

Functions

func AnnotationsFromMetadata added in v0.80.0 

func AnnotationsFromMetadata(pkg api.Package) map[string]string

AnnotationsFromMetadata extracts OCI manifest annotations from a package definition.

func ChartArchiveName added in v0.83.0 

func ChartArchiveName(name, version string) string

ChartArchiveName returns the file name of a chart's packaged tarball, within a component's charts directory.

func ChartValuesFileName added in v0.83.0 

func ChartValuesFileName(name, version string, idx int) string

ChartValuesFileName returns the file name of the idx-th values file of the named chart, within a component's values directory.

func ComponentFileRelPath added in v0.78.0 

func ComponentFileRelPath(idx int, target string) string

ComponentFileRelPath returns the path, relative to a component's files directory, where the idx-th file's contents are stored.

func FormatDocumentFileName added in v0.68.0 

func FormatDocumentFileName(key, file string) string

FormatDocumentFileName for storing the document in the package or presenting it to the user

func GetDocumentationFileNames added in v0.68.0 

func GetDocumentationFileNames(documentation map[string]string) map[string]string

GetDocumentationFileNames returns a map of documentation keys to their final filenames. Filenames are deconflicted: if multiple keys have the same basename, they get prefixed with the key.

func HasImageIndex added in v0.83.0 

func HasImageIndex(imageDir string) (bool, error)

HasImageIndex reports whether the package layout has a multi-platform image. It takes a directory rather than a PackageLayout so callers assembling a package layout may use it as well.

func KustomizationFileName added in v0.78.0 

func KustomizationFileName(manifestName string, idx int) string

KustomizationFileName returns the file name, within a component's manifests directory, that stores the idx-th rendered kustomization of the named manifest.

func ManifestFileName added in v0.78.0 

func ManifestFileName(manifestName string, idx int) string

ManifestFileName returns the file name, within a component's manifests directory, that stores the idx-th file of the named manifest.

func MarshalPackageDefinition added in v0.84.0 

func MarshalPackageDefinition(definition api.Package) ([]byte, error)

MarshalPackageDefinition returns deterministic zarf.yaml bytes for a package definition.

func WritePackageDefinition added in v0.84.0 

func WritePackageDefinition(path string, definition api.Package) error

WritePackageDefinition writes a deterministic zarf.yaml file for a package definition.

Types

type ChartPaths added in v0.83.0 

type ChartPaths struct {
	// ChartsDir is the directory holding chart tarballs.
	ChartsDir string
	// ValuesDir is the directory holding chart values files.
	ValuesDir string
}

ChartPaths resolves the on-disk locations of a chart's packaged artifacts within a component's charts and values directories.

func (ChartPaths) Archive added in v0.83.0 

func (p ChartPaths) Archive(name, version string) string

Archive returns the full path to the named chart's packaged tarball.

func (ChartPaths) ValuesFile added in v0.83.0 

func (p ChartPaths) ValuesFile(name, version string, idx int) string

ValuesFile returns the full path to the idx-th values file for the named chart.

type ComponentDir 

type ComponentDir string

ComponentDir is the type for the different directories in a component. 

const (
	RepoComponentDir      ComponentDir = "repos"
	FilesComponentDir     ComponentDir = "files"
	ChartsComponentDir    ComponentDir = "charts"
	ManifestsComponentDir ComponentDir = "manifests"
	DataComponentDir      ComponentDir = "data"
	ValuesComponentDir    ComponentDir = "values"
)

Different component directory types.

type NoSBOMAvailableError 

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

NoSBOMAvailableError is returned when a user tries to access a package SBOM, but it is not available

func (*NoSBOMAvailableError) Error 

func (e *NoSBOMAvailableError) Error() string

type PackageLayout 

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

PackageLayout manages the layout for a package.

func LoadFromDir 

func LoadFromDir(ctx context.Context, dirPath string, opts PackageLayoutOptions) (*PackageLayout, error)

LoadFromDir loads and validates a package from the given directory path.

func LoadFromTar 

func LoadFromTar(ctx context.Context, tarPath string, opts PackageLayoutOptions) (*PackageLayout, error)

LoadFromTar unpacks the given archive (any compress/format) and loads it.

func (*PackageLayout) Archive 

func (p *PackageLayout) Archive(ctx context.Context, dirPath string, maxPackageSize int) (string, error)

Archive creates a tarball from the package layout and returns the path to that tarball

func (*PackageLayout) AsV1alpha1 added in v0.84.0 

func (p *PackageLayout) AsV1alpha1() v1alpha1.ZarfPackage

AsV1alpha1 returns the package definition as a v1alpha1 ZarfPackage.

func (*PackageLayout) AsV1beta1 added in v0.84.0 

func (p *PackageLayout) AsV1beta1() v1beta1.Package

AsV1beta1 returns the package definition as a v1beta1 Package.

func (*PackageLayout) Cleanup 

func (p *PackageLayout) Cleanup() error

Cleanup removes any temporary directories created.

func (*PackageLayout) ContainsSBOM 

func (p *PackageLayout) ContainsSBOM() bool

ContainsSBOM checks if a package includes an SBOM

func (*PackageLayout) Definition added in v0.87.0 

func (p *PackageLayout) Definition() api.Package

Definition returns the version-neutral package definition for this layout.

func (*PackageLayout) Digest added in v0.80.0 

func (p *PackageLayout) Digest() string

Digest returns the OCI manifest digest for this package layout.

func (*PackageLayout) DirPath 

func (p *PackageLayout) DirPath() string

DirPath returns base directory of the package layout

func (*PackageLayout) Exists added in v0.80.0 

func (p *PackageLayout) Exists(_ context.Context, target ocispec.Descriptor) (bool, error)

Exists implements oras.ReadOnlyTarget.

func (*PackageLayout) Fetch added in v0.80.0 

func (p *PackageLayout) Fetch(_ context.Context, target ocispec.Descriptor) (io.ReadCloser, error)

Fetch implements oras.ReadOnlyTarget. It serves the manifest, config, or a layer blob identified by the descriptor's digest.

func (*PackageLayout) FileName 

func (p *PackageLayout) FileName() (string, error)

FileName returns the name of the Zarf package should have when exported to the file system

func (*PackageLayout) Files 

func (p *PackageLayout) Files() (map[string]string, error)

Files returns a map of all the files in the package.

func (*PackageLayout) Filter added in v0.87.0 

func (p *PackageLayout) Filter(filter filters.ComponentFilterStrategy) error

Filter applies a component filter to this layout's package definition.

func (*PackageLayout) GetComponentDir 

func (p *PackageLayout) GetComponentDir(ctx context.Context, destPath, componentName string, ct ComponentDir) (_ string, err error)

GetComponentDir returns a path to the directory in the given component.

func (*PackageLayout) GetDocumentation added in v0.68.0 

func (p *PackageLayout) GetDocumentation(ctx context.Context, destPath string, keys []string) (err error)

GetDocumentation extracts documentation files from the package to the given destination path. If keys is empty, all documentation files are extracted. If keys are provided, only those specific documentation files are extracted.

func (*PackageLayout) GetImageDirPath 

func (p *PackageLayout) GetImageDirPath() string

GetImageDirPath returns the path to the images directory

func (*PackageLayout) GetSBOM 

func (p *PackageLayout) GetSBOM(ctx context.Context, destPath string) error

GetSBOM outputs the SBOM data from the package to the given destination path.

func (*PackageLayout) HasImageIndex added in v0.77.0 

func (p *PackageLayout) HasImageIndex() (bool, error)

HasImageIndex reports whether the package layout has a multi-platform image

func (*PackageLayout) HasValuesSchema added in v0.78.0 

func (p *PackageLayout) HasValuesSchema() bool

HasValuesSchema reports whether the package layout contains an assembled values schema file (defined or through import)

func (*PackageLayout) IsPushable added in v0.80.0 

func (p *PackageLayout) IsPushable() bool

IsPushable reports whether this layout has a computed manifest cache and can be used as a push source. A layout with only a registry digest (e.g. from a partial OCI pull via SetRegistryDigest) returns false because the cache is nil.

func (*PackageLayout) IsSigned added in v0.66.0 

func (p *PackageLayout) IsSigned() bool

IsSigned returns true if the package is signed. It first checks the package metadata (Build.Signed), then falls back to checking for the presence of a signature file for backward compatibility.

func (*PackageLayout) Manifest added in v0.83.0 

func (p *PackageLayout) Manifest() (*oci.Manifest, error)

Manifest returns the package's computed OCI manifest for use in zoci functions

func (*PackageLayout) OverrideNamespace added in v0.87.0 

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

OverrideNamespace overrides package namespaces when the package permits it.

func (*PackageLayout) RemoveImages added in v0.87.0 

func (p *PackageLayout) RemoveImages()

RemoveImages removes images and image archives from every component.

func (*PackageLayout) RemoveRepositories added in v0.87.0 

func (p *PackageLayout) RemoveRepositories()

RemoveRepositories removes git repositories from every component.

func (*PackageLayout) Resolve added in v0.80.0 

func (p *PackageLayout) Resolve(_ context.Context, reference string) (ocispec.Descriptor, error)

Resolve implements oras.ReadOnlyTarget. It accepts the manifest digest or the package name as a reference.

func (*PackageLayout) SetAnnotations added in v0.87.0 

func (p *PackageLayout) SetAnnotations(annotations map[string]string)

SetAnnotations updates the package metadata annotations.

func (*PackageLayout) SetChartNamespace added in v0.87.0 

func (p *PackageLayout) SetChartNamespace(componentName, chartName, namespace string)

SetChartNamespace sets the namespace for charts matching the component and chart names.

func (*PackageLayout) SetName added in v0.87.0 

func (p *PackageLayout) SetName(name string)

SetName updates the package metadata name.

func (*PackageLayout) SetRegistryDigest added in v0.80.0 

func (p *PackageLayout) SetRegistryDigest(digest string)

SetRegistryDigest records the manifest digest as resolved from a registry. It replaces the locally-computed digest and clears the manifest cache, since the registry manifest may differ (e.g. partial OCI pulls). After this call the layout is no longer usable as an oras.ReadOnlyTarget for pushing.

func (*PackageLayout) SignPackage 

func (p *PackageLayout) SignPackage(ctx context.Context, opts *signing.SignBlobOptions) (err error)

SignPackage signs the zarf package using cosign with the provided options. A nil value leaves the package unsigned; a non-nil value requests signing.

func (*PackageLayout) TotalSize added in v0.80.0 

func (p *PackageLayout) TotalSize() int64

TotalSize returns the total bytes that would be pushed for this package (all layers + config + manifest). Returns 0 if the manifest has not been computed.

func (*PackageLayout) VerifyPackageSignature added in v0.66.0 

func (p *PackageLayout) VerifyPackageSignature(ctx context.Context, opts signing.VerifyBlobOptions) error

VerifyPackageSignature verifies the package signature

type PackageLayoutOptions 

type PackageLayoutOptions struct {
	// Deprecated: Use VerifyBlobOptions instead. PublicKeyPath validates the create-time signage of a package.
	PublicKeyPath string
	// VerificationStrategy specifies whether verification is enforced
	VerificationStrategy VerificationStrategy
	IsPartial            bool
	Filter               filters.ComponentFilterStrategy
	VerifyBlobOptions    *signing.VerifyBlobOptions
}

PackageLayoutOptions are the options used when loading a package.

type PackagePath added in v0.69.0 

type PackagePath struct {
	ManifestFile string // The manifest file (zarf.yaml or arbitrarily named)
	BaseDir      string // Directory for resolving relative paths
}

PackagePath represents a resolved package definition path

func ResolvePackagePath added in v0.69.0 

func ResolvePackagePath(path string) (PackagePath, error)

ResolvePackagePath takes a user-provided path and resolves it to config file + base dir.

type VerificationStrategy added in v0.69.0 

type VerificationStrategy int

VerificationStrategy describes a strategy for determining whether to verify a package. 

const (
	// VerifyIfPossible will attempt a verification, it will not error if verification
	// data is missing. But it will not stop processing if verification fails.
	VerifyIfPossible VerificationStrategy = iota
	// VerifyAlways will always attempt a verification, and will fail if the
	// verification fails.
	VerifyAlways
	// VerifyNever will skip all verification of a package.
	VerifyNever
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.