layout

package
v0.29.0 Latest Latest
Warning

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

 Go to latest Published: Oct 2, 2026 License: Apache-2.0 Imports: 36 Imported by: 0

Documentation

Overview

Package layout is used to defining the distro package files

Index

Constants

View Source 
const (
	// CargoshipLayerMediaTypeBlob is the media type for all Cargoship package layer blobs.
	CargoshipLayerMediaTypeBlob = "application/vnd.cargoship.layer.v1.blob"
	// CargoshipConfigMediaType is the media type for the Cargoship package manifest config.
	CargoshipConfigMediaType = "application/vnd.cargoship.config.v1+json"
	// OCITimestampFormat is the format used for the OCI timestamp annotation
	OCITimestampFormat = time.RFC3339
)

Variables

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 

func AnnotationsFromMetadata(metadata distro.ZarfDistroMetadata) map[string]string

AnnotationsFromMetadata extracts OCI manifest annotations from Zarf package metadata.

func IsCleanPath 

func IsCleanPath(s string) bool

IsCleanPath returns true if s is safe to embed in a file path: it must not be ".." and must not contain path separators.

func IsContainedPath 

func IsContainedPath(s string) bool

IsContainedPath returns true if s is a relative path that stays inside the directory it is resolved against. Unlike IsCleanPath it allows separators, since the paths it guards name files in nested package directories.

func LoadValues 

func LoadValues(ctx context.Context, dirPath string, vals distro.ZarfDistroValues, overrides ...map[string]any) (map[string]any, error)

LoadValues merges the values files a package ships with, in order, then the given overrides, and checks the result against the package's values schema.

The file paths are taken from the package's own distro.yaml, so they are resolved against dirPath and validated by validateDistroPaths before they get here. Overrides come from outside the package - a cluster inventory, say - so they are merged before the schema check, not after: an override that breaks the schema has to fail as loudly as a bad values file would.

Types

type ClusterPath 

type ClusterPath struct {
	ManifestFile string
	BaseDir      string
}

ClusterPath object that contains the manifest file and base directory

func ResolveClusterPath 

func ResolveClusterPath(path string) (ClusterPath, error)

ResolveClusterPath returns an object of ClusterPath from a given path

type Distro 

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

Distro struct

func New 

func New(cfg *types.DistroConfig) (*Distro, error)

New creates a new Distro object

type DistroLayout 

type DistroLayout struct {
	Distro distro.ZarfDistro
	// contains filtered or unexported fields
}

DistroLayout struct

func LoadFromDir 

func LoadFromDir(ctx context.Context, dirPath string, opts DistroLayoutOptions) (*DistroLayout, error)

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

func LoadFromTar 

func LoadFromTar(ctx context.Context, tarPath string, opts DistroLayoutOptions) (*DistroLayout, error)

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

func NewDistroLayout 

func NewDistroLayout(dir string, distro v1alpha1.ZarfDistro) *DistroLayout

NewDistroLayout returns an DistroLayout object

func (*DistroLayout) ApplyValues 

func (d *DistroLayout) ApplyValues(values map[string]any) error

ApplyValues projects the resolved values onto the package's engine configuration: it renders the templates the configuration contains, then follows the mappings the package declares.

The engine configuration is what the package ships; templates and mappings decide which parts of it a cluster is allowed to move. A mapping moves one leaf and is the right tool when that is all a knob does; a template can also decide whether a block is written at all. Doing both here, once, keeps every phase reading a single already-resolved engine configuration, and puts the result ahead of the install-time check that drops engine config keys the distro version does not recognize.

Rendering happens before the mappings, not after, so that the text being executed is the text the package author wrote. A value that arrives from a cluster inventory and happens to contain "{{" is written through as the characters it is.

func (*DistroLayout) Archive 

func (d *DistroLayout) Archive(ctx context.Context, dirPath string, _ int) (string, error)

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

func (*DistroLayout) Cleanup 

func (d *DistroLayout) Cleanup() error

Cleanup removes any temporary directories created.

func (*DistroLayout) Digest 

func (d *DistroLayout) Digest() string

Digest returns the OCI manifest digest for this package layout.

func (*DistroLayout) DirPath 

func (d *DistroLayout) DirPath() string

DirPath returns dirPath

func (*DistroLayout) Exists 

func (d *DistroLayout) Exists(_ context.Context, target ocispec.Descriptor) (bool, error)

Exists implements oras.ReadOnlyTarget.

func (*DistroLayout) Fetch 

func (d *DistroLayout) 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 (*DistroLayout) FileName 

func (d *DistroLayout) FileName() (string, error)

FileName returns the name of the Zarf package should have when exported to the file system. A package targeting several architectures takes multi in the architecture position, since no single architecture describes what it carries.

func (*DistroLayout) Files 

func (d *DistroLayout) Files() (map[string]string, error)

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

func (*DistroLayout) GetImageDirPath 

func (d *DistroLayout) GetImageDirPath() string

GetImageDirPath returns the path to where the image tar balls should be stored in

func (*DistroLayout) IsPushable 

func (d *DistroLayout) 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 (*DistroLayout) IsSigned 

func (d *DistroLayout) 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 (*DistroLayout) RenderFiles 

func (d *DistroLayout) RenderFiles(ctx context.Context, values map[string]any) error

RenderFiles renders, in place in the extracted package, the contents of every file the package marked as a template.

Doing it here rather than inside an upload phase keeps it to a single pass. The package is extracted and its checksums verified by the time a caller has a DistroLayout, and both the generic upload phase and the per-profile one read these same staged paths afterwards. Writing the result back over the staged file also keeps each file at the index it was packaged under, which is the directory name those phases rebuild the path from.

Templating is opt-in per file because most of what a package ships is a tarball or an RPM, and a template pass over one of those would either corrupt it or fail on a brace that happens to appear in the middle of a binary.

func (*DistroLayout) Resolve 

func (d *DistroLayout) 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 (*DistroLayout) SetRegistryDigest 

func (d *DistroLayout) 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 (*DistroLayout) SignPackage 

func (d *DistroLayout) SignPackage(ctx context.Context, opts signing.SignBlobOptions) (err error)

SignPackage signs the zarf package using cosign with the provided options. If the options do not indicate signing should be performed (no key material configured), this is a no-op and returns nil.

func (*DistroLayout) TotalSize 

func (d *DistroLayout) 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 (*DistroLayout) Values 

func (d *DistroLayout) Values(ctx context.Context, overrides ...map[string]any) (map[string]any, error)

Values returns the merged, schema-checked values the package was built with, with any overrides applied on top.

func (*DistroLayout) VerifyPackageSignature 

func (d *DistroLayout) VerifyPackageSignature(ctx context.Context, opts signing.VerifyBlobOptions) error

VerifyPackageSignature verifies the package signature

type DistroLayoutOptions 

type DistroLayoutOptions struct {
	VerifyBlobOptions *signing.VerifyBlobOptions
	// VerificationStrategy specifies whether verification is enforced
	VerificationStrategy VerificationStrategy
}

DistroLayoutOptions struct

type DistroPath 

type DistroPath struct {
	ManifestFile string
	BaseDir      string
}

DistroPath object that contains the manifest file and base directory

func ResolveDistroPath 

func ResolveDistroPath(path string) (DistroPath, error)

ResolveDistroPath returns an object of DistroPath from a given path

type VerificationStrategy 

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.