Documentation
¶
Overview ¶
Package layout contains functions for interacting with Zarf packages.
Index ¶
- Constants
- Variables
- func AnnotationsFromMetadata(pkg api.Package) map[string]string
- func ChartArchiveName(name, version string) string
- func ChartValuesFileName(name, version string, idx int) string
- func ComponentFileRelPath(idx int, target string) string
- func ComponentSBOMResourcePath(componentName string) string
- func FormatAttachmentFileName(key, file string) string
- func FormatDocumentFileName(key, file string) stringdeprecated
- func GetAttachmentFileNames(attachments map[string]string, keys []string) (map[string]string, error)
- func GetDocumentationFileNames(documentation map[string]string, keys []string) (map[string]string, error)deprecated
- func HasImageIndex(imageDir string) (bool, error)
- func ImageSBOMResourcePath(identifier string) string
- func KustomizationFileName(manifestName string, idx int) string
- func ManifestFileName(manifestName string, idx int) string
- func MarshalPackageDefinition(definition api.Package) ([]byte, error)
- func MaterializeSourceToLayout(ctx context.Context, source, destination string) error
- func NormalizeSBOMFilename(identifier string) string
- func PathWithinDirectory(directory, filename string) (string, error)
- func SBOMImageReferenceSet(pkg api.Package) map[string]struct{}
- func SBOMKeyMatchesResource(kind SBOMResourceKind, identifier, key string, ...) bool
- func UsesGranularResourceLayout(pkg api.Package) bool
- func ValidatePackagePaths(pkg api.Package) error
- func ValidatePathComponent(value string) error
- func WritePackageDefinition(path string, definition api.Package) error
- type ChartPaths
- type ComponentDir
- type NoSBOMAvailableError
- type PackageLayout
- func (p *PackageLayout) Archive(ctx context.Context, dirPath string, maxPackageSize int) (string, error)
- func (p *PackageLayout) AsV1alpha1() v1alpha1.ZarfPackage
- func (p *PackageLayout) AsV1beta1() v1beta1.Package
- func (p *PackageLayout) Cleanup() error
- func (p *PackageLayout) ContainsSBOM() bool
- func (p *PackageLayout) Definition() api.Package
- func (p *PackageLayout) Digest() string
- func (p *PackageLayout) DirPath() string
- func (p *PackageLayout) Exists(_ context.Context, target ocispec.Descriptor) (bool, error)
- func (p *PackageLayout) Fetch(_ context.Context, target ocispec.Descriptor) (io.ReadCloser, error)
- func (p *PackageLayout) FileName() (string, error)
- func (p *PackageLayout) Files() (map[string]string, error)
- func (p *PackageLayout) Filter(filter filters.ComponentFilterStrategy) error
- func (p *PackageLayout) GetAttachments(ctx context.Context, destPath string, keys []string) (err error)
- func (p *PackageLayout) GetComponentDir(ctx context.Context, destPath, componentName string, ct ComponentDir) (_ string, err error)
- func (p *PackageLayout) GetDocumentation(ctx context.Context, destPath string, keys []string) errordeprecated
- func (p *PackageLayout) GetImageDirPath() string
- func (p *PackageLayout) GetSBOM(ctx context.Context, destPath string, keys []string) (err error)
- func (p *PackageLayout) HasImageIndex() (bool, error)
- func (p *PackageLayout) HasValuesSchema() bool
- func (p *PackageLayout) IsPushable() bool
- func (p *PackageLayout) IsSigned() bool
- func (p *PackageLayout) Manifest() (*oci.Manifest, error)
- func (p *PackageLayout) OverrideNamespace(namespace string) error
- func (p *PackageLayout) RemoveImages()
- func (p *PackageLayout) RemoveRepositories()
- func (p *PackageLayout) Resolve(_ context.Context, reference string) (ocispec.Descriptor, error)
- func (p *PackageLayout) SetAnnotations(annotations map[string]string)
- func (p *PackageLayout) SetChartNamespace(componentName, chartName, namespace string)
- func (p *PackageLayout) SetName(name string)
- func (p *PackageLayout) SetRegistryDigest(digest string)
- func (p *PackageLayout) SignPackage(ctx context.Context, opts *signing.SignBlobOptions) (err error)
- func (p *PackageLayout) TotalSize() int64
- func (p *PackageLayout) VerifyPackageSignature(ctx context.Context, opts signing.VerifyBlobOptions) error
- type PackageLayoutOptions
- type PackagePath
- type SBOMResourceKind
- type VerificationStrategy
Constants ¶
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" // AttachmentsDir contains individually-addressable attachment resources in v1beta1 and later packages. AttachmentsDir = "attachments" DocumentationTar = "documentation.tar" IndexJSON = "index.json" OCILayout = "oci-layout" )
Constants used in the default package layout.
const ( // ZarfLayerMediaTypeBlob is the media type for all Zarf package layer blobs. ZarfLayerMediaTypeBlob = "application/vnd.zarf.layer.v1.blob" // AttachmentLayerMediaTypeBlob is the media type for a granular attachment resource layer. AttachmentLayerMediaTypeBlob = "application/vnd.zarf.attachment.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" // ResourceKindAnnotation identifies the kind of a granular package resource. ResourceKindAnnotation = "dev.zarf.resource.kind" // ResourceKindAttachment identifies an attachment resource. ResourceKindAttachment = "attachment" // ResourceKindSBOM identifies an SBOM resource. ResourceKindSBOM = "sbom" // OCITimestampFormat is the format used for the OCI timestamp annotation OCITimestampFormat = time.RFC3339 )
const ( // SBOMResourcesDir contains individually-addressable SBOM resources in v1beta1 packages. SBOMResourcesDir = "sboms" // SBOMMediaTypeSyftJSON identifies an SBOM encoded in Syft's JSON format. SBOMMediaTypeSyftJSON = "application/vnd.syft+json" )
Variables ¶
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) )
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
AnnotationsFromMetadata extracts OCI manifest annotations from a package definition.
func ChartArchiveName ¶ added in v0.83.0
ChartArchiveName returns the file name of a chart's packaged tarball, within a component's charts directory.
func ChartValuesFileName ¶ added in v0.83.0
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
ComponentFileRelPath returns the path, relative to a component's files directory, where the idx-th file's contents are stored.
func ComponentSBOMResourcePath ¶ added in v0.89.0
ComponentSBOMResourcePath returns the v1beta1 package-relative path for a component SBOM.
func FormatAttachmentFileName ¶ added in v0.89.0
FormatAttachmentFileName returns the stored filename for an attachment whose basename collides with another attachment.
func FormatDocumentFileName
deprecated
added in
v0.68.0
func GetAttachmentFileNames ¶ added in v0.89.0
func GetAttachmentFileNames(attachments map[string]string, keys []string) (map[string]string, error)
GetAttachmentFileNames returns validated stored filenames for the requested attachment keys. Filenames are deconflicted before selection: if multiple keys have the same basename, they are prefixed with the key.
func GetDocumentationFileNames
deprecated
added in
v0.68.0
func HasImageIndex ¶ added in v0.83.0
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 ImageSBOMResourcePath ¶ added in v0.89.0
ImageSBOMResourcePath returns the v1beta1 package-relative path for an image SBOM.
func KustomizationFileName ¶ added in v0.78.0
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
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
MarshalPackageDefinition returns deterministic zarf.yaml bytes for a package definition.
func MaterializeSourceToLayout ¶ added in v0.88.0
MaterializeSourceToLayout resolves symbolic links from a local package source and writes the resulting regular files and directories to destination in package staging.
Use it for every local path selected by a package definition before that content enters package staging. Callers must provide a destination already validated as being within staging. Do not use it for generated, downloaded, or archive-extracted content.
func NormalizeSBOMFilename ¶ added in v0.89.0
NormalizeSBOMFilename returns the filename used for archive-backed SBOMs.
func PathWithinDirectory ¶ added in v0.88.0
PathWithinDirectory resolves filename under directory and rejects paths that escape it.
func SBOMImageReferenceSet ¶ added in v0.89.0
SBOMImageReferenceSet returns the image references declared by the package.
func SBOMKeyMatchesResource ¶ added in v0.89.0
func SBOMKeyMatchesResource(kind SBOMResourceKind, identifier, key string, imageReferences map[string]struct{}) bool
SBOMKeyMatchesResource reports whether a requested key selects an SBOM resource.
func UsesGranularResourceLayout ¶ added in v0.89.0
UsesGranularResourceLayout reports whether a package stores documentation and SBOMs as individual files. v1alpha1, including definitions that omit apiVersion, retains archive-backed resources.
func ValidatePackagePaths ¶ added in v0.88.0
ValidatePackagePaths checks that package config fields used as filesystem path components do not contain path traversal sequences or separators.
func ValidatePathComponent ¶ added in v0.88.0
ValidatePathComponent ensures a package-derived value is safe to use in an internal path.
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) ArchivePath ¶ added in v0.88.0
func (p ChartPaths) ArchivePath(name, version string) (string, error)
ArchivePath returns the contained path for a chart archive.
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.
func (ChartPaths) ValuesFilePath ¶ added in v0.88.0
func (p ChartPaths) ValuesFilePath(name, version string, idx int) (string, error)
ValuesFilePath returns the contained path for a packaged chart values file.
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) GetAttachments ¶ added in v0.89.0
func (p *PackageLayout) GetAttachments(ctx context.Context, destPath string, keys []string) (err error)
GetAttachments extracts attachment files (documentation in v1alpha1) to the given destination path. If keys is empty, all attachments are extracted. If keys are provided, only those specific attachments are extracted.
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
deprecated
added in
v0.68.0
func (*PackageLayout) GetImageDirPath ¶
func (p *PackageLayout) GetImageDirPath() string
GetImageDirPath returns the path to the images directory
func (*PackageLayout) GetSBOM ¶
GetSBOM outputs selected SBOM data from the package to the given destination path. An empty key set outputs every SBOM.
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 SBOMResourceKind ¶ added in v0.89.0
type SBOMResourceKind string
SBOMResourceKind identifies the source represented by an SBOM resource.
const ( // SBOMResourceComponent identifies an SBOM generated from component files. SBOMResourceComponent SBOMResourceKind = "component" // SBOMResourceImage identifies an SBOM generated from an image. SBOMResourceImage SBOMResourceKind = "image" )
func ParseSBOMResourcePath ¶ added in v0.89.0
func ParseSBOMResourcePath(resourcePath string) (SBOMResourceKind, string, bool)
ParseSBOMResourcePath returns the kind and identifier encoded in a v1beta1 SBOM resource path.
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 )