From bc2a00147bc830e1eaafbe9578ff102b30cf6dd2 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Wed, 4 Mar 2026 12:59:12 -0500 Subject: [PATCH 01/26] update for v1beta1 Signed-off-by: Austin Abro --- src/api/internal/v1beta1/component.go | 199 +++++++++------- src/api/internal/v1beta1/package.go | 44 ++-- src/api/internal/v1beta1/package_test.go | 38 ++-- src/api/internal/v1beta1/translate.go | 116 ---------- src/api/internal/v1beta1/translate_test.go | 251 --------------------- 5 files changed, 168 insertions(+), 480 deletions(-) delete mode 100644 src/api/internal/v1beta1/translate.go delete mode 100644 src/api/internal/v1beta1/translate_test.go diff --git a/src/api/internal/v1beta1/component.go b/src/api/internal/v1beta1/component.go index 75f69cfded..d04ac2662a 100644 --- a/src/api/internal/v1beta1/component.go +++ b/src/api/internal/v1beta1/component.go @@ -15,53 +15,38 @@ type ZarfComponent struct { // Message to include during package deploy describing the purpose of this component. Description string `json:"description,omitempty"` - // Determines the default Y/N state for installing this component on package deploy. - Default bool `json:"default,omitempty"` - - // Do not prompt user to install this component. (Defaults to false) + // Do not prompt user to install this component. Defaults to false, meaning the component is required. Optional *bool `json:"optional,omitempty"` // Filter when this component is included in package creation or deployment. Only ZarfComponentOnlyTarget `json:"only,omitempty"` - // Import a component from another Zarf package. + // Import a component from another Zarf component config. Import ZarfComponentImport `json:"import,omitempty"` + // Features of the Zarf CLI to enable for this component. + Features ZarfComponentFeatures `json:"features,omitempty"` + // Kubernetes manifests to be included in a generated Helm chart on package deploy. Manifests []ZarfManifest `json:"manifests,omitempty"` // Helm charts to install during package deploy. Charts []ZarfChart `json:"charts,omitempty"` - // Datasets to inject into a container in the target cluster. - DataInjections []ZarfDataInjection `json:"dataInjections,omitempty"` - // Files or folders to place on disk during package deployment. Files []ZarfFile `json:"files,omitempty"` // List of OCI images to include in the package. - Images []string `json:"images,omitempty"` + Images []ZarfImage `json:"images,omitempty"` + + // List of tar archives of images to include in the package. + ImageArchives []ImageArchive `json:"imageArchives,omitempty"` // List of git repos to include in the package. Repos []string `json:"repos,omitempty"` // Custom commands to run at various stages of a package lifecycle. Actions ZarfComponentActions `json:"actions,omitempty"` - - // List of resources to health check after deployment - HealthChecks []NamespacedObjectKindReference `json:"healthChecks,omitempty"` -} - -// NamespacedObjectKindReference is a reference to a specific resource in a namespace using its kind and API version. -type NamespacedObjectKindReference struct { - // API Version of the resource - APIVersion string `json:"apiVersion"` - // Kind of the resource - Kind string `json:"kind"` - // Namespace of the resource - Namespace string `json:"namespace"` - // Name of the resource - Name string `json:"name"` } // RequiresCluster returns if the component requires a cluster connection to deploy. @@ -70,9 +55,8 @@ func (c ZarfComponent) RequiresCluster() bool { hasCharts := len(c.Charts) > 0 hasManifests := len(c.Manifests) > 0 hasRepos := len(c.Repos) > 0 - hasDataInjections := len(c.DataInjections) > 0 - if hasImages || hasCharts || hasManifests || hasRepos || hasDataInjections { + if hasImages || hasCharts || hasManifests || hasRepos { return true } @@ -125,34 +109,56 @@ type ZarfFile struct { type ZarfChart struct { // The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repo. Name string `json:"name"` - // The Helm repo where the chart is stored - Helm HelmRepoSource `json:"helm,omitempty"` - // The Git repo where the chart is stored + // The version of the chart. This field is not part of the v1beta1 schema but is kept + // as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1. + version string + // The Helm repo where the chart is stored. + HelmRepo HelmRepoSource `json:"helmRepo,omitempty"` + // The Git repo where the chart is stored. Git GitRepoSource `json:"git,omitempty"` - // The local path where the chart is stored + // The local path where the chart is stored. Local LocalRepoSource `json:"local,omitempty"` - // The OCI registry where the chart is stored + // The OCI registry where the chart is stored. OCI OCISource `json:"oci,omitempty"` - // The version of the chart to deploy; for git-based charts this is also the tag of the git repo by default (when not using the '@' syntax for 'repos'). - Version string `json:"version,omitempty"` // The namespace to deploy the chart to. Namespace string `json:"namespace,omitempty"` // The name of the Helm release to create (defaults to the Zarf name of the chart). ReleaseName string `json:"releaseName,omitempty"` - // Whether to not wait for chart resources to be ready before continuing. + // Whether to wait for chart resources to be ready before continuing. Defaults to true. Wait *bool `json:"wait,omitempty"` // List of local values file paths or remote URLs to include in the package; these will be merged together when deployed. ValuesFiles []string `json:"valuesFiles,omitempty"` - // [alpha] List of variables to set in the Helm chart. - Variables []ZarfChartVariable `json:"variables,omitempty"` + // List of values sources to their Helm override target. + Values []ZarfChartValue `json:"values,omitempty"` +} + +// SetDeprecatedVersion gets the version of the chart, used as a backwards compatibility shim with v1alpha1. +func (c ZarfChart) GetDeprecatedVersion() string { + return c.version +} + +// SetDeprecatedVersion sets the version of the chart, used as a backwards compatibility shim with v1alpha1. +// This function will be deleted when v1alpha1 packages are no longer deployable +func (c *ZarfChart) SetDeprecatedVersion(version string) { + c.version = version +} + +// ZarfChartValue maps a values source path to a Helm chart target path. +type ZarfChartValue struct { + // The source path for the value. + SourcePath string `json:"sourcePath"` + // The target path within the Helm chart values. + TargetPath string `json:"targetPath"` } // HelmRepoSource represents a Helm chart stored in a Helm repository. type HelmRepoSource struct { // The name of a chart within a Helm repository (defaults to the Zarf name of the chart). - RepoName string `json:"repoName,omitempty"` + Name string `json:"name,omitempty"` // The URL of the chart repository where the helm chart is stored. URL string `json:"url"` + // The version of the chart to deploy. + Version string `json:"version"` } // GitRepoSource represents a Helm chart stored in a Git repository. @@ -166,23 +172,15 @@ type GitRepoSource struct { // LocalRepoSource represents a Helm chart stored locally. type LocalRepoSource struct { // The path to a local chart's folder or .tgz archive. - Path string `json:"path,omitempty"` + Path string `json:"path"` } // OCISource represents a Helm chart stored in an OCI registry. type OCISource struct { // The URL of the OCI registry where the helm chart is stored. URL string `json:"url"` -} - -// ZarfChartVariable represents a variable that can be set for a Helm chart overrides. -type ZarfChartVariable struct { - // The name of the variable. - Name string `json:"name" jsonschema:"pattern=^[A-Z0-9_]+$"` - // A brief description of what the variable controls. - Description string `json:"description"` - // The path within the Helm chart values where this variable applies. - Path string `json:"path"` + // The version of the chart to deploy. + Version string `json:"version"` } // ZarfManifest defines raw manifests Zarf will deploy as a helm chart. @@ -197,10 +195,50 @@ type ZarfManifest struct { KustomizeAllowAnyDirectory bool `json:"kustomizeAllowAnyDirectory,omitempty"` // List of local kustomization paths or remote URLs to include in the package. Kustomizations []string `json:"kustomizations,omitempty"` - // Whether to not wait for manifest resources to be ready before continuing. (Defaults to true) + // Whether to wait for manifest resources to be ready before continuing. Defaults to true. Wait *bool `json:"wait,omitempty"` } +// ZarfImage defines an OCI image to include in the package. +type ZarfImage struct { + // The image reference. + Name string `json:"name"` + // The source to pull the image from. Defaults to "registry". + Source string `json:"source,omitempty" jsonschema:"enum=registry,enum=daemon"` +} + +// ImageArchive defines a tar archive of images to include in the package. +type ImageArchive struct { + // The path to the tar archive. + Path string `json:"path"` + // The list of images contained in the archive. + Images []string `json:"images"` +} + +// ZarfComponentFeatures defines features of the Zarf CLI to enable for a component. +type ZarfComponentFeatures struct { + // Whether this component provides a registry. + IsRegistry bool `json:"isRegistry,omitempty"` + // Injector configuration for the component. + Injector *Injector `json:"injector,omitempty"` + // Whether this component provides an agent. + IsAgent bool `json:"isAgent,omitempty"` +} + +// Injector defines the configuration for the Zarf injector. +type Injector struct { + // Whether the injector is enabled. + Enabled bool `json:"enabled"` + // Values for the injector. + Values *InjectorValues `json:"values,omitempty"` +} + +// InjectorValues defines configurable values for the Zarf injector. +type InjectorValues struct { + // Tolerations for the injector pod. + Tolerations string `json:"tolerations,omitempty"` +} + // ZarfComponentActions are ActionSets that map to different zarf package operations. type ZarfComponentActions struct { // Actions to run during package creation. @@ -219,8 +257,6 @@ type ZarfComponentActionSet struct { Before []ZarfComponentAction `json:"before,omitempty"` // Actions to run at the end of an operation. After []ZarfComponentAction `json:"after,omitempty"` - // Actions to run if all operations succeed. - OnSuccess []ZarfComponentAction `json:"onSuccess,omitempty"` // Actions to run if all operations fail. OnFailure []ZarfComponentAction `json:"onFailure,omitempty"` } @@ -229,7 +265,7 @@ type ZarfComponentActionSet struct { type ZarfComponentActionDefaults struct { // Hide the output of commands during execution (default false). Mute bool `json:"mute,omitempty"` - // Default timeout in seconds for commands (default no timeout). + // Default timeout for commands (default no timeout). Timeout *metav1.Duration `json:"timeout,omitempty"` // Retry commands given number of times if they fail (default 0). Retries int `json:"retries,omitempty"` @@ -245,7 +281,7 @@ type ZarfComponentActionDefaults struct { type ZarfComponentAction struct { // Hide the output of the command during package deployment (default false). Mute *bool `json:"mute,omitempty"` - // Timeout in seconds for the command (default to 0, no timeout for cmd actions and 5 minutes for wait actions). + // Timeout for the command (default to 0, no timeout for cmd actions and 5 minutes for wait actions). Timeout *metav1.Duration `json:"timeout,omitempty"` // Retry the command if it fails up to given number of times (default 0). Retries int `json:"retries,omitempty"` @@ -259,12 +295,37 @@ type ZarfComponentAction struct { Shell *Shell `json:"shell,omitempty"` // (onDeploy/cmd only) An array of variables to update with the output of the command. These variables will be available to all remaining actions and components in the package. SetVariables []Variable `json:"setVariables,omitempty"` + // An array of values to set with the output of the command. + SetValues []SetValue `json:"setValues,omitempty"` // Description of the action to be displayed during package execution instead of the command. Description string `json:"description,omitempty"` // Wait for a condition to be met before continuing. Must specify either cmd or wait for the action. See the 'zarf tools wait-for' command for more info. Wait *ZarfComponentActionWait `json:"wait,omitempty"` } +// SetValueType declares the expected input back from the cmd, allowing structured data to be parsed. +type SetValueType string + +// SetValueYAML enables YAML parsing. +var SetValueYAML = SetValueType("yaml") + +// SetValueJSON enables JSON parsing. +var SetValueJSON = SetValueType("json") + +// SetValueString sets the raw value. +var SetValueString = SetValueType("string") + +// SetValue declares a value that can be set during a package deploy. +type SetValue struct { + // Key represents which value to assign to. + Key string `json:"key,omitempty"` + // Value is the current value at the key. + Value any `json:"value,omitempty"` + // Type declares the kind of data being stored in the value. JSON and YAML types ensure proper formatting when + // inserting the value into the template. Defaults to SetValueString behavior when empty. + Type SetValueType `json:"type,omitempty"` +} + // ZarfComponentActionWait specifies a condition to wait for before continuing type ZarfComponentActionWait struct { // Wait for a condition to be met in the cluster before continuing. Only one of cluster or network can be specified. @@ -281,8 +342,8 @@ type ZarfComponentActionWaitCluster struct { Name string `json:"name" jsonschema:"example=podinfo,example=app=podinfo"` // The namespace of the resource to wait for. Namespace string `json:"namespace,omitempty"` - // The condition or jsonpath state to wait for; defaults to exist, a special condition that will wait for the resource to exist. - Condition string `json:"condition,omitempty" jsonschema:"example=Ready,example=Available,'{.status.availableReplicas}'=23"` + // The condition or jsonpath state to wait for; defaults to kstatus readiness checks. + Condition string `json:"condition,omitempty" jsonschema:"example=Available,'{.status.availableReplicas}'=23"` } // ZarfComponentActionWaitNetwork specifies a condition to wait for before continuing @@ -295,35 +356,11 @@ type ZarfComponentActionWaitNetwork struct { Code int `json:"code,omitempty" jsonschema:"example=200,example=404"` } -// ZarfContainerTarget defines the destination info for a ZarfData target -type ZarfContainerTarget struct { - // The namespace to target for data injection. - Namespace string `json:"namespace"` - // The K8s selector to target for data injection. - Selector string `json:"selector" jsonschema:"example=app=data-injection"` - // The container name to target for data injection. - Container string `json:"container"` - // The path within the container to copy the data into. - Path string `json:"path"` -} - -// ZarfDataInjection is a data-injection definition. -type ZarfDataInjection struct { - // Either a path to a local folder/file or a remote URL of a file to inject into the given target pod + container. - Source string `json:"source"` - // The target pod + container to inject the data into. - Target ZarfContainerTarget `json:"target"` - // Compress the data before transmitting using gzip. Note: this requires support for tar/gzip locally and in the target image. - Compress bool `json:"compress,omitempty"` -} - // ZarfComponentImport structure for including imported Zarf components. type ZarfComponentImport struct { - // The name of the component to import from the referenced zarf.yaml. - Name string `json:"name,omitempty"` - // The path to the directory containing the zarf.yaml to import. + // The path to the component config file to import. Path string `json:"path,omitempty"` - // [beta] The URL to a Zarf package to import via OCI. + // The URL to a Zarf component config to import via OCI. URL string `json:"url,omitempty" jsonschema:"pattern=^oci://.*$"` } diff --git a/src/api/internal/v1beta1/package.go b/src/api/internal/v1beta1/package.go index 51c350726f..5c61033ae6 100644 --- a/src/api/internal/v1beta1/package.go +++ b/src/api/internal/v1beta1/package.go @@ -47,11 +47,15 @@ type ZarfPackage struct { // Zarf-generated package build data. Build ZarfBuildData `json:"build,omitempty"` // List of components to deploy in this package. - Components []ZarfComponent `json:"components" jsonschema:"minItems=1"` + Components []ZarfComponent `json:"components"` // Constant template values applied on deploy for K8s resources. Constants []Constant `json:"constants,omitempty"` // Variable template values applied on deploy for K8s resources. Variables []InteractiveVariable `json:"variables,omitempty"` + // Values imports Zarf values files for templating. + Values ZarfValues `json:"values,omitempty"` + // Documentation files. + Documentation map[string]string `json:"documentation,omitempty"` } // IsInitConfig returns whether a Zarf package is an init config. @@ -69,10 +73,10 @@ func (pkg ZarfPackage) HasImages() bool { return false } -// IsSBOMAble checks if a package has contents that an SBOM can be created on (i.e. images, files, or data injections). +// IsSBOMAble checks if a package has contents that an SBOM can be created on (i.e. images, files, or image archives). func (pkg ZarfPackage) IsSBOMAble() bool { for _, c := range pkg.Components { - if len(c.Images) > 0 || len(c.Files) > 0 || len(c.DataInjections) > 0 { + if len(c.Images) > 0 || len(c.Files) > 0 || len(c.ImageArchives) > 0 { return true } } @@ -137,22 +141,22 @@ func (c Constant) Validate() error { type ZarfMetadata struct { // Name to identify this Zarf package. Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"` + // Additional information about this Zarf package. + Description string `json:"description,omitempty"` // Generic string set by a package author to track the package version (Note: ZarfInitConfigs will always be versioned to the CLIVersion they were created with). Version string `json:"version,omitempty"` // Disable compression of this package. Uncompressed bool `json:"uncompressed,omitempty"` // The target cluster architecture for this package. Architecture string `json:"architecture,omitempty" jsonschema:"example=arm64,example=amd64"` - // Default to true, when false components cannot have images or git repos as they will be pulled from the internet - Airgap *bool `json:"airgap,omitempty"` // Annotations are key-value pairs that can be used to store metadata about the package. Annotations map[string]string `json:"annotations,omitempty"` + // Whether to allow namespace overrides for this package. + AllowNamespaceOverride bool `json:"allowNamespaceOverride,omitempty"` } // ZarfBuildData is written during the packager.Create() operation to track details of the created package. type ZarfBuildData struct { - // Checksum of a checksums.txt file that contains checksums all the layers within the package. - AggregateChecksum string `json:"aggregateChecksum,omitempty"` // The machine name that created this package. Terminal string `json:"terminal,omitempty"` // The username who created this package. @@ -169,12 +173,26 @@ type ZarfBuildData struct { RegistryOverrides map[string]string `json:"registryOverrides,omitempty"` // Whether this package was created with differential components. Differential bool `json:"differential,omitempty"` - // Version of a previously built package used as the basis for creating this differential package. - DifferentialPackageVersion string `json:"differentialPackageVersion,omitempty"` - // List of components that were not included in this package due to differential packaging. - DifferentialMissing []string `json:"differentialMissing,omitempty"` - // The minimum version of Zarf that does not have breaking package structure changes. - LastNonBreakingVersion string `json:"lastNonBreakingVersion,omitempty"` // The flavor of Zarf used to build this package. Flavor string `json:"flavor,omitempty"` + // Checksum of a checksums.txt file that contains checksums all the layers within the package. + AggregateChecksum string `json:"aggregateChecksum,omitempty"` + // Requirements for specific Zarf versions needed to deploy this package. + VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"` +} + +// VersionRequirement specifies a minimum Zarf version needed and the reason for the requirement. +type VersionRequirement struct { + // The minimum version of Zarf required. + Version string `json:"version"` + // The reason this version is required. + Reason string `json:"reason"` +} + +// ZarfValues defines values files and schema for templating and overriding Helm values. +type ZarfValues struct { + // List of values file paths to include. + Files []string `json:"files,omitempty"` + // Path to a JSON schema file for validating values. + Schema string `json:"schema,omitempty"` } diff --git a/src/api/internal/v1beta1/package_test.go b/src/api/internal/v1beta1/package_test.go index 69e7d0ba00..2ee1faa0fb 100644 --- a/src/api/internal/v1beta1/package_test.go +++ b/src/api/internal/v1beta1/package_test.go @@ -37,7 +37,7 @@ func TestZarfPackageHasImages(t *testing.T) { Components: []ZarfComponent{ { Name: "with images", - Images: []string{"docker.io/library/alpine:latest"}, + Images: []ZarfImage{{Name: "docker.io/library/alpine:latest"}}, }, }, } @@ -48,11 +48,11 @@ func TestZarfPackageIsSBOMable(t *testing.T) { t.Parallel() tests := []struct { - name string - images []string - files []ZarfFile - dataInjections []ZarfDataInjection - expected bool + name string + images []ZarfImage + files []ZarfFile + imageArchives []ImageArchive + expected bool }{ { name: "empty component", @@ -60,7 +60,7 @@ func TestZarfPackageIsSBOMable(t *testing.T) { }, { name: "only images", - images: []string{""}, + images: []ZarfImage{{Name: "alpine"}}, expected: true, }, { @@ -69,16 +69,16 @@ func TestZarfPackageIsSBOMable(t *testing.T) { expected: true, }, { - name: "only data injections", - dataInjections: []ZarfDataInjection{{}}, - expected: true, + name: "only image archives", + imageArchives: []ImageArchive{{Path: "archive.tar", Images: []string{"img"}}}, + expected: true, }, { - name: "all three set", - images: []string{""}, - files: []ZarfFile{{}}, - dataInjections: []ZarfDataInjection{{}}, - expected: true, + name: "all three set", + images: []ZarfImage{{Name: "alpine"}}, + files: []ZarfFile{{}}, + imageArchives: []ImageArchive{{Path: "archive.tar", Images: []string{"img"}}}, + expected: true, }, } for _, tt := range tests { @@ -88,10 +88,10 @@ func TestZarfPackageIsSBOMable(t *testing.T) { pkg := ZarfPackage{ Components: []ZarfComponent{ { - Name: "without images", - Images: tt.images, - Files: tt.files, - DataInjections: tt.dataInjections, + Name: "test-component", + Images: tt.images, + Files: tt.files, + ImageArchives: tt.imageArchives, }, }, } diff --git a/src/api/internal/v1beta1/translate.go b/src/api/internal/v1beta1/translate.go deleted file mode 100644 index c14da3649e..0000000000 --- a/src/api/internal/v1beta1/translate.go +++ /dev/null @@ -1,116 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 -// SPDX-FileCopyrightText: 2021-Present The Zarf Authors - -package v1beta1 - -import ( - "encoding/json" - "fmt" - "strings" - "time" - - "github.com/defenseunicorns/pkg/helpers/v2" - "github.com/zarf-dev/zarf/src/api/v1alpha1" - v1 "k8s.io/apimachinery/pkg/apis/meta/v1" -) - -// TranslateAlphaPackage translates a v1alpha1.ZarfPackage to a v1beta1.ZarfPackage -func TranslateAlphaPackage(alphaPkg v1alpha1.ZarfPackage) (ZarfPackage, error) { - var betaPkg ZarfPackage - - // This will set all the fields that are common between v1alpha1 and v1beta1 - jsonData, err := json.Marshal(alphaPkg) - if err != nil { - return ZarfPackage{}, fmt.Errorf("failed to marshal v1alpha1 object: %w", err) - } - - err = json.Unmarshal(jsonData, &betaPkg) - if err != nil { - return ZarfPackage{}, fmt.Errorf("failed to unmarshal JSON to v1beta1 object: %w", err) - } - - betaPkg.APIVersion = APIVersion - - betaPkg.Metadata.Annotations = make(map[string]string) - if alphaPkg.Metadata.Description != "" { - betaPkg.Metadata.Annotations["description"] = alphaPkg.Metadata.Description - } - if alphaPkg.Metadata.URL != "" { - betaPkg.Metadata.Annotations["url"] = alphaPkg.Metadata.URL - } - if alphaPkg.Metadata.Image != "" { - betaPkg.Metadata.Annotations["image"] = alphaPkg.Metadata.Image - } - if alphaPkg.Metadata.Authors != "" { - betaPkg.Metadata.Annotations["authors"] = alphaPkg.Metadata.Authors - } - if alphaPkg.Metadata.Documentation != "" { - betaPkg.Metadata.Annotations["documentation"] = alphaPkg.Metadata.Documentation - } - if alphaPkg.Metadata.Source != "" { - betaPkg.Metadata.Annotations["source"] = alphaPkg.Metadata.Source - } - if alphaPkg.Metadata.Vendor != "" { - betaPkg.Metadata.Annotations["vendor"] = alphaPkg.Metadata.Vendor - } - - if alphaPkg.Metadata.YOLO { - betaPkg.Metadata.Airgap = helpers.BoolPtr(false) - } - - betaPkg.Build.AggregateChecksum = alphaPkg.Metadata.AggregateChecksum - - for i := range betaPkg.Components { - betaPkg.Components[i].Optional = helpers.BoolPtr(!alphaPkg.Components[i].IsRequired()) - for j := range betaPkg.Components[i].Charts { - oldURL := alphaPkg.Components[i].Charts[j].URL - if helpers.IsOCIURL(oldURL) { - betaPkg.Components[i].Charts[j].OCI.URL = oldURL - } else if strings.HasSuffix(oldURL, ".git") { - betaPkg.Components[i].Charts[j].Git.URL = oldURL - betaPkg.Components[i].Charts[j].Git.Path = alphaPkg.Components[i].Charts[j].GitPath - } else { - betaPkg.Components[i].Charts[j].Helm.URL = oldURL - betaPkg.Components[i].Charts[j].Helm.RepoName = alphaPkg.Components[i].Charts[j].RepoName - } - betaPkg.Components[i].Charts[j].Local.Path = alphaPkg.Components[i].Charts[j].LocalPath - betaPkg.Components[i].Charts[j].Wait = helpers.BoolPtr(!alphaPkg.Components[i].Charts[j].NoWait) - } - - for j := range betaPkg.Components[i].Manifests { - betaPkg.Components[i].Manifests[j].Wait = helpers.BoolPtr(!alphaPkg.Components[i].Manifests[j].NoWait) - } - betaPkg.Components[i].Actions.OnCreate = transformActionSet(betaPkg.Components[i].Actions.OnCreate, alphaPkg.Components[i].Actions.OnCreate) - betaPkg.Components[i].Actions.OnDeploy = transformActionSet(betaPkg.Components[i].Actions.OnDeploy, alphaPkg.Components[i].Actions.OnDeploy) - betaPkg.Components[i].Actions.OnRemove = transformActionSet(betaPkg.Components[i].Actions.OnRemove, alphaPkg.Components[i].Actions.OnRemove) - } - - return betaPkg, nil -} - -func transformActionSet(betaActions ZarfComponentActionSet, alphaActions v1alpha1.ZarfComponentActionSet) ZarfComponentActionSet { - if alphaActions.Defaults.MaxTotalSeconds != 0 { - betaActions.Defaults.Timeout = &v1.Duration{Duration: time.Duration(alphaActions.Defaults.MaxTotalSeconds) * time.Second} - } - betaActions.Defaults.Retries = alphaActions.Defaults.MaxRetries - - betaActions.After = transformActions(betaActions.After, alphaActions.After) - betaActions.Before = transformActions(betaActions.Before, alphaActions.Before) - betaActions.OnFailure = transformActions(betaActions.OnFailure, alphaActions.OnFailure) - betaActions.OnSuccess = transformActions(betaActions.OnSuccess, alphaActions.OnSuccess) - - return betaActions -} - -func transformActions(betaActions []ZarfComponentAction, alphaActions []v1alpha1.ZarfComponentAction) []ZarfComponentAction { - for i := range betaActions { - if alphaActions[i].MaxTotalSeconds != nil && *alphaActions[i].MaxTotalSeconds != 0 { - betaActions[i].Timeout = &v1.Duration{Duration: time.Duration(*alphaActions[i].MaxTotalSeconds) * time.Second} - } - - if alphaActions[i].MaxRetries != nil { - betaActions[i].Retries = *alphaActions[i].MaxRetries - } - } - return betaActions -} diff --git a/src/api/internal/v1beta1/translate_test.go b/src/api/internal/v1beta1/translate_test.go deleted file mode 100644 index 749a8a00e2..0000000000 --- a/src/api/internal/v1beta1/translate_test.go +++ /dev/null @@ -1,251 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 -// SPDX-FileCopyrightText: 2021-Present The Zarf Authors - -package v1beta1 - -import ( - "testing" - "time" - - "github.com/defenseunicorns/pkg/helpers/v2" - "github.com/stretchr/testify/require" - "github.com/zarf-dev/zarf/src/api/v1alpha1" - v1 "k8s.io/apimachinery/pkg/apis/meta/v1" -) - -func TestTranslate(t *testing.T) { - t.Parallel() - - maxSeconds := 60 - maxRetries := 10 - - tests := []struct { - name string - oldPkg v1alpha1.ZarfPackage - newPkg ZarfPackage - }{ - { - name: "test", - oldPkg: v1alpha1.ZarfPackage{ - APIVersion: v1alpha1.APIVersion, - Kind: v1alpha1.ZarfPackageConfig, - Components: []v1alpha1.ZarfComponent{ - { - Name: "optional", - Required: helpers.BoolPtr(false), - }, - { - Name: "not-optional", - Required: helpers.BoolPtr(true), - }, - { - Name: "manifests", - Manifests: []v1alpha1.ZarfManifest{ - { - NoWait: true, - }, - { - NoWait: false, - }, - }, - }, - { - Name: "actions", - Actions: v1alpha1.ZarfComponentActions{ - OnCreate: v1alpha1.ZarfComponentActionSet{ - Defaults: v1alpha1.ZarfComponentActionDefaults{ - MaxTotalSeconds: 30, - MaxRetries: 5, - }, - Before: []v1alpha1.ZarfComponentAction{ - { - MaxTotalSeconds: &maxSeconds, - MaxRetries: &maxRetries, - }, - }, - After: []v1alpha1.ZarfComponentAction{ - { - MaxTotalSeconds: &maxSeconds, - MaxRetries: &maxRetries, - }, - { - MaxTotalSeconds: &maxSeconds, - MaxRetries: &maxRetries, - }, - }, - OnSuccess: []v1alpha1.ZarfComponentAction{ - { - MaxTotalSeconds: &maxSeconds, - MaxRetries: &maxRetries, - }, - }, - OnFailure: []v1alpha1.ZarfComponentAction{ - { - MaxTotalSeconds: &maxSeconds, - MaxRetries: &maxRetries, - }, - }, - }, - OnDeploy: v1alpha1.ZarfComponentActionSet{ - Defaults: v1alpha1.ZarfComponentActionDefaults{ - MaxTotalSeconds: 30, - MaxRetries: 5, - }, - }, - OnRemove: v1alpha1.ZarfComponentActionSet{ - Defaults: v1alpha1.ZarfComponentActionDefaults{ - MaxTotalSeconds: 30, - MaxRetries: 5, - }, - }, - }, - }, - { - Name: "helm-chart", - Charts: []v1alpha1.ZarfChart{ - { - URL: "https://example.com/chart", - RepoName: "repo1", - NoWait: true, - }, - { - URL: "https://example.com/chart.git", - GitPath: "path/to/chart2", - NoWait: false, - }, - { - URL: "oci://example.com/chart", - }, - { - LocalPath: "path/to/chart4", - }, - }, - }, - }, - }, - newPkg: ZarfPackage{ - APIVersion: APIVersion, - Kind: ZarfPackageConfig, - Metadata: ZarfMetadata{ - Annotations: map[string]string{}, - }, - Components: []ZarfComponent{ - { - Name: "optional", - Optional: helpers.BoolPtr(true), - }, - { - Name: "not-optional", - Optional: helpers.BoolPtr(false), - }, - { - Name: "manifests", - Optional: helpers.BoolPtr(true), - Manifests: []ZarfManifest{ - { - Wait: helpers.BoolPtr(false), - }, - { - Wait: helpers.BoolPtr(true), - }, - }, - }, - { - Name: "actions", - Optional: helpers.BoolPtr(true), - Actions: ZarfComponentActions{ - OnCreate: ZarfComponentActionSet{ - Defaults: ZarfComponentActionDefaults{ - Timeout: &v1.Duration{Duration: time.Duration(time.Second * 30)}, - Retries: 5, - }, - Before: []ZarfComponentAction{ - { - Timeout: &v1.Duration{Duration: time.Duration(time.Second * 60)}, - Retries: 10, - }, - }, - After: []ZarfComponentAction{ - { - Timeout: &v1.Duration{Duration: time.Duration(time.Second * 60)}, - Retries: 10, - }, - { - Timeout: &v1.Duration{Duration: time.Duration(time.Second * 60)}, - Retries: 10, - }, - }, - OnSuccess: []ZarfComponentAction{ - { - Timeout: &v1.Duration{Duration: time.Duration(time.Second * 60)}, - Retries: 10, - }, - }, - OnFailure: []ZarfComponentAction{ - { - Timeout: &v1.Duration{Duration: time.Duration(time.Second * 60)}, - Retries: 10, - }, - }, - }, - OnDeploy: ZarfComponentActionSet{ - Defaults: ZarfComponentActionDefaults{ - Timeout: &v1.Duration{Duration: time.Duration(time.Second * 30)}, - Retries: 5, - }, - }, - OnRemove: ZarfComponentActionSet{ - Defaults: ZarfComponentActionDefaults{ - Timeout: &v1.Duration{Duration: time.Duration(time.Second * 30)}, - Retries: 5, - }, - }, - }, - }, - { - Name: "helm-chart", - Optional: helpers.BoolPtr(true), - Charts: []ZarfChart{ - { - Wait: helpers.BoolPtr(false), - Helm: HelmRepoSource{ - URL: "https://example.com/chart", - RepoName: "repo1", - }, - }, - { - Wait: helpers.BoolPtr(true), - Git: GitRepoSource{ - URL: "https://example.com/chart.git", - Path: "path/to/chart2", - }, - }, - { - Wait: helpers.BoolPtr(true), - OCI: OCISource{ - URL: "oci://example.com/chart", - }, - }, - { - Wait: helpers.BoolPtr(true), - Local: LocalRepoSource{ - Path: "path/to/chart4", - }, - }, - }, - }, - }, - }, - }, - } - - for _, tc := range tests { - t.Run(tc.name, func(t *testing.T) { - t.Parallel() - - translatedPkg, err := TranslateAlphaPackage(tc.oldPkg) - require.NoError(t, err) - require.Equal(t, tc.newPkg, translatedPkg) - }) - } -} From 529e38132b6d0c87c405c1564c21f3eb94b52bdc Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Wed, 4 Mar 2026 13:02:52 -0500 Subject: [PATCH 02/26] update for v1beta1 Signed-off-by: Austin Abro --- src/api/internal/v1beta1/component.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/internal/v1beta1/component.go b/src/api/internal/v1beta1/component.go index d04ac2662a..d2cbfb5b3c 100644 --- a/src/api/internal/v1beta1/component.go +++ b/src/api/internal/v1beta1/component.go @@ -132,7 +132,7 @@ type ZarfChart struct { Values []ZarfChartValue `json:"values,omitempty"` } -// SetDeprecatedVersion gets the version of the chart, used as a backwards compatibility shim with v1alpha1. +// GetDeprecatedVersion gets the version of the chart, used as a backwards compatibility shim with v1alpha1. func (c ZarfChart) GetDeprecatedVersion() string { return c.version } From f244966644259eb1ce96b1b8a61c1737e880901d Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Wed, 11 Mar 2026 14:51:30 -0400 Subject: [PATCH 03/26] include data injections Signed-off-by: Austin Abro --- src/api/internal/v1beta1/component.go | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/api/internal/v1beta1/component.go b/src/api/internal/v1beta1/component.go index d2cbfb5b3c..023c0a9ebf 100644 --- a/src/api/internal/v1beta1/component.go +++ b/src/api/internal/v1beta1/component.go @@ -4,6 +4,7 @@ package v1beta1 import ( + "github.com/zarf-dev/zarf/src/api/v1alpha1" metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" ) @@ -47,6 +48,21 @@ type ZarfComponent struct { // Custom commands to run at various stages of a package lifecycle. Actions ZarfComponentActions `json:"actions,omitempty"` + + // Datasets to inject into a container in the target cluster. + // This field is not part of the v1beta1 schema but is kept as a backwards compatibility shim so v1alpha1 packages can be losslessly + // converted to v1beta1 for packager logic. + dataInjections []v1alpha1.ZarfDataInjection +} + +// SetDataInjections allows setting data injections for lossless v1alpha1 conversions +func (c *ZarfComponent) SetDataInjections(dataInjections []v1alpha1.ZarfDataInjection) { + c.dataInjections = dataInjections +} + +// GetDataInjections is a shim to retrieving data injections when set for lossless v1alpha1 conversions +func (c ZarfComponent) GetDataInjections() []v1alpha1.ZarfDataInjection { + return c.dataInjections } // RequiresCluster returns if the component requires a cluster connection to deploy. From 429411c0f5c5ea47e94459ef1220279398b73dfc Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Wed, 11 Mar 2026 15:27:14 -0400 Subject: [PATCH 04/26] add in missing fields Signed-off-by: Austin Abro --- src/api/internal/v1beta1/component.go | 48 ++++++++++++++++++++++++--- src/api/internal/v1beta1/package.go | 12 ++++--- 2 files changed, 51 insertions(+), 9 deletions(-) diff --git a/src/api/internal/v1beta1/component.go b/src/api/internal/v1beta1/component.go index 023c0a9ebf..fbd0a2de68 100644 --- a/src/api/internal/v1beta1/component.go +++ b/src/api/internal/v1beta1/component.go @@ -119,6 +119,16 @@ type ZarfFile struct { Symlinks []string `json:"symlinks,omitempty"` // Local folder or file to be extracted from a 'source' archive. ExtractPath string `json:"extractPath,omitempty"` + // Template enables go-template processing on this file during deploy. + Template *bool `json:"template,omitempty"` +} + +// ShouldTemplate returns whether go-template processing is enabled for this file. +func (f ZarfFile) ShouldTemplate() bool { + if f.Template != nil { + return *f.Template + } + return false } // ZarfChart defines a helm chart to be deployed. @@ -146,17 +156,27 @@ type ZarfChart struct { ValuesFiles []string `json:"valuesFiles,omitempty"` // List of values sources to their Helm override target. Values []ZarfChartValue `json:"values,omitempty"` + // Whether to validate the chart's values against its JSON schema. Defaults to true. + SchemaValidation *bool `json:"schemaValidation,omitempty"` +} + +// ShouldRunSchemaValidation returns whether Helm schema validation should run. +func (zc ZarfChart) ShouldRunSchemaValidation() bool { + if zc.SchemaValidation != nil { + return *zc.SchemaValidation + } + return true } // GetDeprecatedVersion gets the version of the chart, used as a backwards compatibility shim with v1alpha1. -func (c ZarfChart) GetDeprecatedVersion() string { - return c.version +func (zc ZarfChart) GetDeprecatedVersion() string { + return zc.version } // SetDeprecatedVersion sets the version of the chart, used as a backwards compatibility shim with v1alpha1. // This function will be deleted when v1alpha1 packages are no longer deployable -func (c *ZarfChart) SetDeprecatedVersion(version string) { - c.version = version +func (zc *ZarfChart) SetDeprecatedVersion(version string) { + zc.version = version } // ZarfChartValue maps a values source path to a Helm chart target path. @@ -213,6 +233,16 @@ type ZarfManifest struct { Kustomizations []string `json:"kustomizations,omitempty"` // Whether to wait for manifest resources to be ready before continuing. Defaults to true. Wait *bool `json:"wait,omitempty"` + // Template enables go-template processing on these manifests during deploy. + Template *bool `json:"template,omitempty"` +} + +// ShouldTemplate returns whether go-template processing is enabled for this manifest. +func (m ZarfManifest) ShouldTemplate() bool { + if m.Template != nil { + return *m.Template + } + return false } // ZarfImage defines an OCI image to include in the package. @@ -317,6 +347,16 @@ type ZarfComponentAction struct { Description string `json:"description,omitempty"` // Wait for a condition to be met before continuing. Must specify either cmd or wait for the action. See the 'zarf tools wait-for' command for more info. Wait *ZarfComponentActionWait `json:"wait,omitempty"` + // Disable go-template processing on the cmd field. + Template *bool `json:"template,omitempty"` +} + +// ShouldTemplate returns whether the action should have go-template processing. +func (a ZarfComponentAction) ShouldTemplate() bool { + if a.Template != nil { + return *a.Template + } + return false } // SetValueType declares the expected input back from the cmd, allowing structured data to be parsed. diff --git a/src/api/internal/v1beta1/package.go b/src/api/internal/v1beta1/package.go index 5c61033ae6..44d2ba2f0d 100644 --- a/src/api/internal/v1beta1/package.go +++ b/src/api/internal/v1beta1/package.go @@ -31,11 +31,6 @@ const ( APIVersion string = "zarf.dev/v1beta1" ) -// ZarfPackageTemplatePrefix is the prefix for package templates. -const ( - ZarfPackageTemplatePrefix = "###ZARF_PKG_TMPL_" -) - // ZarfPackage the top-level structure of a Zarf config file. type ZarfPackage struct { // The API version of the Zarf package. @@ -173,12 +168,19 @@ type ZarfBuildData struct { RegistryOverrides map[string]string `json:"registryOverrides,omitempty"` // Whether this package was created with differential components. Differential bool `json:"differential,omitempty"` + // Version of a previously built package used as the basis for creating this differential package. + DifferentialPackageVersion string `json:"differentialPackageVersion,omitempty"` // The flavor of Zarf used to build this package. Flavor string `json:"flavor,omitempty"` + // Whether this package was signed. + Signed *bool `json:"signed,omitempty"` // Checksum of a checksums.txt file that contains checksums all the layers within the package. AggregateChecksum string `json:"aggregateChecksum,omitempty"` // Requirements for specific Zarf versions needed to deploy this package. VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"` + // ProvenanceFiles lists files present in the package that are not included in checksums.txt. + // These are files added after checksum generation (e.g., signature files). + ProvenanceFiles []string `json:"provenanceFiles,omitempty"` } // VersionRequirement specifies a minimum Zarf version needed and the reason for the requirement. From 73a519eb3d5344b713e3fdbc6acf8eff572e6a4c Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Wed, 11 Mar 2026 15:41:08 -0400 Subject: [PATCH 05/26] generate schema and move out of internal Signed-off-by: Austin Abro --- src/api/{internal => }/v1beta1/component.go | 1 + src/api/{internal => }/v1beta1/package.go | 0 src/api/{internal => }/v1beta1/package_test.go | 0 src/pkg/schema/generate.go | 15 ++++++++++----- 4 files changed, 11 insertions(+), 5 deletions(-) rename src/api/{internal => }/v1beta1/component.go (99%) rename src/api/{internal => }/v1beta1/package.go (100%) rename src/api/{internal => }/v1beta1/package_test.go (100%) diff --git a/src/api/internal/v1beta1/component.go b/src/api/v1beta1/component.go similarity index 99% rename from src/api/internal/v1beta1/component.go rename to src/api/v1beta1/component.go index fbd0a2de68..ff005a1b2a 100644 --- a/src/api/internal/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -1,6 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 // SPDX-FileCopyrightText: 2021-Present The Zarf Authors +// Package v1beta1 holds the definition of the v1beta1 Zarf Package package v1beta1 import ( diff --git a/src/api/internal/v1beta1/package.go b/src/api/v1beta1/package.go similarity index 100% rename from src/api/internal/v1beta1/package.go rename to src/api/v1beta1/package.go diff --git a/src/api/internal/v1beta1/package_test.go b/src/api/v1beta1/package_test.go similarity index 100% rename from src/api/internal/v1beta1/package_test.go rename to src/api/v1beta1/package_test.go diff --git a/src/pkg/schema/generate.go b/src/pkg/schema/generate.go index fa9c238014..3254016fd6 100644 --- a/src/pkg/schema/generate.go +++ b/src/pkg/schema/generate.go @@ -18,21 +18,26 @@ import ( ) func main() { + if err := writeSchema("v1alpha1"); err != nil { + fmt.Println(err.Error()) + os.Exit(1) + } +} + +func writeSchema(apiVersion string) error { schema, err := generateV1Alpha1Schema() if err != nil { - fmt.Println("Error generating schema: %v", err) - os.Exit(1) + return fmt.Errorf("error generating schema: %w", err) } // Add trailing newline to match linter expectations schema = append(schema, '\n') if err := os.WriteFile("zarf-v1alpha1-schema.json", schema, 0644); err != nil { - fmt.Println("Error writing schema file: %v", err) - os.Exit(1) + return fmt.Errorf("error writing schema file: %w", err) } - fmt.Println("Successfully generated zarf-schema.json") + return nil } func generateV1Alpha1Schema() ([]byte, error) { From 3b390c35971fc8926c6d084109177481e1b9ecdd Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Wed, 11 Mar 2026 15:51:17 -0400 Subject: [PATCH 06/26] generate v1beta1 Signed-off-by: Austin Abro --- src/pkg/schema/generate.go | 33 +- src/pkg/schema/zarf-v1beta1-schema.json | 1240 +++++++++++++++++++++++ 2 files changed, 1264 insertions(+), 9 deletions(-) create mode 100644 src/pkg/schema/zarf-v1beta1-schema.json diff --git a/src/pkg/schema/generate.go b/src/pkg/schema/generate.go index 3254016fd6..e6a7c98a0d 100644 --- a/src/pkg/schema/generate.go +++ b/src/pkg/schema/generate.go @@ -15,6 +15,7 @@ import ( "github.com/invopop/jsonschema" "github.com/zarf-dev/zarf/src/api/v1alpha1" + "github.com/zarf-dev/zarf/src/api/v1beta1" ) func main() { @@ -22,25 +23,39 @@ func main() { fmt.Println(err.Error()) os.Exit(1) } + if err := writeSchema("v1beta1"); err != nil { + fmt.Println(err.Error()) + os.Exit(1) + } } func writeSchema(apiVersion string) error { - schema, err := generateV1Alpha1Schema() + var schema []byte + var err error + switch apiVersion { + case "v1alpha1": + schema, err = generateSchema("v1alpha1", &v1alpha1.ZarfPackage{}) + case "v1beta1": + schema, err = generateSchema("v1beta1", &v1beta1.ZarfPackage{}) + default: + return fmt.Errorf("unknown API version: %s", apiVersion) + } if err != nil { - return fmt.Errorf("error generating schema: %w", err) + return fmt.Errorf("error generating %s schema: %w", apiVersion, err) } // Add trailing newline to match linter expectations schema = append(schema, '\n') - if err := os.WriteFile("zarf-v1alpha1-schema.json", schema, 0644); err != nil { + filename := fmt.Sprintf("zarf-%s-schema.json", apiVersion) + if err := os.WriteFile(filename, schema, 0644); err != nil { return fmt.Errorf("error writing schema file: %w", err) } - fmt.Println("Successfully generated zarf-schema.json") + fmt.Printf("Successfully generated %s\n", filename) return nil } -func generateV1Alpha1Schema() ([]byte, error) { +func generateSchema(apiVersion string, rootType any) ([]byte, error) { reflector := jsonschema.Reflector{ExpandedStruct: true} // AddGoComments breaks if called with an absolute path, so we save the current @@ -60,14 +75,14 @@ func generateV1Alpha1Schema() ([]byte, error) { return nil, fmt.Errorf("unable to change to schema directory: %w", err) } - typePackagePath := filepath.Join("..", "..", "api", "v1alpha1") + typePackagePath := filepath.Join("..", "..", "api", apiVersion) + modulePath := fmt.Sprintf("github.com/zarf-dev/zarf/src/api/%s", apiVersion) - // Get the Go comments from the v1alpha1 package - if err := reflector.AddGoComments("github.com/zarf-dev/zarf/src/api/v1alpha1", typePackagePath); err != nil { + if err := reflector.AddGoComments(modulePath, typePackagePath); err != nil { return nil, fmt.Errorf("unable to add Go comments to schema: %w", err) } - schema := reflector.Reflect(&v1alpha1.ZarfPackage{}) + schema := reflector.Reflect(rootType) schemaData, err := json.MarshalIndent(schema, "", " ") if err != nil { diff --git a/src/pkg/schema/zarf-v1beta1-schema.json b/src/pkg/schema/zarf-v1beta1-schema.json new file mode 100644 index 0000000000..d425854266 --- /dev/null +++ b/src/pkg/schema/zarf-v1beta1-schema.json @@ -0,0 +1,1240 @@ +{ + "$defs": { + "Constant": { + "additionalProperties": false, + "description": "Constant are constants that can be used to dynamically template K8s resources or run in actions.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "autoIndent": { + "description": "Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARF_CONST_.", + "type": "boolean" + }, + "description": { + "description": "A description of the constant to explain its purpose on package create or deploy confirmation prompts", + "type": "string" + }, + "name": { + "description": "The name to be used for the constant", + "pattern": "^[A-Z0-9_]+$", + "type": "string" + }, + "pattern": { + "description": "An optional regex pattern that a constant value must match before a package can be created.", + "type": "string" + }, + "value": { + "description": "The value to set for the constant during deploy", + "type": "string" + } + }, + "required": [ + "name", + "value" + ], + "type": "object" + }, + "Duration": { + "additionalProperties": false, + "patternProperties": { + "^x-": {} + }, + "properties": { + "Duration": { + "$ref": "#/$defs/Duration" + } + }, + "required": [ + "Duration" + ], + "type": "object" + }, + "GitRepoSource": { + "additionalProperties": false, + "description": "GitRepoSource represents a Helm chart stored in a Git repository.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "path": { + "description": "The sub directory to the chart within a git repo.", + "type": "string" + }, + "url": { + "description": "The URL of the git repository where the helm chart is stored.", + "type": "string" + } + }, + "required": [ + "url" + ], + "type": "object" + }, + "HelmRepoSource": { + "additionalProperties": false, + "description": "HelmRepoSource represents a Helm chart stored in a Helm repository.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "name": { + "description": "The name of a chart within a Helm repository (defaults to the Zarf name of the chart).", + "type": "string" + }, + "url": { + "description": "The URL of the chart repository where the helm chart is stored.", + "type": "string" + }, + "version": { + "description": "The version of the chart to deploy.", + "type": "string" + } + }, + "required": [ + "url", + "version" + ], + "type": "object" + }, + "ImageArchive": { + "additionalProperties": false, + "description": "ImageArchive defines a tar archive of images to include in the package.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "images": { + "description": "The list of images contained in the archive.", + "items": { + "type": "string" + }, + "type": "array" + }, + "path": { + "description": "The path to the tar archive.", + "type": "string" + } + }, + "required": [ + "path", + "images" + ], + "type": "object" + }, + "Injector": { + "additionalProperties": false, + "description": "Injector defines the configuration for the Zarf injector.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "enabled": { + "description": "Whether the injector is enabled.", + "type": "boolean" + }, + "values": { + "$ref": "#/$defs/InjectorValues", + "description": "Values for the injector." + } + }, + "required": [ + "enabled" + ], + "type": "object" + }, + "InjectorValues": { + "additionalProperties": false, + "description": "InjectorValues defines configurable values for the Zarf injector.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "tolerations": { + "description": "Tolerations for the injector pod.", + "type": "string" + } + }, + "type": "object" + }, + "InteractiveVariable": { + "additionalProperties": false, + "description": "InteractiveVariable is a variable that can be used to prompt a user for more information", + "patternProperties": { + "^x-": {} + }, + "properties": { + "autoIndent": { + "description": "Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARF_VAR_.", + "type": "boolean" + }, + "default": { + "description": "The default value to use for the variable", + "type": "string" + }, + "description": { + "description": "A description of the variable to be used when prompting the user a value", + "type": "string" + }, + "name": { + "description": "The name to be used for the variable", + "pattern": "^[A-Z0-9_]+$", + "type": "string" + }, + "pattern": { + "description": "An optional regex pattern that a variable value must match before a package deployment can continue.", + "type": "string" + }, + "prompt": { + "description": "Whether to prompt the user for input for this variable", + "type": "boolean" + }, + "sensitive": { + "description": "Whether to mark this variable as sensitive to not print it in the log", + "type": "boolean" + }, + "type": { + "description": "Changes the handling of a variable to load contents differently (i.e. from a file rather than as a raw variable - templated files should be kept below 1 MiB)", + "enum": [ + "raw", + "file" + ], + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "LocalRepoSource": { + "additionalProperties": false, + "description": "LocalRepoSource represents a Helm chart stored locally.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "path": { + "description": "The path to a local chart's folder or .tgz archive.", + "type": "string" + } + }, + "required": [ + "path" + ], + "type": "object" + }, + "OCISource": { + "additionalProperties": false, + "description": "OCISource represents a Helm chart stored in an OCI registry.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "url": { + "description": "The URL of the OCI registry where the helm chart is stored.", + "type": "string" + }, + "version": { + "description": "The version of the chart to deploy.", + "type": "string" + } + }, + "required": [ + "url", + "version" + ], + "type": "object" + }, + "SetValue": { + "additionalProperties": false, + "description": "SetValue declares a value that can be set during a package deploy.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "key": { + "description": "Key represents which value to assign to.", + "type": "string" + }, + "type": { + "description": "Type declares the kind of data being stored in the value. JSON and YAML types ensure proper formatting when\ninserting the value into the template. Defaults to SetValueString behavior when empty.", + "type": "string" + }, + "value": { + "description": "Value is the current value at the key." + } + }, + "type": "object" + }, + "Shell": { + "additionalProperties": false, + "description": "Shell represents the desired shell to use for a given command", + "patternProperties": { + "^x-": {} + }, + "properties": { + "darwin": { + "description": "(default 'sh') Indicates a preference for the shell to use on macOS systems", + "examples": [ + "sh", + "bash", + "fish", + "zsh", + "pwsh" + ], + "type": "string" + }, + "linux": { + "description": "(default 'sh') Indicates a preference for the shell to use on Linux systems", + "examples": [ + "sh", + "bash", + "fish", + "zsh", + "pwsh" + ], + "type": "string" + }, + "windows": { + "description": "(default 'powershell') Indicates a preference for the shell to use on Windows systems (note that choosing 'cmd' will turn off migrations like touch -\u003e New-Item)", + "examples": [ + "powershell", + "cmd", + "pwsh", + "sh", + "bash", + "gsh" + ], + "type": "string" + } + }, + "type": "object" + }, + "Variable": { + "additionalProperties": false, + "description": "Variable represents a variable that has a value set programmatically", + "patternProperties": { + "^x-": {} + }, + "properties": { + "autoIndent": { + "description": "Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARF_VAR_.", + "type": "boolean" + }, + "name": { + "description": "The name to be used for the variable", + "pattern": "^[A-Z0-9_]+$", + "type": "string" + }, + "pattern": { + "description": "An optional regex pattern that a variable value must match before a package deployment can continue.", + "type": "string" + }, + "sensitive": { + "description": "Whether to mark this variable as sensitive to not print it in the log", + "type": "boolean" + }, + "type": { + "description": "Changes the handling of a variable to load contents differently (i.e. from a file rather than as a raw variable - templated files should be kept below 1 MiB)", + "enum": [ + "raw", + "file" + ], + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "VersionRequirement": { + "additionalProperties": false, + "description": "VersionRequirement specifies a minimum Zarf version needed and the reason for the requirement.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "reason": { + "description": "The reason this version is required.", + "type": "string" + }, + "version": { + "description": "The minimum version of Zarf required.", + "type": "string" + } + }, + "required": [ + "version", + "reason" + ], + "type": "object" + }, + "ZarfBuildData": { + "additionalProperties": false, + "description": "ZarfBuildData is written during the packager.Create() operation to track details of the created package.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "aggregateChecksum": { + "description": "Checksum of a checksums.txt file that contains checksums all the layers within the package.", + "type": "string" + }, + "architecture": { + "description": "The architecture this package was created on.", + "type": "string" + }, + "differential": { + "description": "Whether this package was created with differential components.", + "type": "boolean" + }, + "differentialPackageVersion": { + "description": "Version of a previously built package used as the basis for creating this differential package.", + "type": "string" + }, + "flavor": { + "description": "The flavor of Zarf used to build this package.", + "type": "string" + }, + "migrations": { + "description": "Any migrations that have been run on this package.", + "items": { + "type": "string" + }, + "type": "array" + }, + "provenanceFiles": { + "description": "ProvenanceFiles lists files present in the package that are not included in checksums.txt.\nThese are files added after checksum generation (e.g., signature files).", + "items": { + "type": "string" + }, + "type": "array" + }, + "registryOverrides": { + "additionalProperties": { + "type": "string" + }, + "description": "Any registry domains that were overridden on package create when pulling images.", + "type": "object" + }, + "signed": { + "description": "Whether this package was signed.", + "type": "boolean" + }, + "terminal": { + "description": "The machine name that created this package.", + "type": "string" + }, + "timestamp": { + "description": "The timestamp when this package was created.", + "type": "string" + }, + "user": { + "description": "The username who created this package.", + "type": "string" + }, + "version": { + "description": "The version of Zarf used to build this package.", + "type": "string" + }, + "versionRequirements": { + "description": "Requirements for specific Zarf versions needed to deploy this package.", + "items": { + "$ref": "#/$defs/VersionRequirement" + }, + "type": "array" + } + }, + "required": [ + "architecture", + "timestamp", + "version" + ], + "type": "object" + }, + "ZarfChart": { + "additionalProperties": false, + "description": "ZarfChart defines a helm chart to be deployed.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "git": { + "$ref": "#/$defs/GitRepoSource", + "description": "The Git repo where the chart is stored." + }, + "helmRepo": { + "$ref": "#/$defs/HelmRepoSource", + "description": "The Helm repo where the chart is stored." + }, + "local": { + "$ref": "#/$defs/LocalRepoSource", + "description": "The local path where the chart is stored." + }, + "name": { + "description": "The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repo.", + "type": "string" + }, + "namespace": { + "description": "The namespace to deploy the chart to.", + "type": "string" + }, + "oci": { + "$ref": "#/$defs/OCISource", + "description": "The OCI registry where the chart is stored." + }, + "releaseName": { + "description": "The name of the Helm release to create (defaults to the Zarf name of the chart).", + "type": "string" + }, + "schemaValidation": { + "description": "Whether to validate the chart's values against its JSON schema. Defaults to true.", + "type": "boolean" + }, + "values": { + "description": "List of values sources to their Helm override target.", + "items": { + "$ref": "#/$defs/ZarfChartValue" + }, + "type": "array" + }, + "valuesFiles": { + "description": "List of local values file paths or remote URLs to include in the package; these will be merged together when deployed.", + "items": { + "type": "string" + }, + "type": "array" + }, + "wait": { + "description": "Whether to wait for chart resources to be ready before continuing. Defaults to true.", + "type": "boolean" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "ZarfChartValue": { + "additionalProperties": false, + "description": "ZarfChartValue maps a values source path to a Helm chart target path.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "sourcePath": { + "description": "The source path for the value.", + "type": "string" + }, + "targetPath": { + "description": "The target path within the Helm chart values.", + "type": "string" + } + }, + "required": [ + "sourcePath", + "targetPath" + ], + "type": "object" + }, + "ZarfComponent": { + "additionalProperties": false, + "description": "ZarfComponent is the primary functional grouping of assets to deploy by Zarf.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "actions": { + "$ref": "#/$defs/ZarfComponentActions", + "description": "Custom commands to run at various stages of a package lifecycle." + }, + "charts": { + "description": "Helm charts to install during package deploy.", + "items": { + "$ref": "#/$defs/ZarfChart" + }, + "type": "array" + }, + "description": { + "description": "Message to include during package deploy describing the purpose of this component.", + "type": "string" + }, + "features": { + "$ref": "#/$defs/ZarfComponentFeatures", + "description": "Features of the Zarf CLI to enable for this component." + }, + "files": { + "description": "Files or folders to place on disk during package deployment.", + "items": { + "$ref": "#/$defs/ZarfFile" + }, + "type": "array" + }, + "imageArchives": { + "description": "List of tar archives of images to include in the package.", + "items": { + "$ref": "#/$defs/ImageArchive" + }, + "type": "array" + }, + "images": { + "description": "List of OCI images to include in the package.", + "items": { + "$ref": "#/$defs/ZarfImage" + }, + "type": "array" + }, + "import": { + "$ref": "#/$defs/ZarfComponentImport", + "description": "Import a component from another Zarf component config." + }, + "manifests": { + "description": "Kubernetes manifests to be included in a generated Helm chart on package deploy.", + "items": { + "$ref": "#/$defs/ZarfManifest" + }, + "type": "array" + }, + "name": { + "description": "The name of the component.", + "pattern": "^[a-z0-9][a-z0-9\\-]*$", + "type": "string" + }, + "only": { + "$ref": "#/$defs/ZarfComponentOnlyTarget", + "description": "Filter when this component is included in package creation or deployment." + }, + "optional": { + "description": "Do not prompt user to install this component. Defaults to false, meaning the component is required.", + "type": "boolean" + }, + "repos": { + "description": "List of git repos to include in the package.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "ZarfComponentAction": { + "additionalProperties": false, + "description": "ZarfComponentAction represents a single action to run during a zarf package operation.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "cmd": { + "description": "The command to run. Must specify either cmd or wait for the action to do anything.", + "type": "string" + }, + "description": { + "description": "Description of the action to be displayed during package execution instead of the command.", + "type": "string" + }, + "dir": { + "description": "The working directory to run the command in (default is CWD).", + "type": "string" + }, + "env": { + "description": "Additional environment variables to set for the command.", + "items": { + "type": "string" + }, + "type": "array" + }, + "mute": { + "description": "Hide the output of the command during package deployment (default false).", + "type": "boolean" + }, + "retries": { + "description": "Retry the command if it fails up to given number of times (default 0).", + "type": "integer" + }, + "setValues": { + "description": "An array of values to set with the output of the command.", + "items": { + "$ref": "#/$defs/SetValue" + }, + "type": "array" + }, + "setVariables": { + "description": "(onDeploy/cmd only) An array of variables to update with the output of the command. These variables will be available to all remaining actions and components in the package.", + "items": { + "$ref": "#/$defs/Variable" + }, + "type": "array" + }, + "shell": { + "$ref": "#/$defs/Shell", + "description": "(cmd only) Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems." + }, + "template": { + "description": "Disable go-template processing on the cmd field.", + "type": "boolean" + }, + "timeout": { + "$ref": "#/$defs/Duration", + "description": "Timeout for the command (default to 0, no timeout for cmd actions and 5 minutes for wait actions)." + }, + "wait": { + "$ref": "#/$defs/ZarfComponentActionWait", + "description": "Wait for a condition to be met before continuing. Must specify either cmd or wait for the action. See the 'zarf tools wait-for' command for more info." + } + }, + "type": "object" + }, + "ZarfComponentActionDefaults": { + "additionalProperties": false, + "description": "ZarfComponentActionDefaults sets the default configs for child actions.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "dir": { + "description": "Working directory for commands (default CWD).", + "type": "string" + }, + "env": { + "description": "Additional environment variables for commands.", + "items": { + "type": "string" + }, + "type": "array" + }, + "mute": { + "description": "Hide the output of commands during execution (default false).", + "type": "boolean" + }, + "retries": { + "description": "Retry commands given number of times if they fail (default 0).", + "type": "integer" + }, + "shell": { + "$ref": "#/$defs/Shell", + "description": "(cmd only) Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems." + }, + "timeout": { + "$ref": "#/$defs/Duration", + "description": "Default timeout for commands (default no timeout)." + } + }, + "type": "object" + }, + "ZarfComponentActionSet": { + "additionalProperties": false, + "description": "ZarfComponentActionSet is a set of actions to run during a zarf package operation.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "after": { + "description": "Actions to run at the end of an operation.", + "items": { + "$ref": "#/$defs/ZarfComponentAction" + }, + "type": "array" + }, + "before": { + "description": "Actions to run at the start of an operation.", + "items": { + "$ref": "#/$defs/ZarfComponentAction" + }, + "type": "array" + }, + "defaults": { + "$ref": "#/$defs/ZarfComponentActionDefaults", + "description": "Default configuration for all actions in this set." + }, + "onFailure": { + "description": "Actions to run if all operations fail.", + "items": { + "$ref": "#/$defs/ZarfComponentAction" + }, + "type": "array" + } + }, + "type": "object" + }, + "ZarfComponentActionWait": { + "additionalProperties": false, + "description": "ZarfComponentActionWait specifies a condition to wait for before continuing", + "patternProperties": { + "^x-": {} + }, + "properties": { + "cluster": { + "$ref": "#/$defs/ZarfComponentActionWaitCluster", + "description": "Wait for a condition to be met in the cluster before continuing. Only one of cluster or network can be specified." + }, + "network": { + "$ref": "#/$defs/ZarfComponentActionWaitNetwork", + "description": "Wait for a condition to be met on the network before continuing. Only one of cluster or network can be specified." + } + }, + "type": "object" + }, + "ZarfComponentActionWaitCluster": { + "additionalProperties": false, + "description": "ZarfComponentActionWaitCluster specifies a condition to wait for before continuing", + "patternProperties": { + "^x-": {} + }, + "properties": { + "condition": { + "description": "The condition or jsonpath state to wait for; defaults to kstatus readiness checks.", + "examples": [ + "Available" + ], + "type": "string" + }, + "kind": { + "description": "The kind of resource to wait for.", + "examples": [ + "Pod", + "Deployment" + ], + "type": "string" + }, + "name": { + "description": "The name of the resource or selector to wait for.", + "examples": [ + "podinfo", + "app=podinfo" + ], + "type": "string" + }, + "namespace": { + "description": "The namespace of the resource to wait for.", + "type": "string" + } + }, + "required": [ + "kind", + "name" + ], + "type": "object" + }, + "ZarfComponentActionWaitNetwork": { + "additionalProperties": false, + "description": "ZarfComponentActionWaitNetwork specifies a condition to wait for before continuing", + "patternProperties": { + "^x-": {} + }, + "properties": { + "address": { + "description": "The address to wait for.", + "examples": [ + "localhost:8080", + "1.1.1.1" + ], + "type": "string" + }, + "code": { + "description": "The HTTP status code to wait for if using http or https.", + "examples": [ + 200, + 404 + ], + "type": "integer" + }, + "protocol": { + "description": "The protocol to wait for.", + "enum": [ + "tcp", + "http", + "https" + ], + "type": "string" + } + }, + "required": [ + "protocol", + "address" + ], + "type": "object" + }, + "ZarfComponentActions": { + "additionalProperties": false, + "description": "ZarfComponentActions are ActionSets that map to different zarf package operations.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "onCreate": { + "$ref": "#/$defs/ZarfComponentActionSet", + "description": "Actions to run during package creation." + }, + "onDeploy": { + "$ref": "#/$defs/ZarfComponentActionSet", + "description": "Actions to run during package deployment." + }, + "onRemove": { + "$ref": "#/$defs/ZarfComponentActionSet", + "description": "Actions to run during package removal." + } + }, + "type": "object" + }, + "ZarfComponentFeatures": { + "additionalProperties": false, + "description": "ZarfComponentFeatures defines features of the Zarf CLI to enable for a component.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "injector": { + "$ref": "#/$defs/Injector", + "description": "Injector configuration for the component." + }, + "isAgent": { + "description": "Whether this component provides an agent.", + "type": "boolean" + }, + "isRegistry": { + "description": "Whether this component provides a registry.", + "type": "boolean" + } + }, + "type": "object" + }, + "ZarfComponentImport": { + "additionalProperties": false, + "description": "ZarfComponentImport structure for including imported Zarf components.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "path": { + "description": "The path to the component config file to import.", + "type": "string" + }, + "url": { + "description": "The URL to a Zarf component config to import via OCI.", + "pattern": "^oci://.*$", + "type": "string" + } + }, + "type": "object" + }, + "ZarfComponentOnlyCluster": { + "additionalProperties": false, + "description": "ZarfComponentOnlyCluster represents the architecture and K8s cluster distribution to filter on.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "architecture": { + "description": "Only create and deploy to clusters of the given architecture.", + "enum": [ + "amd64", + "arm64" + ], + "type": "string" + }, + "distros": { + "description": "A list of kubernetes distros this package works with (Reserved for future use).", + "items": { + "examples": [ + "k3s", + "eks" + ], + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "ZarfComponentOnlyTarget": { + "additionalProperties": false, + "description": "ZarfComponentOnlyTarget filters a component to only show it for a given local OS and cluster.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "cluster": { + "$ref": "#/$defs/ZarfComponentOnlyCluster", + "description": "Only deploy component to specified clusters." + }, + "flavor": { + "description": "Only include this component when a matching '--flavor' is specified on 'zarf package create'.", + "type": "string" + }, + "localOS": { + "description": "Only deploy component to specified OS.", + "enum": [ + "linux", + "darwin", + "windows" + ], + "type": "string" + } + }, + "type": "object" + }, + "ZarfFile": { + "additionalProperties": false, + "description": "ZarfFile defines a file to deploy.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "executable": { + "description": "(files only) Determines if the file should be made executable during package deploy.", + "type": "boolean" + }, + "extractPath": { + "description": "Local folder or file to be extracted from a 'source' archive.", + "type": "string" + }, + "shasum": { + "description": "(files only) Optional SHA256 checksum of the file.", + "type": "string" + }, + "source": { + "description": "Local folder or file path or remote URL to pull into the package.", + "type": "string" + }, + "symlinks": { + "description": "List of symlinks to create during package deploy.", + "items": { + "type": "string" + }, + "type": "array" + }, + "target": { + "description": "The absolute or relative path where the file or folder should be copied to during package deploy.", + "type": "string" + }, + "template": { + "description": "Template enables go-template processing on this file during deploy.", + "type": "boolean" + } + }, + "required": [ + "source", + "target" + ], + "type": "object" + }, + "ZarfImage": { + "additionalProperties": false, + "description": "ZarfImage defines an OCI image to include in the package.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "name": { + "description": "The image reference.", + "type": "string" + }, + "source": { + "description": "The source to pull the image from. Defaults to \"registry\".", + "enum": [ + "registry", + "daemon" + ], + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "ZarfManifest": { + "additionalProperties": false, + "description": "ZarfManifest defines raw manifests Zarf will deploy as a helm chart.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "files": { + "description": "List of local K8s YAML files or remote URLs to deploy (in order).", + "items": { + "type": "string" + }, + "type": "array" + }, + "kustomizations": { + "description": "List of local kustomization paths or remote URLs to include in the package.", + "items": { + "type": "string" + }, + "type": "array" + }, + "kustomizeAllowAnyDirectory": { + "description": "Allow traversing directory above the current directory if needed for kustomization. (Defaults to false)", + "type": "boolean" + }, + "name": { + "description": "A name to give this collection of manifests; this will become the name of the dynamically-created helm chart.", + "type": "string" + }, + "namespace": { + "description": "The namespace to deploy the manifests to.", + "type": "string" + }, + "template": { + "description": "Template enables go-template processing on these manifests during deploy.", + "type": "boolean" + }, + "wait": { + "description": "Whether to wait for manifest resources to be ready before continuing. Defaults to true.", + "type": "boolean" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "ZarfMetadata": { + "additionalProperties": false, + "description": "ZarfMetadata lists information about the current ZarfPackage.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "allowNamespaceOverride": { + "description": "Whether to allow namespace overrides for this package.", + "type": "boolean" + }, + "annotations": { + "additionalProperties": { + "type": "string" + }, + "description": "Annotations are key-value pairs that can be used to store metadata about the package.", + "type": "object" + }, + "architecture": { + "description": "The target cluster architecture for this package.", + "examples": [ + "arm64", + "amd64" + ], + "type": "string" + }, + "description": { + "description": "Additional information about this Zarf package.", + "type": "string" + }, + "name": { + "description": "Name to identify this Zarf package.", + "pattern": "^[a-z0-9][a-z0-9\\-]*$", + "type": "string" + }, + "uncompressed": { + "description": "Disable compression of this package.", + "type": "boolean" + }, + "version": { + "description": "Generic string set by a package author to track the package version (Note: ZarfInitConfigs will always be versioned to the CLIVersion they were created with).", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "ZarfValues": { + "additionalProperties": false, + "description": "ZarfValues defines values files and schema for templating and overriding Helm values.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "files": { + "description": "List of values file paths to include.", + "items": { + "type": "string" + }, + "type": "array" + }, + "schema": { + "description": "Path to a JSON schema file for validating values.", + "type": "string" + } + }, + "type": "object" + } + }, + "$id": "https://github.com/zarf-dev/zarf/src/api/v1beta1/zarf-package", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "description": "ZarfPackage the top-level structure of a Zarf config file.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "apiVersion": { + "description": "The API version of the Zarf package.", + "enum": [ + "zarf.dev/v1beta1" + ], + "type": "string" + }, + "build": { + "$ref": "#/$defs/ZarfBuildData", + "description": "Zarf-generated package build data." + }, + "components": { + "description": "List of components to deploy in this package.", + "items": { + "$ref": "#/$defs/ZarfComponent" + }, + "type": "array" + }, + "constants": { + "description": "Constant template values applied on deploy for K8s resources.", + "items": { + "$ref": "#/$defs/Constant" + }, + "type": "array" + }, + "documentation": { + "additionalProperties": { + "type": "string" + }, + "description": "Documentation files.", + "type": "object" + }, + "kind": { + "default": "ZarfPackageConfig", + "description": "The kind of Zarf package.", + "enum": [ + "ZarfInitConfig", + "ZarfPackageConfig" + ], + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/ZarfMetadata", + "description": "Package metadata." + }, + "values": { + "$ref": "#/$defs/ZarfValues", + "description": "Values imports Zarf values files for templating." + }, + "variables": { + "description": "Variable template values applied on deploy for K8s resources.", + "items": { + "$ref": "#/$defs/InteractiveVariable" + }, + "type": "array" + } + }, + "required": [ + "kind", + "components" + ], + "type": "object" +} From 3a424b0aa4ac590dc8dd7378fe342c7280900e36 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Thu, 12 Mar 2026 10:07:06 -0400 Subject: [PATCH 07/26] add server side apply Signed-off-by: Austin Abro --- src/api/v1beta1/component.go | 30 +++++++++++++++++++++++++ src/pkg/schema/zarf-v1beta1-schema.json | 18 +++++++++++++++ 2 files changed, 48 insertions(+) diff --git a/src/api/v1beta1/component.go b/src/api/v1beta1/component.go index ff005a1b2a..533f021ae9 100644 --- a/src/api/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -159,6 +159,13 @@ type ZarfChart struct { Values []ZarfChartValue `json:"values,omitempty"` // Whether to validate the chart's values against its JSON schema. Defaults to true. SchemaValidation *bool `json:"schemaValidation,omitempty"` + // Controls whether Helm uses Server-Side Apply (SSA) or client-side apply (CSA) when deploying this chart. + // - "true": always use SSA + // - "false": always use CSA + // - "auto": use SSA for fresh installs; for upgrades, match whichever strategy + // was used when the chart was first installed + // Defaults to "auto" when omitted. + ServerSideApply string `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"` } // ShouldRunSchemaValidation returns whether Helm schema validation should run. @@ -169,6 +176,14 @@ func (zc ZarfChart) ShouldRunSchemaValidation() bool { return true } +// GetServerSideApply returns server side apply with default of "auto" if it is not set +func (zc ZarfChart) GetServerSideApply() string { + if zc.ServerSideApply == "" { + return "auto" + } + return zc.ServerSideApply +} + // GetDeprecatedVersion gets the version of the chart, used as a backwards compatibility shim with v1alpha1. func (zc ZarfChart) GetDeprecatedVersion() string { return zc.version @@ -232,6 +247,13 @@ type ZarfManifest struct { KustomizeAllowAnyDirectory bool `json:"kustomizeAllowAnyDirectory,omitempty"` // List of local kustomization paths or remote URLs to include in the package. Kustomizations []string `json:"kustomizations,omitempty"` + // Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy. + // - "true": always use SSA + // - "false": always use CSA + // - "auto": use SSA for fresh installs; for upgrades, match whichever strategy + // was used when the chart was first installed + // Defaults to "auto" when omitted. + ServerSideApply string `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"` // Whether to wait for manifest resources to be ready before continuing. Defaults to true. Wait *bool `json:"wait,omitempty"` // Template enables go-template processing on these manifests during deploy. @@ -246,6 +268,14 @@ func (m ZarfManifest) ShouldTemplate() bool { return false } +// GetServerSideApply returns server side apply with default of "auto" if it is not set +func (m ZarfManifest) GetServerSideApply() string { + if m.ServerSideApply == "" { + return "auto" + } + return m.ServerSideApply +} + // ZarfImage defines an OCI image to include in the package. type ZarfImage struct { // The image reference. diff --git a/src/pkg/schema/zarf-v1beta1-schema.json b/src/pkg/schema/zarf-v1beta1-schema.json index d425854266..061b776a0b 100644 --- a/src/pkg/schema/zarf-v1beta1-schema.json +++ b/src/pkg/schema/zarf-v1beta1-schema.json @@ -493,6 +493,15 @@ "description": "Whether to validate the chart's values against its JSON schema. Defaults to true.", "type": "boolean" }, + "serverSideApply": { + "description": "Controls whether Helm uses Server-Side Apply (SSA) or client-side apply (CSA) when deploying this chart.\n - \"true\": always use SSA\n - \"false\": always use CSA\n - \"auto\": use SSA for fresh installs; for upgrades, match whichever strategy\n was used when the chart was first installed\nDefaults to \"auto\" when omitted.", + "enum": [ + "true", + "false", + "auto" + ], + "type": "string" + }, "values": { "description": "List of values sources to their Helm override target.", "items": { @@ -1082,6 +1091,15 @@ "description": "The namespace to deploy the manifests to.", "type": "string" }, + "serverSideApply": { + "description": "Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy.\n - \"true\": always use SSA\n - \"false\": always use CSA\n - \"auto\": use SSA for fresh installs; for upgrades, match whichever strategy\n was used when the chart was first installed\nDefaults to \"auto\" when omitted.", + "enum": [ + "true", + "false", + "auto" + ], + "type": "string" + }, "template": { "description": "Template enables go-template processing on these manifests during deploy.", "type": "boolean" From 3318a5dcc1f1f2d53cee6756024b8a18e80c34b6 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Fri, 13 Mar 2026 15:56:55 -0400 Subject: [PATCH 08/26] make allow namespace overrides a boolptr field Signed-off-by: Austin Abro --- src/api/v1beta1/package.go | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/api/v1beta1/package.go b/src/api/v1beta1/package.go index 44d2ba2f0d..810d858203 100644 --- a/src/api/v1beta1/package.go +++ b/src/api/v1beta1/package.go @@ -58,6 +58,15 @@ func (pkg ZarfPackage) IsInitConfig() bool { return pkg.Kind == ZarfInitConfig } +// AllowsNamespaceOverride returns whether the package allows the namespace to be overridden +func (pkg ZarfPackage) AllowsNamespaceOverride() bool { + if pkg.Metadata.AllowNamespaceOverride != nil { + return *pkg.Metadata.AllowNamespaceOverride + } + // defaulting to allowing package namespace to be overridden + return true +} + // HasImages returns true if one of the components contains an image. func (pkg ZarfPackage) HasImages() bool { for _, component := range pkg.Components { @@ -147,7 +156,7 @@ type ZarfMetadata struct { // Annotations are key-value pairs that can be used to store metadata about the package. Annotations map[string]string `json:"annotations,omitempty"` // Whether to allow namespace overrides for this package. - AllowNamespaceOverride bool `json:"allowNamespaceOverride,omitempty"` + AllowNamespaceOverride *bool `json:"allowNamespaceOverride,omitempty"` } // ZarfBuildData is written during the packager.Create() operation to track details of the created package. From c2098efec4810e4b393621f1862fdad7fcf9d189 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 16 Mar 2026 12:13:22 -0400 Subject: [PATCH 09/26] update v1beta1 with default Signed-off-by: Austin Abro --- src/api/v1beta1/component.go | 3 +++ src/pkg/schema/zarf-v1beta1-schema.json | 4 ++++ 2 files changed, 7 insertions(+) diff --git a/src/api/v1beta1/component.go b/src/api/v1beta1/component.go index 533f021ae9..c27369d6cc 100644 --- a/src/api/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -17,6 +17,9 @@ type ZarfComponent struct { // Message to include during package deploy describing the purpose of this component. Description string `json:"description,omitempty"` + // Determines the default Y/N state for installing this component on package deploy. + Default bool `json:"default,omitempty"` + // Do not prompt user to install this component. Defaults to false, meaning the component is required. Optional *bool `json:"optional,omitempty"` diff --git a/src/pkg/schema/zarf-v1beta1-schema.json b/src/pkg/schema/zarf-v1beta1-schema.json index 061b776a0b..bf54528032 100644 --- a/src/pkg/schema/zarf-v1beta1-schema.json +++ b/src/pkg/schema/zarf-v1beta1-schema.json @@ -566,6 +566,10 @@ }, "type": "array" }, + "default": { + "description": "Determines the default Y/N state for installing this component on package deploy.", + "type": "boolean" + }, "description": { "description": "Message to include during package deploy describing the purpose of this component.", "type": "string" From 0bbd04883744dd6637835f0d5ff0241cd5cbec21 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 16 Mar 2026 12:16:24 -0400 Subject: [PATCH 10/26] add get images Signed-off-by: Austin Abro --- src/api/v1beta1/component.go | 12 ++++ src/api/v1beta1/component_test.go | 99 +++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 src/api/v1beta1/component_test.go diff --git a/src/api/v1beta1/component.go b/src/api/v1beta1/component.go index c27369d6cc..e6fda8f61d 100644 --- a/src/api/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -69,6 +69,18 @@ func (c ZarfComponent) GetDataInjections() []v1alpha1.ZarfDataInjection { return c.dataInjections } +// GetImages returns all image names specified in the component, including those from ImageArchives. +func (c ZarfComponent) GetImages() []string { + images := []string{} + for _, img := range c.Images { + images = append(images, img.Name) + } + for _, ia := range c.ImageArchives { + images = append(images, ia.Images...) + } + return images +} + // RequiresCluster returns if the component requires a cluster connection to deploy. func (c ZarfComponent) RequiresCluster() bool { hasImages := len(c.Images) > 0 diff --git a/src/api/v1beta1/component_test.go b/src/api/v1beta1/component_test.go new file mode 100644 index 0000000000..baeff3eb97 --- /dev/null +++ b/src/api/v1beta1/component_test.go @@ -0,0 +1,99 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: 2021-Present The Zarf Authors + +package v1beta1 + +import ( + "testing" + + "github.com/stretchr/testify/require" +) + +func TestGetImages(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + component ZarfComponent + expected []string + }{ + { + name: "no images", + component: ZarfComponent{ + Name: "test-component", + }, + expected: []string{}, + }, + { + name: "only Images field", + component: ZarfComponent{ + Name: "test-component", + Images: []ZarfImage{ + {Name: "docker.io/library/nginx:latest"}, + {Name: "ghcr.io/zarf-dev/zarf:v0.32.6"}, + }, + }, + expected: []string{ + "docker.io/library/nginx:latest", + "ghcr.io/zarf-dev/zarf:v0.32.6", + }, + }, + { + name: "only ImageArchives with images", + component: ZarfComponent{ + Name: "test-component", + ImageArchives: []ImageArchive{ + { + Path: "/tmp/images.tar", + Images: []string{ + "docker.io/library/redis:latest", + "docker.io/library/postgres:14", + }, + }, + }, + }, + expected: []string{ + "docker.io/library/redis:latest", + "docker.io/library/postgres:14", + }, + }, + { + name: "both Images and ImageArchives", + component: ZarfComponent{ + Name: "test-component", + Images: []ZarfImage{ + {Name: "docker.io/library/nginx:latest"}, + }, + ImageArchives: []ImageArchive{ + { + Path: "/tmp/images1.tar", + Images: []string{ + "docker.io/library/redis:latest", + }, + }, + { + Path: "/tmp/images2.tar", + Images: []string{ + "docker.io/library/postgres:14", + "ghcr.io/zarf-dev/zarf:v0.32.6", + }, + }, + }, + }, + expected: []string{ + "docker.io/library/nginx:latest", + "docker.io/library/redis:latest", + "docker.io/library/postgres:14", + "ghcr.io/zarf-dev/zarf:v0.32.6", + }, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + result := tt.component.GetImages() + require.Equal(t, tt.expected, result) + }) + } +} From 288c31af01bf04615eb8377296f48915a7d3b8b9 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 16 Mar 2026 15:26:19 -0400 Subject: [PATCH 11/26] build api version Signed-off-by: Austin Abro --- src/api/v1alpha1/package.go | 2 ++ src/api/v1beta1/package.go | 2 ++ src/pkg/schema/zarf-v1alpha1-schema.json | 4 ++++ src/pkg/schema/zarf-v1beta1-schema.json | 4 ++++ zarf.schema.json | 4 ++++ 5 files changed, 16 insertions(+) diff --git a/src/api/v1alpha1/package.go b/src/api/v1alpha1/package.go index 2ac778a97d..96f7666ae1 100644 --- a/src/api/v1alpha1/package.go +++ b/src/api/v1alpha1/package.go @@ -267,6 +267,8 @@ type ZarfBuildData struct { Flavor string `json:"flavor,omitempty"` // Whether this package was signed Signed *bool `json:"signed,omitempty"` + // The API version defined in the package definition used to build the package. + APIVersion string `json:"apiVersion,omitempty"` // Requirements for specific package operations. VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"` // ProvenanceFiles lists files present in the package that are not included in checksums.txt. diff --git a/src/api/v1beta1/package.go b/src/api/v1beta1/package.go index 810d858203..5c8b3e4f20 100644 --- a/src/api/v1beta1/package.go +++ b/src/api/v1beta1/package.go @@ -185,6 +185,8 @@ type ZarfBuildData struct { Signed *bool `json:"signed,omitempty"` // Checksum of a checksums.txt file that contains checksums all the layers within the package. AggregateChecksum string `json:"aggregateChecksum,omitempty"` + // The API version defined in the package definition used to build the package. + APIVersion string `json:"apiVersion,omitempty"` // Requirements for specific Zarf versions needed to deploy this package. VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"` // ProvenanceFiles lists files present in the package that are not included in checksums.txt. diff --git a/src/pkg/schema/zarf-v1alpha1-schema.json b/src/pkg/schema/zarf-v1alpha1-schema.json index 79c5eb59f2..46edd8ed93 100644 --- a/src/pkg/schema/zarf-v1alpha1-schema.json +++ b/src/pkg/schema/zarf-v1alpha1-schema.json @@ -316,6 +316,10 @@ "^x-": {} }, "properties": { + "apiVersion": { + "description": "The API version defined in the package definition used to build the package.", + "type": "string" + }, "architecture": { "description": "The architecture this package was created on.", "type": "string" diff --git a/src/pkg/schema/zarf-v1beta1-schema.json b/src/pkg/schema/zarf-v1beta1-schema.json index bf54528032..8ed0dcebf1 100644 --- a/src/pkg/schema/zarf-v1beta1-schema.json +++ b/src/pkg/schema/zarf-v1beta1-schema.json @@ -382,6 +382,10 @@ "description": "Checksum of a checksums.txt file that contains checksums all the layers within the package.", "type": "string" }, + "apiVersion": { + "description": "The API version defined in the package definition used to build the package.", + "type": "string" + }, "architecture": { "description": "The architecture this package was created on.", "type": "string" diff --git a/zarf.schema.json b/zarf.schema.json index 79c5eb59f2..46edd8ed93 100644 --- a/zarf.schema.json +++ b/zarf.schema.json @@ -316,6 +316,10 @@ "^x-": {} }, "properties": { + "apiVersion": { + "description": "The API version defined in the package definition used to build the package.", + "type": "string" + }, "architecture": { "description": "The architecture this package was created on.", "type": "string" From a2848a238cc9eec4f1ec5868c1ea37ce0d4814c2 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Thu, 28 May 2026 11:14:49 -0400 Subject: [PATCH 12/26] v1beta1 changes Signed-off-by: Austin Abro --- src/api/v1beta1/component.go | 515 ++++----- src/api/v1beta1/componentConfig.go | 42 + src/api/v1beta1/component_test.go | 14 +- src/api/v1beta1/package.go | 160 +-- src/api/v1beta1/package_test.go | 43 +- src/pkg/schema/generate.go | 25 +- .../schema/zarf-v1beta1-component-schema.json | 998 ++++++++++++++++ src/pkg/schema/zarf-v1beta1-schema.json | 1008 +++++++---------- 8 files changed, 1713 insertions(+), 1092 deletions(-) create mode 100644 src/api/v1beta1/componentConfig.go create mode 100644 src/pkg/schema/zarf-v1beta1-component-schema.json diff --git a/src/api/v1beta1/component.go b/src/api/v1beta1/component.go index e6fda8f61d..6627332818 100644 --- a/src/api/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -1,76 +1,40 @@ // SPDX-License-Identifier: Apache-2.0 // SPDX-FileCopyrightText: 2021-Present The Zarf Authors -// Package v1beta1 holds the definition of the v1beta1 Zarf Package package v1beta1 -import ( - "github.com/zarf-dev/zarf/src/api/v1alpha1" - metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" -) - -// ZarfComponent is the primary functional grouping of assets to deploy by Zarf. -type ZarfComponent struct { +// Component is the primary functional grouping of assets to deploy by Zarf. +type Component struct { // The name of the component. Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"` - // Message to include during package deploy describing the purpose of this component. Description string `json:"description,omitempty"` - - // Determines the default Y/N state for installing this component on package deploy. - Default bool `json:"default,omitempty"` - - // Do not prompt user to install this component. Defaults to false, meaning the component is required. - Optional *bool `json:"optional,omitempty"` - + // Do not install this component unless explicitly requested. Defaults to false, meaning the component is required. + Optional bool `json:"optional,omitempty"` // Filter when this component is included in package creation or deployment. - Only ZarfComponentOnlyTarget `json:"only,omitempty"` - + Target ComponentTarget `json:"target,omitempty"` // Import a component from another Zarf component config. - Import ZarfComponentImport `json:"import,omitempty"` - - // Features of the Zarf CLI to enable for this component. - Features ZarfComponentFeatures `json:"features,omitempty"` - + Import ComponentImport `json:"import,omitempty"` + // The Zarf CLI service this component provides, such as the registry, injector, or agent. + Service Service `json:"service,omitempty" jsonschema:"enum=registry,enum=seed-registry,enum=injector,enum=agent,enum=git-server"` // Kubernetes manifests to be included in a generated Helm chart on package deploy. - Manifests []ZarfManifest `json:"manifests,omitempty"` - + Manifests []Manifest `json:"manifests,omitempty"` // Helm charts to install during package deploy. - Charts []ZarfChart `json:"charts,omitempty"` - + Charts []Chart `json:"charts,omitempty"` // Files or folders to place on disk during package deployment. - Files []ZarfFile `json:"files,omitempty"` - + Files []File `json:"files,omitempty"` // List of OCI images to include in the package. - Images []ZarfImage `json:"images,omitempty"` - + Images []Image `json:"images,omitempty"` // List of tar archives of images to include in the package. ImageArchives []ImageArchive `json:"imageArchives,omitempty"` - - // List of git repos to include in the package. - Repos []string `json:"repos,omitempty"` - + // List of git repositories to include in the package. + Repositories []string `json:"repositories,omitempty"` // Custom commands to run at various stages of a package lifecycle. - Actions ZarfComponentActions `json:"actions,omitempty"` - - // Datasets to inject into a container in the target cluster. - // This field is not part of the v1beta1 schema but is kept as a backwards compatibility shim so v1alpha1 packages can be losslessly - // converted to v1beta1 for packager logic. - dataInjections []v1alpha1.ZarfDataInjection -} - -// SetDataInjections allows setting data injections for lossless v1alpha1 conversions -func (c *ZarfComponent) SetDataInjections(dataInjections []v1alpha1.ZarfDataInjection) { - c.dataInjections = dataInjections -} - -// GetDataInjections is a shim to retrieving data injections when set for lossless v1alpha1 conversions -func (c ZarfComponent) GetDataInjections() []v1alpha1.ZarfDataInjection { - return c.dataInjections + Actions ComponentActions `json:"actions,omitempty"` } // GetImages returns all image names specified in the component, including those from ImageArchives. -func (c ZarfComponent) GetImages() []string { +func (c Component) GetImages() []string { images := []string{} for _, img := range c.Images { images = append(images, img.Name) @@ -81,218 +45,197 @@ func (c ZarfComponent) GetImages() []string { return images } -// RequiresCluster returns if the component requires a cluster connection to deploy. -func (c ZarfComponent) RequiresCluster() bool { - hasImages := len(c.Images) > 0 - hasCharts := len(c.Charts) > 0 - hasManifests := len(c.Manifests) > 0 - hasRepos := len(c.Repos) > 0 - - if hasImages || hasCharts || hasManifests || hasRepos { - return true - } - - return false -} - -// IsOptional returns if the component is optional. -func (c ZarfComponent) IsOptional() bool { - if c.Optional == nil { - return false - } - return *c.Optional +// RequiresCluster returns true if the component requires a cluster connection to deploy. +func (c Component) RequiresCluster() bool { + return len(c.Images) > 0 || len(c.Charts) > 0 || len(c.Manifests) > 0 || len(c.Repositories) > 0 } -// ZarfComponentOnlyTarget filters a component to only show it for a given local OS and cluster. -type ZarfComponentOnlyTarget struct { +// ComponentTarget filters a component to only apply for a given local OS, architecture, or flavor. +type ComponentTarget struct { // Only deploy component to specified OS. - LocalOS string `json:"localOS,omitempty" jsonschema:"enum=linux,enum=darwin,enum=windows"` - // Only deploy component to specified clusters. - Cluster ZarfComponentOnlyCluster `json:"cluster,omitempty"` + OS string `json:"os,omitempty" jsonschema:"enum=linux,enum=darwin,enum=windows"` + // Only include component for the given package architecture. + Architecture string `json:"architecture,omitempty" jsonschema:"enum=amd64,enum=arm64"` // Only include this component when a matching '--flavor' is specified on 'zarf package create'. Flavor string `json:"flavor,omitempty"` } -// ZarfComponentOnlyCluster represents the architecture and K8s cluster distribution to filter on. -type ZarfComponentOnlyCluster struct { - // Only create and deploy to clusters of the given architecture. - Architecture string `json:"architecture,omitempty" jsonschema:"enum=amd64,enum=arm64"` - // A list of kubernetes distros this package works with (Reserved for future use). - Distros []string `json:"distros,omitempty" jsonschema:"example=k3s,example=eks"` +// ComponentImport is a reference to imported Zarf component configs. +type ComponentImport struct { + // Local file path references to component config files to import. + Local []ComponentImportLocal `json:"local,omitempty"` + // OCI URL references to remote component config files to import; pulled at create time. + Remote []ComponentImportRemote `json:"remote,omitempty"` } -// ZarfFile defines a file to deploy. -type ZarfFile struct { - // Local folder or file path or remote URL to pull into the package. - Source string `json:"source"` - // (files only) Optional SHA256 checksum of the file. - Shasum string `json:"shasum,omitempty"` - // The absolute or relative path where the file or folder should be copied to during package deploy. - Target string `json:"target"` - // (files only) Determines if the file should be made executable during package deploy. - Executable bool `json:"executable,omitempty"` - // List of symlinks to create during package deploy. - Symlinks []string `json:"symlinks,omitempty"` - // Local folder or file to be extracted from a 'source' archive. - ExtractPath string `json:"extractPath,omitempty"` - // Template enables go-template processing on this file during deploy. - Template *bool `json:"template,omitempty"` +// ComponentImportLocal is a local file path reference to a component config. +type ComponentImportLocal struct { + // The local file path to the component config. + Path string `json:"path"` } -// ShouldTemplate returns whether go-template processing is enabled for this file. -func (f ZarfFile) ShouldTemplate() bool { - if f.Template != nil { - return *f.Template - } - return false +// ComponentImportRemote is a remote OCI URL reference to a component config. +type ComponentImportRemote struct { + // The OCI URL of the remote component config. + URL string `json:"url"` +} + +// Service identifies which Zarf CLI service a component provides. +type Service string + +const ( + // ServiceRegistry indicates a component that provides the in-cluster registry. + ServiceRegistry Service = "registry" + // ServiceSeedRegistry indicates a component that provides the seed registry used during init. + ServiceSeedRegistry Service = "seed-registry" + // ServiceInjector indicates a component that provides the Zarf injector. + ServiceInjector Service = "injector" + // ServiceAgent indicates a component that provides the Zarf agent. + ServiceAgent Service = "agent" + // ServiceGitServer indicates a component that provides the in-cluster git server. + ServiceGitServer Service = "git-server" +) + +// ServerSideApplyMode controls when server-side apply is used during deploy. +type ServerSideApplyMode string + +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" +) + +// KustomizeManifest defines kustomization settings for a manifest. +type KustomizeManifest struct { + // List of local kustomization paths or remote URLs to include in the package. + Files []string `json:"files,omitempty"` + // Allow traversing directory above the current directory if needed for kustomization. + AllowAnyDirectory bool `json:"allowAnyDirectory,omitempty"` + // Enable kustomize plugins when building manifests. + EnablePlugins bool `json:"enablePlugins,omitempty"` } -// ZarfChart defines a helm chart to be deployed. -type ZarfChart struct { - // The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repo. +// Manifest defines raw manifests Zarf will deploy as a helm chart. +type Manifest struct { + // A name to give this collection of manifests; this will become the name of the dynamically-created helm chart. + Name string `json:"name" jsonschema:"maxLength=40"` + // The namespace to deploy the manifests to. + Namespace string `json:"namespace,omitempty"` + // List of local K8s YAML files or remote URLs to deploy (in order). + Files []string `json:"files,omitempty"` + // Kustomize settings for this manifest. + Kustomize *KustomizeManifest `json:"kustomize,omitempty"` + // Whether to skip waiting for manifest resources to be ready before continuing. + SkipWait bool `json:"skipWait,omitempty"` + // Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy. Defaults to "auto" when omitted. + ServerSideApply ServerSideApplyMode `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"` + // EnableValues enables go-template processing on these manifests during deploy. + EnableValues bool `json:"enableValues,omitempty"` +} + +// Chart defines a helm chart to be deployed. +type Chart struct { + // The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repository. Name string `json:"name"` - // The version of the chart. This field is not part of the v1beta1 schema but is kept - // as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1. + // The version of the chart. This field is removed from the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1. version string - // The Helm repo where the chart is stored. - HelmRepo HelmRepoSource `json:"helmRepo,omitempty"` - // The Git repo where the chart is stored. - Git GitRepoSource `json:"git,omitempty"` + // The Helm repository where the chart is stored. + HelmRepository *HelmRepositorySource `json:"helmRepository,omitempty"` + // The Git repository where the chart is stored. + Git *GitSource `json:"git,omitempty"` // The local path where the chart is stored. - Local LocalRepoSource `json:"local,omitempty"` + Local *LocalSource `json:"local,omitempty"` // The OCI registry where the chart is stored. - OCI OCISource `json:"oci,omitempty"` + OCI *OCISource `json:"oci,omitempty"` // The namespace to deploy the chart to. Namespace string `json:"namespace,omitempty"` // The name of the Helm release to create (defaults to the Zarf name of the chart). ReleaseName string `json:"releaseName,omitempty"` - // Whether to wait for chart resources to be ready before continuing. Defaults to true. - Wait *bool `json:"wait,omitempty"` + // Whether to skip waiting for chart resources to be ready before continuing. + SkipWait bool `json:"skipWait,omitempty"` // List of local values file paths or remote URLs to include in the package; these will be merged together when deployed. ValuesFiles []string `json:"valuesFiles,omitempty"` - // List of values sources to their Helm override target. - Values []ZarfChartValue `json:"values,omitempty"` - // Whether to validate the chart's values against its JSON schema. Defaults to true. - SchemaValidation *bool `json:"schemaValidation,omitempty"` - // Controls whether Helm uses Server-Side Apply (SSA) or client-side apply (CSA) when deploying this chart. - // - "true": always use SSA - // - "false": always use CSA - // - "auto": use SSA for fresh installs; for upgrades, match whichever strategy - // was used when the chart was first installed - // Defaults to "auto" when omitted. - ServerSideApply string `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"` -} - -// ShouldRunSchemaValidation returns whether Helm schema validation should run. -func (zc ZarfChart) ShouldRunSchemaValidation() bool { - if zc.SchemaValidation != nil { - return *zc.SchemaValidation - } - return true -} - -// GetServerSideApply returns server side apply with default of "auto" if it is not set -func (zc ZarfChart) GetServerSideApply() string { - if zc.ServerSideApply == "" { - return "auto" - } - return zc.ServerSideApply + // List of value sources mapped to their Helm override targets. + Values []ChartValue `json:"values,omitempty"` + // Skip validation of the chart's values against its JSON schema. Defaults to false. + SkipSchemaValidation bool `json:"skipSchemaValidation,omitempty"` + // Controls whether Helm uses Server-Side Apply (SSA) or client-side apply (CSA) when deploying this chart. Defaults to "auto" when omitted. + ServerSideApply ServerSideApplyMode `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"` } -// GetDeprecatedVersion gets the version of the chart, used as a backwards compatibility shim with v1alpha1. -func (zc ZarfChart) GetDeprecatedVersion() string { - return zc.version +// GetDeprecatedVersion returns the deprecated top-level chart version, used as a v1alpha1 backwards-compatibility shim. +func (c Chart) GetDeprecatedVersion() string { + return c.version } -// SetDeprecatedVersion sets the version of the chart, used as a backwards compatibility shim with v1alpha1. -// This function will be deleted when v1alpha1 packages are no longer deployable -func (zc *ZarfChart) SetDeprecatedVersion(version string) { - zc.version = version +// SetDeprecatedVersion sets the deprecated top-level chart version, used as a v1alpha1 backwards-compatibility shim. +func (c *Chart) SetDeprecatedVersion(version string) { + c.version = version } -// ZarfChartValue maps a values source path to a Helm chart target path. -type ZarfChartValue struct { +// ChartValue maps a values source path to a Helm chart target path. +type ChartValue struct { // The source path for the value. SourcePath string `json:"sourcePath"` // The target path within the Helm chart values. TargetPath string `json:"targetPath"` } -// HelmRepoSource represents a Helm chart stored in a Helm repository. -type HelmRepoSource struct { - // The name of a chart within a Helm repository (defaults to the Zarf name of the chart). +// HelmRepositorySource represents a Helm chart stored in a Helm repository. +type HelmRepositorySource struct { + // The name of a chart within a Helm repository. Name string `json:"name,omitempty"` - // The URL of the chart repository where the helm chart is stored. + // The URL of the chart repository where the Helm chart is stored. URL string `json:"url"` - // The version of the chart to deploy. + // The version of the chart in the Helm repository. Version string `json:"version"` } -// GitRepoSource represents a Helm chart stored in a Git repository. -type GitRepoSource struct { - // The URL of the git repository where the helm chart is stored. +// GitSource represents a Helm chart stored in a Git repository. +type GitSource struct { + // The URL of the Git repository where the Helm chart is stored. URL string `json:"url"` - // The sub directory to the chart within a git repo. + // The subdirectory containing the chart within a Git repo. Path string `json:"path,omitempty"` } -// LocalRepoSource represents a Helm chart stored locally. -type LocalRepoSource struct { +// LocalSource represents a Helm chart stored locally. +type LocalSource struct { // The path to a local chart's folder or .tgz archive. Path string `json:"path"` } // OCISource represents a Helm chart stored in an OCI registry. type OCISource struct { - // The URL of the OCI registry where the helm chart is stored. + // The URL of the OCI registry where the Helm chart is stored. URL string `json:"url"` - // The version of the chart to deploy. + // The version of the chart in the OCI registry. Version string `json:"version"` } -// ZarfManifest defines raw manifests Zarf will deploy as a helm chart. -type ZarfManifest struct { - // A name to give this collection of manifests; this will become the name of the dynamically-created helm chart. - Name string `json:"name"` - // The namespace to deploy the manifests to. - Namespace string `json:"namespace,omitempty"` - // List of local K8s YAML files or remote URLs to deploy (in order). - Files []string `json:"files,omitempty"` - // Allow traversing directory above the current directory if needed for kustomization. (Defaults to false) - KustomizeAllowAnyDirectory bool `json:"kustomizeAllowAnyDirectory,omitempty"` - // List of local kustomization paths or remote URLs to include in the package. - Kustomizations []string `json:"kustomizations,omitempty"` - // Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy. - // - "true": always use SSA - // - "false": always use CSA - // - "auto": use SSA for fresh installs; for upgrades, match whichever strategy - // was used when the chart was first installed - // Defaults to "auto" when omitted. - ServerSideApply string `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"` - // Whether to wait for manifest resources to be ready before continuing. Defaults to true. - Wait *bool `json:"wait,omitempty"` - // Template enables go-template processing on these manifests during deploy. - Template *bool `json:"template,omitempty"` -} - -// ShouldTemplate returns whether go-template processing is enabled for this manifest. -func (m ZarfManifest) ShouldTemplate() bool { - if m.Template != nil { - return *m.Template - } - return false -} - -// GetServerSideApply returns server side apply with default of "auto" if it is not set -func (m ZarfManifest) GetServerSideApply() string { - if m.ServerSideApply == "" { - return "auto" - } - return m.ServerSideApply +// File defines a file to deploy. +type File struct { + // Local folder or file path or remote URL to pull into the package. + Source string `json:"source"` + // Optional checksum of the file in the format : (e.g. sha256:abc123). Defaults to sha256 if no algorithm is specified. + Checksum string `json:"checksum,omitempty"` + // The absolute or relative path where the file or folder should be copied to during package deploy. + Destination string `json:"destination"` + // Determines if the file should be made executable during package deploy. + Executable bool `json:"executable,omitempty"` + // List of symlinks to create during package deploy. + Symlinks []string `json:"symlinks,omitempty"` + // Local folder or file to be extracted from a 'source' archive. + ExtractPath string `json:"extractPath,omitempty"` + // EnableValues enables go-template processing on this file during deploy. + EnableValues bool `json:"enableValues,omitempty"` } -// ZarfImage defines an OCI image to include in the package. -type ZarfImage struct { +// Image defines an OCI image to include in the package. +type Image struct { // The image reference. Name string `json:"name"` // The source to pull the image from. Defaults to "registry". @@ -307,115 +250,81 @@ type ImageArchive struct { Images []string `json:"images"` } -// ZarfComponentFeatures defines features of the Zarf CLI to enable for a component. -type ZarfComponentFeatures struct { - // Whether this component provides a registry. - IsRegistry bool `json:"isRegistry,omitempty"` - // Injector configuration for the component. - Injector *Injector `json:"injector,omitempty"` - // Whether this component provides an agent. - IsAgent bool `json:"isAgent,omitempty"` -} - -// Injector defines the configuration for the Zarf injector. -type Injector struct { - // Whether the injector is enabled. - Enabled bool `json:"enabled"` - // Values for the injector. - Values *InjectorValues `json:"values,omitempty"` -} - -// InjectorValues defines configurable values for the Zarf injector. -type InjectorValues struct { - // Tolerations for the injector pod. - Tolerations string `json:"tolerations,omitempty"` -} - -// ZarfComponentActions are ActionSets that map to different zarf package operations. -type ZarfComponentActions struct { +// ComponentActions are ActionSets that map to different Zarf package operations. +type ComponentActions struct { // Actions to run during package creation. - OnCreate ZarfComponentActionSet `json:"onCreate,omitempty"` + OnCreate ComponentActionSet `json:"onCreate,omitempty"` // Actions to run during package deployment. - OnDeploy ZarfComponentActionSet `json:"onDeploy,omitempty"` + OnDeploy ComponentActionSet `json:"onDeploy,omitempty"` // Actions to run during package removal. - OnRemove ZarfComponentActionSet `json:"onRemove,omitempty"` + OnRemove ComponentActionSet `json:"onRemove,omitempty"` } -// ZarfComponentActionSet is a set of actions to run during a zarf package operation. -type ZarfComponentActionSet struct { +// ComponentActionSet is a set of actions to run during a Zarf package operation. +type ComponentActionSet struct { // Default configuration for all actions in this set. - Defaults ZarfComponentActionDefaults `json:"defaults,omitempty"` + Defaults ComponentActionDefaults `json:"defaults,omitempty"` // Actions to run at the start of an operation. - Before []ZarfComponentAction `json:"before,omitempty"` - // Actions to run at the end of an operation. - After []ZarfComponentAction `json:"after,omitempty"` - // Actions to run if all operations fail. - OnFailure []ZarfComponentAction `json:"onFailure,omitempty"` + Before []ComponentAction `json:"before,omitempty"` + // Actions to run at the end of an operation if it succeeds. + OnSuccess []ComponentAction `json:"onSuccess,omitempty"` + // Actions to run if any operation in this set fails. + OnFailure []ComponentAction `json:"onFailure,omitempty"` } -// ZarfComponentActionDefaults sets the default configs for child actions. -type ZarfComponentActionDefaults struct { +// ComponentActionDefaults sets the default configs for child actions. +type ComponentActionDefaults struct { // Hide the output of commands during execution (default false). - Mute bool `json:"mute,omitempty"` - // Default timeout for commands (default no timeout). - Timeout *metav1.Duration `json:"timeout,omitempty"` - // Retry commands given number of times if they fail (default 0). - Retries int `json:"retries,omitempty"` + Silent bool `json:"silent,omitempty"` + // Default timeout in seconds for commands (default 0, no timeout). + MaxTotalSeconds int32 `json:"maxTotalSeconds,omitempty"` + // Retry commands a given number of times if they fail (default 0). + Retries int32 `json:"retries,omitempty"` // Working directory for commands (default CWD). Dir string `json:"dir,omitempty"` // Additional environment variables for commands. Env []string `json:"env,omitempty"` - // (cmd only) Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems. + // Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems. Shell Shell `json:"shell,omitempty"` } -// ZarfComponentAction represents a single action to run during a zarf package operation. -type ZarfComponentAction struct { +// ComponentAction represents a single action to run during a Zarf package operation. +type ComponentAction struct { // Hide the output of the command during package deployment (default false). - Mute *bool `json:"mute,omitempty"` - // Timeout for the command (default to 0, no timeout for cmd actions and 5 minutes for wait actions). - Timeout *metav1.Duration `json:"timeout,omitempty"` - // Retry the command if it fails up to given number of times (default 0). - Retries int `json:"retries,omitempty"` + Silent *bool `json:"silent,omitempty"` + // Timeout in seconds for the command (default 0, no timeout for cmd actions and 300, 5 minutes for wait actions). + MaxTotalSeconds *int32 `json:"maxTotalSeconds,omitempty"` + // Retry the command if it fails up to a given number of times (default 0). + Retries *int32 `json:"retries,omitempty"` // The working directory to run the command in (default is CWD). Dir *string `json:"dir,omitempty"` // Additional environment variables to set for the command. Env []string `json:"env,omitempty"` // The command to run. Must specify either cmd or wait for the action to do anything. Cmd string `json:"cmd,omitempty"` - // (cmd only) Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems. + // Indicates a preference for a shell for the provided cmd. Shell *Shell `json:"shell,omitempty"` - // (onDeploy/cmd only) An array of variables to update with the output of the command. These variables will be available to all remaining actions and components in the package. - SetVariables []Variable `json:"setVariables,omitempty"` // An array of values to set with the output of the command. SetValues []SetValue `json:"setValues,omitempty"` // Description of the action to be displayed during package execution instead of the command. Description string `json:"description,omitempty"` - // Wait for a condition to be met before continuing. Must specify either cmd or wait for the action. See the 'zarf tools wait-for' command for more info. - Wait *ZarfComponentActionWait `json:"wait,omitempty"` - // Disable go-template processing on the cmd field. - Template *bool `json:"template,omitempty"` -} - -// ShouldTemplate returns whether the action should have go-template processing. -func (a ZarfComponentAction) ShouldTemplate() bool { - if a.Template != nil { - return *a.Template - } - return false + // Wait for a condition to be met before continuing. + Wait *ComponentActionWait `json:"wait,omitempty"` + // EnableValues enables go-template processing on the cmd field. + EnableValues bool `json:"enableValues,omitempty"` } // SetValueType declares the expected input back from the cmd, allowing structured data to be parsed. type SetValueType string -// SetValueYAML enables YAML parsing. -var SetValueYAML = SetValueType("yaml") - -// SetValueJSON enables JSON parsing. -var SetValueJSON = SetValueType("json") - -// SetValueString sets the raw value. -var SetValueString = SetValueType("string") +const ( + // SetValueYAML enables YAML parsing. + SetValueYAML SetValueType = "yaml" + // SetValueJSON enables JSON parsing. + SetValueJSON SetValueType = "json" + // SetValueString sets the raw value. + SetValueString SetValueType = "string" +) // SetValue declares a value that can be set during a package deploy. type SetValue struct { @@ -423,21 +332,20 @@ type SetValue struct { Key string `json:"key,omitempty"` // Value is the current value at the key. Value any `json:"value,omitempty"` - // Type declares the kind of data being stored in the value. JSON and YAML types ensure proper formatting when - // inserting the value into the template. Defaults to SetValueString behavior when empty. + // Type declares the kind of data being stored in the value. Type SetValueType `json:"type,omitempty"` } -// ZarfComponentActionWait specifies a condition to wait for before continuing -type ZarfComponentActionWait struct { +// ComponentActionWait specifies a condition to wait for before continuing. +type ComponentActionWait struct { // Wait for a condition to be met in the cluster before continuing. Only one of cluster or network can be specified. - Cluster *ZarfComponentActionWaitCluster `json:"cluster,omitempty"` + Cluster *ComponentActionWaitCluster `json:"cluster,omitempty"` // Wait for a condition to be met on the network before continuing. Only one of cluster or network can be specified. - Network *ZarfComponentActionWaitNetwork `json:"network,omitempty"` + Network *ComponentActionWaitNetwork `json:"network,omitempty"` } -// ZarfComponentActionWaitCluster specifies a condition to wait for before continuing -type ZarfComponentActionWaitCluster struct { +// ComponentActionWaitCluster specifies a cluster-level condition to wait for. +type ComponentActionWaitCluster struct { // The kind of resource to wait for. Kind string `json:"kind" jsonschema:"example=Pod,example=Deployment"` // The name of the resource or selector to wait for. @@ -448,27 +356,22 @@ type ZarfComponentActionWaitCluster struct { Condition string `json:"condition,omitempty" jsonschema:"example=Available,'{.status.availableReplicas}'=23"` } -// ZarfComponentActionWaitNetwork specifies a condition to wait for before continuing -type ZarfComponentActionWaitNetwork struct { +// ComponentActionWaitNetwork specifies a network-level condition to wait for. +type ComponentActionWaitNetwork struct { // The protocol to wait for. Protocol string `json:"protocol" jsonschema:"enum=tcp,enum=http,enum=https"` // The address to wait for. Address string `json:"address" jsonschema:"example=localhost:8080,example=1.1.1.1"` // The HTTP status code to wait for if using http or https. - Code int `json:"code,omitempty" jsonschema:"example=200,example=404"` -} - -// ZarfComponentImport structure for including imported Zarf components. -type ZarfComponentImport struct { - // The path to the component config file to import. - Path string `json:"path,omitempty"` - // The URL to a Zarf component config to import via OCI. - URL string `json:"url,omitempty" jsonschema:"pattern=^oci://.*$"` + Code int32 `json:"code,omitempty" jsonschema:"example=200,example=404"` } -// Shell represents the desired shell to use for a given command +// Shell represents the desired shell to use for a given command. type Shell struct { - Windows string `json:"windows,omitempty" jsonschema:"description=(default 'powershell') Indicates a preference for the shell to use on Windows systems (note that choosing 'cmd' will turn off migrations like touch -> New-Item),example=powershell,example=cmd,example=pwsh,example=sh,example=bash,example=gsh"` - Linux string `json:"linux,omitempty" jsonschema:"description=(default 'sh') Indicates a preference for the shell to use on Linux systems,example=sh,example=bash,example=fish,example=zsh,example=pwsh"` - Darwin string `json:"darwin,omitempty" jsonschema:"description=(default 'sh') Indicates a preference for the shell to use on macOS systems,example=sh,example=bash,example=fish,example=zsh,example=pwsh"` + // Windows shell preference. + Windows string `json:"windows,omitempty" jsonschema:"example=powershell,example=cmd,example=pwsh"` + // Linux shell preference. + Linux string `json:"linux,omitempty" jsonschema:"example=sh,example=bash,example=zsh"` + // Darwin (macOS) shell preference. + Darwin string `json:"darwin,omitempty" jsonschema:"example=sh,example=bash,example=zsh"` } diff --git a/src/api/v1beta1/componentConfig.go b/src/api/v1beta1/componentConfig.go new file mode 100644 index 0000000000..a3ad00cdcb --- /dev/null +++ b/src/api/v1beta1/componentConfig.go @@ -0,0 +1,42 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: 2021-Present The Zarf Authors + +package v1beta1 + +// ComponentConfig is the top-level structure of a Zarf component config file. +type ComponentConfig struct { + // The API version of the component config. + APIVersion string `json:"apiVersion" jsonschema:"enum=zarf.dev/v1beta1"` + // The kind of component config. + Kind PackageKind `json:"kind" jsonschema:"enum=ZarfComponentConfig,default=ZarfComponentConfig"` + // Component metadata. + Metadata ComponentMetadata `json:"metadata"` + // The single component this config defines. + Component Component `json:"component"` + // Values imports Zarf values files for templating and overriding Helm values. + Values Values `json:"values,omitempty"` + // Zarf-generated publish data for the component config. + PublishData ComponentPublishData `json:"publishData,omitempty"` +} + +// ComponentMetadata holds metadata about a component config. +type ComponentMetadata struct { + // Name to identify this component config. + Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"` + // Additional information about this component config. + Description string `json:"description,omitempty"` + // Generic string to track the component config version. + Version string `json:"version,omitempty"` + // Annotations contains arbitrary metadata about the component config. + Annotations map[string]string `json:"annotations,omitempty"` +} + +// ComponentPublishData is written during publish to track details of the component config. +type ComponentPublishData struct { + // The version of Zarf used to build this component config. + ZarfVersion string `json:"zarfVersion"` + // Any migrations that have been run on this component config. + Migrations []string `json:"migrations,omitempty"` + // Requirements for specific package operations. + VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"` +} diff --git a/src/api/v1beta1/component_test.go b/src/api/v1beta1/component_test.go index baeff3eb97..abc2a87002 100644 --- a/src/api/v1beta1/component_test.go +++ b/src/api/v1beta1/component_test.go @@ -14,21 +14,21 @@ func TestGetImages(t *testing.T) { tests := []struct { name string - component ZarfComponent + component Component expected []string }{ { name: "no images", - component: ZarfComponent{ + component: Component{ Name: "test-component", }, expected: []string{}, }, { name: "only Images field", - component: ZarfComponent{ + component: Component{ Name: "test-component", - Images: []ZarfImage{ + Images: []Image{ {Name: "docker.io/library/nginx:latest"}, {Name: "ghcr.io/zarf-dev/zarf:v0.32.6"}, }, @@ -40,7 +40,7 @@ func TestGetImages(t *testing.T) { }, { name: "only ImageArchives with images", - component: ZarfComponent{ + component: Component{ Name: "test-component", ImageArchives: []ImageArchive{ { @@ -59,9 +59,9 @@ func TestGetImages(t *testing.T) { }, { name: "both Images and ImageArchives", - component: ZarfComponent{ + component: Component{ Name: "test-component", - Images: []ZarfImage{ + Images: []Image{ {Name: "docker.io/library/nginx:latest"}, }, ImageArchives: []ImageArchive{ diff --git a/src/api/v1beta1/package.go b/src/api/v1beta1/package.go index 5c8b3e4f20..d9ed682f42 100644 --- a/src/api/v1beta1/package.go +++ b/src/api/v1beta1/package.go @@ -1,74 +1,41 @@ // SPDX-License-Identifier: Apache-2.0 // SPDX-FileCopyrightText: 2021-Present The Zarf Authors -// Package v1beta1 holds the definition of the v1beta1 Zarf Package. This API is work in progress and not yet used within Zarf +// Package v1beta1 holds the definition of the v1beta1 Zarf Package. This API is work in progress and not yet used within Zarf. package v1beta1 -import ( - "fmt" - "regexp" -) - -// VariableType represents a type of a Zarf package variable -type VariableType string +// PackageKind is an enum of the different kinds of Zarf packages. +type PackageKind string const ( - // RawVariableType is the default type for a Zarf package variable - RawVariableType VariableType = "raw" - // FileVariableType is a type for a Zarf package variable that loads its contents from a file - FileVariableType VariableType = "file" -) - -// ZarfPackageKind is an enum of the different kinds of Zarf packages. -type ZarfPackageKind string - -const ( - // ZarfInitConfig is the kind of Zarf package used during `zarf init`. - ZarfInitConfig ZarfPackageKind = "ZarfInitConfig" - // ZarfPackageConfig is the default kind of Zarf package, primarily used during `zarf package`. - ZarfPackageConfig ZarfPackageKind = "ZarfPackageConfig" - // APIVersion the api version of this package. + // ZarfPackageConfig is the default kind of Zarf package. + ZarfPackageConfig PackageKind = "ZarfPackageConfig" + // ZarfComponentConfig is the kind of a Zarf component config file. + ZarfComponentConfig PackageKind = "ZarfComponentConfig" + // APIVersion is the api version of this package. APIVersion string = "zarf.dev/v1beta1" ) -// ZarfPackage the top-level structure of a Zarf config file. -type ZarfPackage struct { +// Package is the top-level structure of a Zarf package definition. +type Package struct { // The API version of the Zarf package. - APIVersion string `json:"apiVersion,omitempty" jsonschema:"enum=zarf.dev/v1beta1"` + APIVersion string `json:"apiVersion" jsonschema:"enum=zarf.dev/v1beta1"` // The kind of Zarf package. - Kind ZarfPackageKind `json:"kind" jsonschema:"enum=ZarfInitConfig,enum=ZarfPackageConfig,default=ZarfPackageConfig"` + Kind PackageKind `json:"kind" jsonschema:"enum=ZarfPackageConfig"` // Package metadata. - Metadata ZarfMetadata `json:"metadata,omitempty"` + Metadata PackageMetadata `json:"metadata,omitempty"` // Zarf-generated package build data. - Build ZarfBuildData `json:"build,omitempty"` + Build BuildData `json:"build,omitempty"` // List of components to deploy in this package. - Components []ZarfComponent `json:"components"` - // Constant template values applied on deploy for K8s resources. - Constants []Constant `json:"constants,omitempty"` - // Variable template values applied on deploy for K8s resources. - Variables []InteractiveVariable `json:"variables,omitempty"` - // Values imports Zarf values files for templating. - Values ZarfValues `json:"values,omitempty"` - // Documentation files. + Components []Component `json:"components" jsonschema:"minItems=1"` + // Values imports Zarf values files for templating and overriding Helm values. + Values Values `json:"values,omitempty"` + // Documentation files included in the package. Documentation map[string]string `json:"documentation,omitempty"` } -// IsInitConfig returns whether a Zarf package is an init config. -func (pkg ZarfPackage) IsInitConfig() bool { - return pkg.Kind == ZarfInitConfig -} - -// AllowsNamespaceOverride returns whether the package allows the namespace to be overridden -func (pkg ZarfPackage) AllowsNamespaceOverride() bool { - if pkg.Metadata.AllowNamespaceOverride != nil { - return *pkg.Metadata.AllowNamespaceOverride - } - // defaulting to allowing package namespace to be overridden - return true -} - // HasImages returns true if one of the components contains an image. -func (pkg ZarfPackage) HasImages() bool { +func (pkg Package) HasImages() bool { for _, component := range pkg.Components { if len(component.Images) > 0 { return true @@ -78,7 +45,7 @@ func (pkg ZarfPackage) HasImages() bool { } // IsSBOMAble checks if a package has contents that an SBOM can be created on (i.e. images, files, or image archives). -func (pkg ZarfPackage) IsSBOMAble() bool { +func (pkg Package) IsSBOMAble() bool { for _, c := range pkg.Components { if len(c.Images) > 0 || len(c.Files) > 0 || len(c.ImageArchives) > 0 { return true @@ -87,67 +54,13 @@ func (pkg ZarfPackage) IsSBOMAble() bool { return false } -// Variable represents a variable that has a value set programmatically -type Variable struct { - // The name to be used for the variable - Name string `json:"name" jsonschema:"pattern=^[A-Z0-9_]+$"` - // Whether to mark this variable as sensitive to not print it in the log - Sensitive bool `json:"sensitive,omitempty"` - // Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARF_VAR_. - AutoIndent bool `json:"autoIndent,omitempty"` - // An optional regex pattern that a variable value must match before a package deployment can continue. - Pattern string `json:"pattern,omitempty"` - // Changes the handling of a variable to load contents differently (i.e. from a file rather than as a raw variable - templated files should be kept below 1 MiB) - Type VariableType `json:"type,omitempty" jsonschema:"enum=raw,enum=file"` -} - -// InteractiveVariable is a variable that can be used to prompt a user for more information -type InteractiveVariable struct { - Variable `json:",inline"` - // A description of the variable to be used when prompting the user a value - Description string `json:"description,omitempty"` - // The default value to use for the variable - Default string `json:"default,omitempty"` - // Whether to prompt the user for input for this variable - Prompt bool `json:"prompt,omitempty"` -} - -// Constant are constants that can be used to dynamically template K8s resources or run in actions. -type Constant struct { - // The name to be used for the constant - Name string `json:"name" jsonschema:"pattern=^[A-Z0-9_]+$"` - // The value to set for the constant during deploy - Value string `json:"value"` - // A description of the constant to explain its purpose on package create or deploy confirmation prompts - Description string `json:"description,omitempty"` - // Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARF_CONST_. - AutoIndent bool `json:"autoIndent,omitempty"` - // An optional regex pattern that a constant value must match before a package can be created. - Pattern string `json:"pattern,omitempty"` -} - -// SetVariable tracks internal variables that have been set during this run of Zarf -type SetVariable struct { - Variable `json:",inline"` - // The value the variable is currently set with - Value string `json:"value"` -} - -// Validate runs all validation checks on a package constant. -func (c Constant) Validate() error { - if !regexp.MustCompile(c.Pattern).MatchString(c.Value) { - return fmt.Errorf("provided value for constant %s does not match pattern %s", c.Name, c.Pattern) - } - return nil -} - -// ZarfMetadata lists information about the current ZarfPackage. -type ZarfMetadata struct { +// PackageMetadata holds information about the package. +type PackageMetadata struct { // Name to identify this Zarf package. Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"` // Additional information about this Zarf package. Description string `json:"description,omitempty"` - // Generic string set by a package author to track the package version (Note: ZarfInitConfigs will always be versioned to the CLIVersion they were created with). + // Generic string set by a package author to track the package version. Version string `json:"version,omitempty"` // Disable compression of this package. Uncompressed bool `json:"uncompressed,omitempty"` @@ -155,14 +68,14 @@ type ZarfMetadata struct { Architecture string `json:"architecture,omitempty" jsonschema:"example=arm64,example=amd64"` // Annotations are key-value pairs that can be used to store metadata about the package. Annotations map[string]string `json:"annotations,omitempty"` - // Whether to allow namespace overrides for this package. - AllowNamespaceOverride *bool `json:"allowNamespaceOverride,omitempty"` + // Prevent namespace overrides for this package. + PreventNamespaceOverride bool `json:"preventNamespaceOverride,omitempty"` } -// ZarfBuildData is written during the packager.Create() operation to track details of the created package. -type ZarfBuildData struct { +// BuildData is written during package create to track details of the created package. +type BuildData struct { // The machine name that created this package. - Terminal string `json:"terminal,omitempty"` + Hostname string `json:"hostname,omitempty"` // The username who created this package. User string `json:"user,omitempty"` // The architecture this package was created on. @@ -177,21 +90,12 @@ type ZarfBuildData struct { RegistryOverrides map[string]string `json:"registryOverrides,omitempty"` // Whether this package was created with differential components. Differential bool `json:"differential,omitempty"` - // Version of a previously built package used as the basis for creating this differential package. - DifferentialPackageVersion string `json:"differentialPackageVersion,omitempty"` // The flavor of Zarf used to build this package. Flavor string `json:"flavor,omitempty"` - // Whether this package was signed. - Signed *bool `json:"signed,omitempty"` - // Checksum of a checksums.txt file that contains checksums all the layers within the package. - AggregateChecksum string `json:"aggregateChecksum,omitempty"` - // The API version defined in the package definition used to build the package. - APIVersion string `json:"apiVersion,omitempty"` // Requirements for specific Zarf versions needed to deploy this package. VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"` - // ProvenanceFiles lists files present in the package that are not included in checksums.txt. - // These are files added after checksum generation (e.g., signature files). - ProvenanceFiles []string `json:"provenanceFiles,omitempty"` + // Checksum of a checksums.txt file that contains checksums all the layers within the package. + AggregateChecksum string `json:"aggregateChecksum,omitempty"` } // VersionRequirement specifies a minimum Zarf version needed and the reason for the requirement. @@ -202,8 +106,8 @@ type VersionRequirement struct { Reason string `json:"reason"` } -// ZarfValues defines values files and schema for templating and overriding Helm values. -type ZarfValues struct { +// Values defines values files and schema for templating and overriding Helm values. +type Values struct { // List of values file paths to include. Files []string `json:"files,omitempty"` // Path to a JSON schema file for validating values. diff --git a/src/api/v1beta1/package_test.go b/src/api/v1beta1/package_test.go index 2ee1faa0fb..f5fa692dbe 100644 --- a/src/api/v1beta1/package_test.go +++ b/src/api/v1beta1/package_test.go @@ -9,48 +9,35 @@ import ( "github.com/stretchr/testify/require" ) -func TestZarfPackageIsInitPackage(t *testing.T) { +func TestPackageHasImages(t *testing.T) { t.Parallel() - pkg := ZarfPackage{ - Kind: ZarfInitConfig, - } - require.True(t, pkg.IsInitConfig()) - pkg = ZarfPackage{ - Kind: ZarfPackageConfig, - } - require.False(t, pkg.IsInitConfig()) -} - -func TestZarfPackageHasImages(t *testing.T) { - t.Parallel() - - pkg := ZarfPackage{ - Components: []ZarfComponent{ + pkg := Package{ + Components: []Component{ { Name: "without images", }, }, } require.False(t, pkg.HasImages()) - pkg = ZarfPackage{ - Components: []ZarfComponent{ + pkg = Package{ + Components: []Component{ { Name: "with images", - Images: []ZarfImage{{Name: "docker.io/library/alpine:latest"}}, + Images: []Image{{Name: "docker.io/library/alpine:latest"}}, }, }, } require.True(t, pkg.HasImages()) } -func TestZarfPackageIsSBOMable(t *testing.T) { +func TestPackageIsSBOMable(t *testing.T) { t.Parallel() tests := []struct { name string - images []ZarfImage - files []ZarfFile + images []Image + files []File imageArchives []ImageArchive expected bool }{ @@ -60,12 +47,12 @@ func TestZarfPackageIsSBOMable(t *testing.T) { }, { name: "only images", - images: []ZarfImage{{Name: "alpine"}}, + images: []Image{{Name: "alpine"}}, expected: true, }, { name: "only files", - files: []ZarfFile{{}}, + files: []File{{}}, expected: true, }, { @@ -75,8 +62,8 @@ func TestZarfPackageIsSBOMable(t *testing.T) { }, { name: "all three set", - images: []ZarfImage{{Name: "alpine"}}, - files: []ZarfFile{{}}, + images: []Image{{Name: "alpine"}}, + files: []File{{}}, imageArchives: []ImageArchive{{Path: "archive.tar", Images: []string{"img"}}}, expected: true, }, @@ -85,8 +72,8 @@ func TestZarfPackageIsSBOMable(t *testing.T) { t.Run(tt.name, func(t *testing.T) { t.Parallel() - pkg := ZarfPackage{ - Components: []ZarfComponent{ + pkg := Package{ + Components: []Component{ { Name: "test-component", Images: tt.images, diff --git a/src/pkg/schema/generate.go b/src/pkg/schema/generate.go index e6a7c98a0d..11165f4c31 100644 --- a/src/pkg/schema/generate.go +++ b/src/pkg/schema/generate.go @@ -19,35 +19,28 @@ import ( ) func main() { - if err := writeSchema("v1alpha1"); err != nil { + if err := writeSchema("v1alpha1", "zarf-v1alpha1-schema.json", &v1alpha1.ZarfPackage{}); err != nil { fmt.Println(err.Error()) os.Exit(1) } - if err := writeSchema("v1beta1"); err != nil { + if err := writeSchema("v1beta1", "zarf-v1beta1-schema.json", &v1beta1.Package{}); err != nil { + fmt.Println(err.Error()) + os.Exit(1) + } + if err := writeSchema("v1beta1", "zarf-v1beta1-component-schema.json", &v1beta1.ComponentConfig{}); err != nil { fmt.Println(err.Error()) os.Exit(1) } } -func writeSchema(apiVersion string) error { - var schema []byte - var err error - switch apiVersion { - case "v1alpha1": - schema, err = generateSchema("v1alpha1", &v1alpha1.ZarfPackage{}) - case "v1beta1": - schema, err = generateSchema("v1beta1", &v1beta1.ZarfPackage{}) - default: - return fmt.Errorf("unknown API version: %s", apiVersion) - } +func writeSchema(apiVersion, filename string, rootType any) error { + schema, err := generateSchema(apiVersion, rootType) if err != nil { - return fmt.Errorf("error generating %s schema: %w", apiVersion, err) + return fmt.Errorf("error generating %s schema: %w", filename, err) } - // Add trailing newline to match linter expectations schema = append(schema, '\n') - filename := fmt.Sprintf("zarf-%s-schema.json", apiVersion) if err := os.WriteFile(filename, schema, 0644); err != nil { return fmt.Errorf("error writing schema file: %w", err) } diff --git a/src/pkg/schema/zarf-v1beta1-component-schema.json b/src/pkg/schema/zarf-v1beta1-component-schema.json new file mode 100644 index 0000000000..194169dc0c --- /dev/null +++ b/src/pkg/schema/zarf-v1beta1-component-schema.json @@ -0,0 +1,998 @@ +{ + "$defs": { + "Chart": { + "additionalProperties": false, + "description": "Chart defines a helm chart to be deployed.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "git": { + "$ref": "#/$defs/GitSource", + "description": "The Git repository where the chart is stored." + }, + "helmRepository": { + "$ref": "#/$defs/HelmRepositorySource", + "description": "The Helm repository where the chart is stored." + }, + "local": { + "$ref": "#/$defs/LocalSource", + "description": "The local path where the chart is stored." + }, + "name": { + "description": "The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repository.", + "type": "string" + }, + "namespace": { + "description": "The namespace to deploy the chart to.", + "type": "string" + }, + "oci": { + "$ref": "#/$defs/OCISource", + "description": "The OCI registry where the chart is stored." + }, + "releaseName": { + "description": "The name of the Helm release to create (defaults to the Zarf name of the chart).", + "type": "string" + }, + "serverSideApply": { + "description": "Controls whether Helm uses Server-Side Apply (SSA) or client-side apply (CSA) when deploying this chart. Defaults to \"auto\" when omitted.", + "enum": [ + "true", + "false", + "auto" + ], + "type": "string" + }, + "skipSchemaValidation": { + "description": "Skip validation of the chart's values against its JSON schema. Defaults to false.", + "type": "boolean" + }, + "skipWait": { + "description": "Whether to skip waiting for chart resources to be ready before continuing.", + "type": "boolean" + }, + "values": { + "description": "List of value sources mapped to their Helm override targets.", + "items": { + "$ref": "#/$defs/ChartValue" + }, + "type": "array" + }, + "valuesFiles": { + "description": "List of local values file paths or remote URLs to include in the package; these will be merged together when deployed.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "ChartValue": { + "additionalProperties": false, + "description": "ChartValue maps a values source path to a Helm chart target path.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "sourcePath": { + "description": "The source path for the value.", + "type": "string" + }, + "targetPath": { + "description": "The target path within the Helm chart values.", + "type": "string" + } + }, + "required": [ + "sourcePath", + "targetPath" + ], + "type": "object" + }, + "Component": { + "additionalProperties": false, + "description": "Component is the primary functional grouping of assets to deploy by Zarf.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "actions": { + "$ref": "#/$defs/ComponentActions", + "description": "Custom commands to run at various stages of a package lifecycle." + }, + "charts": { + "description": "Helm charts to install during package deploy.", + "items": { + "$ref": "#/$defs/Chart" + }, + "type": "array" + }, + "description": { + "description": "Message to include during package deploy describing the purpose of this component.", + "type": "string" + }, + "files": { + "description": "Files or folders to place on disk during package deployment.", + "items": { + "$ref": "#/$defs/File" + }, + "type": "array" + }, + "imageArchives": { + "description": "List of tar archives of images to include in the package.", + "items": { + "$ref": "#/$defs/ImageArchive" + }, + "type": "array" + }, + "images": { + "description": "List of OCI images to include in the package.", + "items": { + "$ref": "#/$defs/Image" + }, + "type": "array" + }, + "import": { + "$ref": "#/$defs/ComponentImport", + "description": "Import a component from another Zarf component config." + }, + "manifests": { + "description": "Kubernetes manifests to be included in a generated Helm chart on package deploy.", + "items": { + "$ref": "#/$defs/Manifest" + }, + "type": "array" + }, + "name": { + "description": "The name of the component.", + "pattern": "^[a-z0-9][a-z0-9\\-]*$", + "type": "string" + }, + "optional": { + "description": "Do not install this component unless explicitly requested. Defaults to false, meaning the component is required.", + "type": "boolean" + }, + "repositories": { + "description": "List of git repositories to include in the package.", + "items": { + "type": "string" + }, + "type": "array" + }, + "service": { + "description": "The Zarf CLI service this component provides, such as the registry, injector, or agent.", + "enum": [ + "registry", + "seed-registry", + "injector", + "agent", + "git-server" + ], + "type": "string" + }, + "target": { + "$ref": "#/$defs/ComponentTarget", + "description": "Filter when this component is included in package creation or deployment." + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "ComponentAction": { + "additionalProperties": false, + "description": "ComponentAction represents a single action to run during a Zarf package operation.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "cmd": { + "description": "The command to run. Must specify either cmd or wait for the action to do anything.", + "type": "string" + }, + "description": { + "description": "Description of the action to be displayed during package execution instead of the command.", + "type": "string" + }, + "dir": { + "description": "The working directory to run the command in (default is CWD).", + "type": "string" + }, + "enableValues": { + "description": "EnableValues enables go-template processing on the cmd field.", + "type": "boolean" + }, + "env": { + "description": "Additional environment variables to set for the command.", + "items": { + "type": "string" + }, + "type": "array" + }, + "maxTotalSeconds": { + "description": "Timeout in seconds for the command (default 0, no timeout for cmd actions and 300, 5 minutes for wait actions).", + "type": "integer" + }, + "retries": { + "description": "Retry the command if it fails up to a given number of times (default 0).", + "type": "integer" + }, + "setValues": { + "description": "An array of values to set with the output of the command.", + "items": { + "$ref": "#/$defs/SetValue" + }, + "type": "array" + }, + "shell": { + "$ref": "#/$defs/Shell", + "description": "Indicates a preference for a shell for the provided cmd." + }, + "silent": { + "description": "Hide the output of the command during package deployment (default false).", + "type": "boolean" + }, + "wait": { + "$ref": "#/$defs/ComponentActionWait", + "description": "Wait for a condition to be met before continuing." + } + }, + "type": "object" + }, + "ComponentActionDefaults": { + "additionalProperties": false, + "description": "ComponentActionDefaults sets the default configs for child actions.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "dir": { + "description": "Working directory for commands (default CWD).", + "type": "string" + }, + "env": { + "description": "Additional environment variables for commands.", + "items": { + "type": "string" + }, + "type": "array" + }, + "maxTotalSeconds": { + "description": "Default timeout in seconds for commands (default 0, no timeout).", + "type": "integer" + }, + "retries": { + "description": "Retry commands a given number of times if they fail (default 0).", + "type": "integer" + }, + "shell": { + "$ref": "#/$defs/Shell", + "description": "Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems." + }, + "silent": { + "description": "Hide the output of commands during execution (default false).", + "type": "boolean" + } + }, + "type": "object" + }, + "ComponentActionSet": { + "additionalProperties": false, + "description": "ComponentActionSet is a set of actions to run during a Zarf package operation.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "before": { + "description": "Actions to run at the start of an operation.", + "items": { + "$ref": "#/$defs/ComponentAction" + }, + "type": "array" + }, + "defaults": { + "$ref": "#/$defs/ComponentActionDefaults", + "description": "Default configuration for all actions in this set." + }, + "onFailure": { + "description": "Actions to run if any operation in this set fails.", + "items": { + "$ref": "#/$defs/ComponentAction" + }, + "type": "array" + }, + "onSuccess": { + "description": "Actions to run at the end of an operation if it succeeds.", + "items": { + "$ref": "#/$defs/ComponentAction" + }, + "type": "array" + } + }, + "type": "object" + }, + "ComponentActionWait": { + "additionalProperties": false, + "description": "ComponentActionWait specifies a condition to wait for before continuing.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "cluster": { + "$ref": "#/$defs/ComponentActionWaitCluster", + "description": "Wait for a condition to be met in the cluster before continuing. Only one of cluster or network can be specified." + }, + "network": { + "$ref": "#/$defs/ComponentActionWaitNetwork", + "description": "Wait for a condition to be met on the network before continuing. Only one of cluster or network can be specified." + } + }, + "type": "object" + }, + "ComponentActionWaitCluster": { + "additionalProperties": false, + "description": "ComponentActionWaitCluster specifies a cluster-level condition to wait for.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "condition": { + "description": "The condition or jsonpath state to wait for; defaults to kstatus readiness checks.", + "examples": [ + "Available" + ], + "type": "string" + }, + "kind": { + "description": "The kind of resource to wait for.", + "examples": [ + "Pod", + "Deployment" + ], + "type": "string" + }, + "name": { + "description": "The name of the resource or selector to wait for.", + "examples": [ + "podinfo", + "app=podinfo" + ], + "type": "string" + }, + "namespace": { + "description": "The namespace of the resource to wait for.", + "type": "string" + } + }, + "required": [ + "kind", + "name" + ], + "type": "object" + }, + "ComponentActionWaitNetwork": { + "additionalProperties": false, + "description": "ComponentActionWaitNetwork specifies a network-level condition to wait for.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "address": { + "description": "The address to wait for.", + "examples": [ + "localhost:8080", + "1.1.1.1" + ], + "type": "string" + }, + "code": { + "description": "The HTTP status code to wait for if using http or https.", + "examples": [ + 200, + 404 + ], + "type": "integer" + }, + "protocol": { + "description": "The protocol to wait for.", + "enum": [ + "tcp", + "http", + "https" + ], + "type": "string" + } + }, + "required": [ + "protocol", + "address" + ], + "type": "object" + }, + "ComponentActions": { + "additionalProperties": false, + "description": "ComponentActions are ActionSets that map to different Zarf package operations.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "onCreate": { + "$ref": "#/$defs/ComponentActionSet", + "description": "Actions to run during package creation." + }, + "onDeploy": { + "$ref": "#/$defs/ComponentActionSet", + "description": "Actions to run during package deployment." + }, + "onRemove": { + "$ref": "#/$defs/ComponentActionSet", + "description": "Actions to run during package removal." + } + }, + "type": "object" + }, + "ComponentImport": { + "additionalProperties": false, + "description": "ComponentImport is a reference to imported Zarf component configs.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "local": { + "description": "Local file path references to component config files to import.", + "items": { + "$ref": "#/$defs/ComponentImportLocal" + }, + "type": "array" + }, + "remote": { + "description": "OCI URL references to remote component config files to import; pulled at create time.", + "items": { + "$ref": "#/$defs/ComponentImportRemote" + }, + "type": "array" + } + }, + "type": "object" + }, + "ComponentImportLocal": { + "additionalProperties": false, + "description": "ComponentImportLocal is a local file path reference to a component config.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "path": { + "description": "The local file path to the component config.", + "type": "string" + } + }, + "required": [ + "path" + ], + "type": "object" + }, + "ComponentImportRemote": { + "additionalProperties": false, + "description": "ComponentImportRemote is a remote OCI URL reference to a component config.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "url": { + "description": "The OCI URL of the remote component config.", + "type": "string" + } + }, + "required": [ + "url" + ], + "type": "object" + }, + "ComponentMetadata": { + "additionalProperties": false, + "description": "ComponentMetadata holds metadata about a component config.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "annotations": { + "additionalProperties": { + "type": "string" + }, + "description": "Annotations contains arbitrary metadata about the component config.", + "type": "object" + }, + "description": { + "description": "Additional information about this component config.", + "type": "string" + }, + "name": { + "description": "Name to identify this component config.", + "pattern": "^[a-z0-9][a-z0-9\\-]*$", + "type": "string" + }, + "version": { + "description": "Generic string to track the component config version.", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "ComponentPublishData": { + "additionalProperties": false, + "description": "ComponentPublishData is written during publish to track details of the component config.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "migrations": { + "description": "Any migrations that have been run on this component config.", + "items": { + "type": "string" + }, + "type": "array" + }, + "versionRequirements": { + "description": "Requirements for specific package operations.", + "items": { + "$ref": "#/$defs/VersionRequirement" + }, + "type": "array" + }, + "zarfVersion": { + "description": "The version of Zarf used to build this component config.", + "type": "string" + } + }, + "required": [ + "zarfVersion" + ], + "type": "object" + }, + "ComponentTarget": { + "additionalProperties": false, + "description": "ComponentTarget filters a component to only apply for a given local OS, architecture, or flavor.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "architecture": { + "description": "Only include component for the given package architecture.", + "enum": [ + "amd64", + "arm64" + ], + "type": "string" + }, + "flavor": { + "description": "Only include this component when a matching '--flavor' is specified on 'zarf package create'.", + "type": "string" + }, + "os": { + "description": "Only deploy component to specified OS.", + "enum": [ + "linux", + "darwin", + "windows" + ], + "type": "string" + } + }, + "type": "object" + }, + "File": { + "additionalProperties": false, + "description": "File defines a file to deploy.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "checksum": { + "description": "Optional checksum of the file in the format \u003calgorithm\u003e:\u003cchecksum\u003e (e.g. sha256:abc123). Defaults to sha256 if no algorithm is specified.", + "type": "string" + }, + "destination": { + "description": "The absolute or relative path where the file or folder should be copied to during package deploy.", + "type": "string" + }, + "enableValues": { + "description": "EnableValues enables go-template processing on this file during deploy.", + "type": "boolean" + }, + "executable": { + "description": "Determines if the file should be made executable during package deploy.", + "type": "boolean" + }, + "extractPath": { + "description": "Local folder or file to be extracted from a 'source' archive.", + "type": "string" + }, + "source": { + "description": "Local folder or file path or remote URL to pull into the package.", + "type": "string" + }, + "symlinks": { + "description": "List of symlinks to create during package deploy.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "source", + "destination" + ], + "type": "object" + }, + "GitSource": { + "additionalProperties": false, + "description": "GitSource represents a Helm chart stored in a Git repository.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "path": { + "description": "The subdirectory containing the chart within a Git repo.", + "type": "string" + }, + "url": { + "description": "The URL of the Git repository where the Helm chart is stored.", + "type": "string" + } + }, + "required": [ + "url" + ], + "type": "object" + }, + "HelmRepositorySource": { + "additionalProperties": false, + "description": "HelmRepositorySource represents a Helm chart stored in a Helm repository.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "name": { + "description": "The name of a chart within a Helm repository.", + "type": "string" + }, + "url": { + "description": "The URL of the chart repository where the Helm chart is stored.", + "type": "string" + }, + "version": { + "description": "The version of the chart in the Helm repository.", + "type": "string" + } + }, + "required": [ + "url", + "version" + ], + "type": "object" + }, + "Image": { + "additionalProperties": false, + "description": "Image defines an OCI image to include in the package.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "name": { + "description": "The image reference.", + "type": "string" + }, + "source": { + "description": "The source to pull the image from. Defaults to \"registry\".", + "enum": [ + "registry", + "daemon" + ], + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "ImageArchive": { + "additionalProperties": false, + "description": "ImageArchive defines a tar archive of images to include in the package.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "images": { + "description": "The list of images contained in the archive.", + "items": { + "type": "string" + }, + "type": "array" + }, + "path": { + "description": "The path to the tar archive.", + "type": "string" + } + }, + "required": [ + "path", + "images" + ], + "type": "object" + }, + "KustomizeManifest": { + "additionalProperties": false, + "description": "KustomizeManifest defines kustomization settings for a manifest.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "allowAnyDirectory": { + "description": "Allow traversing directory above the current directory if needed for kustomization.", + "type": "boolean" + }, + "enablePlugins": { + "description": "Enable kustomize plugins when building manifests.", + "type": "boolean" + }, + "files": { + "description": "List of local kustomization paths or remote URLs to include in the package.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "LocalSource": { + "additionalProperties": false, + "description": "LocalSource represents a Helm chart stored locally.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "path": { + "description": "The path to a local chart's folder or .tgz archive.", + "type": "string" + } + }, + "required": [ + "path" + ], + "type": "object" + }, + "Manifest": { + "additionalProperties": false, + "description": "Manifest defines raw manifests Zarf will deploy as a helm chart.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "enableValues": { + "description": "EnableValues enables go-template processing on these manifests during deploy.", + "type": "boolean" + }, + "files": { + "description": "List of local K8s YAML files or remote URLs to deploy (in order).", + "items": { + "type": "string" + }, + "type": "array" + }, + "kustomize": { + "$ref": "#/$defs/KustomizeManifest", + "description": "Kustomize settings for this manifest." + }, + "name": { + "description": "A name to give this collection of manifests; this will become the name of the dynamically-created helm chart.", + "maxLength": 40, + "type": "string" + }, + "namespace": { + "description": "The namespace to deploy the manifests to.", + "type": "string" + }, + "serverSideApply": { + "description": "Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy. Defaults to \"auto\" when omitted.", + "enum": [ + "true", + "false", + "auto" + ], + "type": "string" + }, + "skipWait": { + "description": "Whether to skip waiting for manifest resources to be ready before continuing.", + "type": "boolean" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "OCISource": { + "additionalProperties": false, + "description": "OCISource represents a Helm chart stored in an OCI registry.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "url": { + "description": "The URL of the OCI registry where the Helm chart is stored.", + "type": "string" + }, + "version": { + "description": "The version of the chart in the OCI registry.", + "type": "string" + } + }, + "required": [ + "url", + "version" + ], + "type": "object" + }, + "SetValue": { + "additionalProperties": false, + "description": "SetValue declares a value that can be set during a package deploy.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "key": { + "description": "Key represents which value to assign to.", + "type": "string" + }, + "type": { + "description": "Type declares the kind of data being stored in the value.", + "type": "string" + }, + "value": { + "description": "Value is the current value at the key." + } + }, + "type": "object" + }, + "Shell": { + "additionalProperties": false, + "description": "Shell represents the desired shell to use for a given command.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "darwin": { + "description": "Darwin (macOS) shell preference.", + "examples": [ + "sh", + "bash", + "zsh" + ], + "type": "string" + }, + "linux": { + "description": "Linux shell preference.", + "examples": [ + "sh", + "bash", + "zsh" + ], + "type": "string" + }, + "windows": { + "description": "Windows shell preference.", + "examples": [ + "powershell", + "cmd", + "pwsh" + ], + "type": "string" + } + }, + "type": "object" + }, + "Values": { + "additionalProperties": false, + "description": "Values defines values files and schema for templating and overriding Helm values.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "files": { + "description": "List of values file paths to include.", + "items": { + "type": "string" + }, + "type": "array" + }, + "schema": { + "description": "Path to a JSON schema file for validating values.", + "type": "string" + } + }, + "type": "object" + }, + "VersionRequirement": { + "additionalProperties": false, + "description": "VersionRequirement specifies a minimum Zarf version needed and the reason for the requirement.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "reason": { + "description": "The reason this version is required.", + "type": "string" + }, + "version": { + "description": "The minimum version of Zarf required.", + "type": "string" + } + }, + "required": [ + "version", + "reason" + ], + "type": "object" + } + }, + "$id": "https://github.com/zarf-dev/zarf/src/api/v1beta1/component-config", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "description": "ComponentConfig is the top-level structure of a Zarf component config file.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "apiVersion": { + "description": "The API version of the component config.", + "enum": [ + "zarf.dev/v1beta1" + ], + "type": "string" + }, + "component": { + "$ref": "#/$defs/Component", + "description": "The single component this config defines." + }, + "kind": { + "default": "ZarfComponentConfig", + "description": "The kind of component config.", + "enum": [ + "ZarfComponentConfig" + ], + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/ComponentMetadata", + "description": "Component metadata." + }, + "publishData": { + "$ref": "#/$defs/ComponentPublishData", + "description": "Zarf-generated publish data for the component config." + }, + "values": { + "$ref": "#/$defs/Values", + "description": "Values imports Zarf values files for templating and overriding Helm values." + } + }, + "required": [ + "apiVersion", + "kind", + "metadata", + "component" + ], + "type": "object" +} diff --git a/src/pkg/schema/zarf-v1beta1-schema.json b/src/pkg/schema/zarf-v1beta1-schema.json index 8ed0dcebf1..b3c123e9e4 100644 --- a/src/pkg/schema/zarf-v1beta1-schema.json +++ b/src/pkg/schema/zarf-v1beta1-schema.json @@ -1,379 +1,8 @@ { "$defs": { - "Constant": { + "BuildData": { "additionalProperties": false, - "description": "Constant are constants that can be used to dynamically template K8s resources or run in actions.", - "patternProperties": { - "^x-": {} - }, - "properties": { - "autoIndent": { - "description": "Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARF_CONST_.", - "type": "boolean" - }, - "description": { - "description": "A description of the constant to explain its purpose on package create or deploy confirmation prompts", - "type": "string" - }, - "name": { - "description": "The name to be used for the constant", - "pattern": "^[A-Z0-9_]+$", - "type": "string" - }, - "pattern": { - "description": "An optional regex pattern that a constant value must match before a package can be created.", - "type": "string" - }, - "value": { - "description": "The value to set for the constant during deploy", - "type": "string" - } - }, - "required": [ - "name", - "value" - ], - "type": "object" - }, - "Duration": { - "additionalProperties": false, - "patternProperties": { - "^x-": {} - }, - "properties": { - "Duration": { - "$ref": "#/$defs/Duration" - } - }, - "required": [ - "Duration" - ], - "type": "object" - }, - "GitRepoSource": { - "additionalProperties": false, - "description": "GitRepoSource represents a Helm chart stored in a Git repository.", - "patternProperties": { - "^x-": {} - }, - "properties": { - "path": { - "description": "The sub directory to the chart within a git repo.", - "type": "string" - }, - "url": { - "description": "The URL of the git repository where the helm chart is stored.", - "type": "string" - } - }, - "required": [ - "url" - ], - "type": "object" - }, - "HelmRepoSource": { - "additionalProperties": false, - "description": "HelmRepoSource represents a Helm chart stored in a Helm repository.", - "patternProperties": { - "^x-": {} - }, - "properties": { - "name": { - "description": "The name of a chart within a Helm repository (defaults to the Zarf name of the chart).", - "type": "string" - }, - "url": { - "description": "The URL of the chart repository where the helm chart is stored.", - "type": "string" - }, - "version": { - "description": "The version of the chart to deploy.", - "type": "string" - } - }, - "required": [ - "url", - "version" - ], - "type": "object" - }, - "ImageArchive": { - "additionalProperties": false, - "description": "ImageArchive defines a tar archive of images to include in the package.", - "patternProperties": { - "^x-": {} - }, - "properties": { - "images": { - "description": "The list of images contained in the archive.", - "items": { - "type": "string" - }, - "type": "array" - }, - "path": { - "description": "The path to the tar archive.", - "type": "string" - } - }, - "required": [ - "path", - "images" - ], - "type": "object" - }, - "Injector": { - "additionalProperties": false, - "description": "Injector defines the configuration for the Zarf injector.", - "patternProperties": { - "^x-": {} - }, - "properties": { - "enabled": { - "description": "Whether the injector is enabled.", - "type": "boolean" - }, - "values": { - "$ref": "#/$defs/InjectorValues", - "description": "Values for the injector." - } - }, - "required": [ - "enabled" - ], - "type": "object" - }, - "InjectorValues": { - "additionalProperties": false, - "description": "InjectorValues defines configurable values for the Zarf injector.", - "patternProperties": { - "^x-": {} - }, - "properties": { - "tolerations": { - "description": "Tolerations for the injector pod.", - "type": "string" - } - }, - "type": "object" - }, - "InteractiveVariable": { - "additionalProperties": false, - "description": "InteractiveVariable is a variable that can be used to prompt a user for more information", - "patternProperties": { - "^x-": {} - }, - "properties": { - "autoIndent": { - "description": "Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARF_VAR_.", - "type": "boolean" - }, - "default": { - "description": "The default value to use for the variable", - "type": "string" - }, - "description": { - "description": "A description of the variable to be used when prompting the user a value", - "type": "string" - }, - "name": { - "description": "The name to be used for the variable", - "pattern": "^[A-Z0-9_]+$", - "type": "string" - }, - "pattern": { - "description": "An optional regex pattern that a variable value must match before a package deployment can continue.", - "type": "string" - }, - "prompt": { - "description": "Whether to prompt the user for input for this variable", - "type": "boolean" - }, - "sensitive": { - "description": "Whether to mark this variable as sensitive to not print it in the log", - "type": "boolean" - }, - "type": { - "description": "Changes the handling of a variable to load contents differently (i.e. from a file rather than as a raw variable - templated files should be kept below 1 MiB)", - "enum": [ - "raw", - "file" - ], - "type": "string" - } - }, - "required": [ - "name" - ], - "type": "object" - }, - "LocalRepoSource": { - "additionalProperties": false, - "description": "LocalRepoSource represents a Helm chart stored locally.", - "patternProperties": { - "^x-": {} - }, - "properties": { - "path": { - "description": "The path to a local chart's folder or .tgz archive.", - "type": "string" - } - }, - "required": [ - "path" - ], - "type": "object" - }, - "OCISource": { - "additionalProperties": false, - "description": "OCISource represents a Helm chart stored in an OCI registry.", - "patternProperties": { - "^x-": {} - }, - "properties": { - "url": { - "description": "The URL of the OCI registry where the helm chart is stored.", - "type": "string" - }, - "version": { - "description": "The version of the chart to deploy.", - "type": "string" - } - }, - "required": [ - "url", - "version" - ], - "type": "object" - }, - "SetValue": { - "additionalProperties": false, - "description": "SetValue declares a value that can be set during a package deploy.", - "patternProperties": { - "^x-": {} - }, - "properties": { - "key": { - "description": "Key represents which value to assign to.", - "type": "string" - }, - "type": { - "description": "Type declares the kind of data being stored in the value. JSON and YAML types ensure proper formatting when\ninserting the value into the template. Defaults to SetValueString behavior when empty.", - "type": "string" - }, - "value": { - "description": "Value is the current value at the key." - } - }, - "type": "object" - }, - "Shell": { - "additionalProperties": false, - "description": "Shell represents the desired shell to use for a given command", - "patternProperties": { - "^x-": {} - }, - "properties": { - "darwin": { - "description": "(default 'sh') Indicates a preference for the shell to use on macOS systems", - "examples": [ - "sh", - "bash", - "fish", - "zsh", - "pwsh" - ], - "type": "string" - }, - "linux": { - "description": "(default 'sh') Indicates a preference for the shell to use on Linux systems", - "examples": [ - "sh", - "bash", - "fish", - "zsh", - "pwsh" - ], - "type": "string" - }, - "windows": { - "description": "(default 'powershell') Indicates a preference for the shell to use on Windows systems (note that choosing 'cmd' will turn off migrations like touch -\u003e New-Item)", - "examples": [ - "powershell", - "cmd", - "pwsh", - "sh", - "bash", - "gsh" - ], - "type": "string" - } - }, - "type": "object" - }, - "Variable": { - "additionalProperties": false, - "description": "Variable represents a variable that has a value set programmatically", - "patternProperties": { - "^x-": {} - }, - "properties": { - "autoIndent": { - "description": "Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARF_VAR_.", - "type": "boolean" - }, - "name": { - "description": "The name to be used for the variable", - "pattern": "^[A-Z0-9_]+$", - "type": "string" - }, - "pattern": { - "description": "An optional regex pattern that a variable value must match before a package deployment can continue.", - "type": "string" - }, - "sensitive": { - "description": "Whether to mark this variable as sensitive to not print it in the log", - "type": "boolean" - }, - "type": { - "description": "Changes the handling of a variable to load contents differently (i.e. from a file rather than as a raw variable - templated files should be kept below 1 MiB)", - "enum": [ - "raw", - "file" - ], - "type": "string" - } - }, - "required": [ - "name" - ], - "type": "object" - }, - "VersionRequirement": { - "additionalProperties": false, - "description": "VersionRequirement specifies a minimum Zarf version needed and the reason for the requirement.", - "patternProperties": { - "^x-": {} - }, - "properties": { - "reason": { - "description": "The reason this version is required.", - "type": "string" - }, - "version": { - "description": "The minimum version of Zarf required.", - "type": "string" - } - }, - "required": [ - "version", - "reason" - ], - "type": "object" - }, - "ZarfBuildData": { - "additionalProperties": false, - "description": "ZarfBuildData is written during the packager.Create() operation to track details of the created package.", + "description": "BuildData is written during package create to track details of the created package.", "patternProperties": { "^x-": {} }, @@ -382,10 +11,6 @@ "description": "Checksum of a checksums.txt file that contains checksums all the layers within the package.", "type": "string" }, - "apiVersion": { - "description": "The API version defined in the package definition used to build the package.", - "type": "string" - }, "architecture": { "description": "The architecture this package was created on.", "type": "string" @@ -394,14 +19,14 @@ "description": "Whether this package was created with differential components.", "type": "boolean" }, - "differentialPackageVersion": { - "description": "Version of a previously built package used as the basis for creating this differential package.", - "type": "string" - }, "flavor": { "description": "The flavor of Zarf used to build this package.", "type": "string" }, + "hostname": { + "description": "The machine name that created this package.", + "type": "string" + }, "migrations": { "description": "Any migrations that have been run on this package.", "items": { @@ -409,13 +34,6 @@ }, "type": "array" }, - "provenanceFiles": { - "description": "ProvenanceFiles lists files present in the package that are not included in checksums.txt.\nThese are files added after checksum generation (e.g., signature files).", - "items": { - "type": "string" - }, - "type": "array" - }, "registryOverrides": { "additionalProperties": { "type": "string" @@ -423,14 +41,6 @@ "description": "Any registry domains that were overridden on package create when pulling images.", "type": "object" }, - "signed": { - "description": "Whether this package was signed.", - "type": "boolean" - }, - "terminal": { - "description": "The machine name that created this package.", - "type": "string" - }, "timestamp": { "description": "The timestamp when this package was created.", "type": "string" @@ -458,27 +68,27 @@ ], "type": "object" }, - "ZarfChart": { + "Chart": { "additionalProperties": false, - "description": "ZarfChart defines a helm chart to be deployed.", + "description": "Chart defines a helm chart to be deployed.", "patternProperties": { "^x-": {} }, "properties": { "git": { - "$ref": "#/$defs/GitRepoSource", - "description": "The Git repo where the chart is stored." + "$ref": "#/$defs/GitSource", + "description": "The Git repository where the chart is stored." }, - "helmRepo": { - "$ref": "#/$defs/HelmRepoSource", - "description": "The Helm repo where the chart is stored." + "helmRepository": { + "$ref": "#/$defs/HelmRepositorySource", + "description": "The Helm repository where the chart is stored." }, "local": { - "$ref": "#/$defs/LocalRepoSource", + "$ref": "#/$defs/LocalSource", "description": "The local path where the chart is stored." }, "name": { - "description": "The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repo.", + "description": "The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repository.", "type": "string" }, "namespace": { @@ -493,12 +103,8 @@ "description": "The name of the Helm release to create (defaults to the Zarf name of the chart).", "type": "string" }, - "schemaValidation": { - "description": "Whether to validate the chart's values against its JSON schema. Defaults to true.", - "type": "boolean" - }, "serverSideApply": { - "description": "Controls whether Helm uses Server-Side Apply (SSA) or client-side apply (CSA) when deploying this chart.\n - \"true\": always use SSA\n - \"false\": always use CSA\n - \"auto\": use SSA for fresh installs; for upgrades, match whichever strategy\n was used when the chart was first installed\nDefaults to \"auto\" when omitted.", + "description": "Controls whether Helm uses Server-Side Apply (SSA) or client-side apply (CSA) when deploying this chart. Defaults to \"auto\" when omitted.", "enum": [ "true", "false", @@ -506,10 +112,18 @@ ], "type": "string" }, + "skipSchemaValidation": { + "description": "Skip validation of the chart's values against its JSON schema. Defaults to false.", + "type": "boolean" + }, + "skipWait": { + "description": "Whether to skip waiting for chart resources to be ready before continuing.", + "type": "boolean" + }, "values": { - "description": "List of values sources to their Helm override target.", + "description": "List of value sources mapped to their Helm override targets.", "items": { - "$ref": "#/$defs/ZarfChartValue" + "$ref": "#/$defs/ChartValue" }, "type": "array" }, @@ -519,10 +133,6 @@ "type": "string" }, "type": "array" - }, - "wait": { - "description": "Whether to wait for chart resources to be ready before continuing. Defaults to true.", - "type": "boolean" } }, "required": [ @@ -530,9 +140,9 @@ ], "type": "object" }, - "ZarfChartValue": { + "ChartValue": { "additionalProperties": false, - "description": "ZarfChartValue maps a values source path to a Helm chart target path.", + "description": "ChartValue maps a values source path to a Helm chart target path.", "patternProperties": { "^x-": {} }, @@ -552,40 +162,32 @@ ], "type": "object" }, - "ZarfComponent": { + "Component": { "additionalProperties": false, - "description": "ZarfComponent is the primary functional grouping of assets to deploy by Zarf.", + "description": "Component is the primary functional grouping of assets to deploy by Zarf.", "patternProperties": { "^x-": {} }, "properties": { "actions": { - "$ref": "#/$defs/ZarfComponentActions", + "$ref": "#/$defs/ComponentActions", "description": "Custom commands to run at various stages of a package lifecycle." }, "charts": { "description": "Helm charts to install during package deploy.", "items": { - "$ref": "#/$defs/ZarfChart" + "$ref": "#/$defs/Chart" }, "type": "array" }, - "default": { - "description": "Determines the default Y/N state for installing this component on package deploy.", - "type": "boolean" - }, "description": { "description": "Message to include during package deploy describing the purpose of this component.", "type": "string" }, - "features": { - "$ref": "#/$defs/ZarfComponentFeatures", - "description": "Features of the Zarf CLI to enable for this component." - }, "files": { "description": "Files or folders to place on disk during package deployment.", "items": { - "$ref": "#/$defs/ZarfFile" + "$ref": "#/$defs/File" }, "type": "array" }, @@ -599,18 +201,18 @@ "images": { "description": "List of OCI images to include in the package.", "items": { - "$ref": "#/$defs/ZarfImage" + "$ref": "#/$defs/Image" }, "type": "array" }, "import": { - "$ref": "#/$defs/ZarfComponentImport", + "$ref": "#/$defs/ComponentImport", "description": "Import a component from another Zarf component config." }, "manifests": { "description": "Kubernetes manifests to be included in a generated Helm chart on package deploy.", "items": { - "$ref": "#/$defs/ZarfManifest" + "$ref": "#/$defs/Manifest" }, "type": "array" }, @@ -619,20 +221,31 @@ "pattern": "^[a-z0-9][a-z0-9\\-]*$", "type": "string" }, - "only": { - "$ref": "#/$defs/ZarfComponentOnlyTarget", - "description": "Filter when this component is included in package creation or deployment." - }, "optional": { - "description": "Do not prompt user to install this component. Defaults to false, meaning the component is required.", + "description": "Do not install this component unless explicitly requested. Defaults to false, meaning the component is required.", "type": "boolean" }, - "repos": { - "description": "List of git repos to include in the package.", + "repositories": { + "description": "List of git repositories to include in the package.", "items": { "type": "string" }, "type": "array" + }, + "service": { + "description": "The Zarf CLI service this component provides, such as the registry, injector, or agent.", + "enum": [ + "registry", + "seed-registry", + "injector", + "agent", + "git-server" + ], + "type": "string" + }, + "target": { + "$ref": "#/$defs/ComponentTarget", + "description": "Filter when this component is included in package creation or deployment." } }, "required": [ @@ -640,9 +253,9 @@ ], "type": "object" }, - "ZarfComponentAction": { + "ComponentAction": { "additionalProperties": false, - "description": "ZarfComponentAction represents a single action to run during a zarf package operation.", + "description": "ComponentAction represents a single action to run during a Zarf package operation.", "patternProperties": { "^x-": {} }, @@ -659,6 +272,10 @@ "description": "The working directory to run the command in (default is CWD).", "type": "string" }, + "enableValues": { + "description": "EnableValues enables go-template processing on the cmd field.", + "type": "boolean" + }, "env": { "description": "Additional environment variables to set for the command.", "items": { @@ -666,12 +283,12 @@ }, "type": "array" }, - "mute": { - "description": "Hide the output of the command during package deployment (default false).", - "type": "boolean" + "maxTotalSeconds": { + "description": "Timeout in seconds for the command (default 0, no timeout for cmd actions and 300, 5 minutes for wait actions).", + "type": "integer" }, "retries": { - "description": "Retry the command if it fails up to given number of times (default 0).", + "description": "Retry the command if it fails up to a given number of times (default 0).", "type": "integer" }, "setValues": { @@ -681,35 +298,24 @@ }, "type": "array" }, - "setVariables": { - "description": "(onDeploy/cmd only) An array of variables to update with the output of the command. These variables will be available to all remaining actions and components in the package.", - "items": { - "$ref": "#/$defs/Variable" - }, - "type": "array" - }, "shell": { "$ref": "#/$defs/Shell", - "description": "(cmd only) Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems." + "description": "Indicates a preference for a shell for the provided cmd." }, - "template": { - "description": "Disable go-template processing on the cmd field.", + "silent": { + "description": "Hide the output of the command during package deployment (default false).", "type": "boolean" }, - "timeout": { - "$ref": "#/$defs/Duration", - "description": "Timeout for the command (default to 0, no timeout for cmd actions and 5 minutes for wait actions)." - }, "wait": { - "$ref": "#/$defs/ZarfComponentActionWait", - "description": "Wait for a condition to be met before continuing. Must specify either cmd or wait for the action. See the 'zarf tools wait-for' command for more info." + "$ref": "#/$defs/ComponentActionWait", + "description": "Wait for a condition to be met before continuing." } }, "type": "object" }, - "ZarfComponentActionDefaults": { + "ComponentActionDefaults": { "additionalProperties": false, - "description": "ZarfComponentActionDefaults sets the default configs for child actions.", + "description": "ComponentActionDefaults sets the default configs for child actions.", "patternProperties": { "^x-": {} }, @@ -725,81 +331,81 @@ }, "type": "array" }, - "mute": { - "description": "Hide the output of commands during execution (default false).", - "type": "boolean" + "maxTotalSeconds": { + "description": "Default timeout in seconds for commands (default 0, no timeout).", + "type": "integer" }, "retries": { - "description": "Retry commands given number of times if they fail (default 0).", + "description": "Retry commands a given number of times if they fail (default 0).", "type": "integer" }, "shell": { "$ref": "#/$defs/Shell", - "description": "(cmd only) Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems." + "description": "Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems." }, - "timeout": { - "$ref": "#/$defs/Duration", - "description": "Default timeout for commands (default no timeout)." + "silent": { + "description": "Hide the output of commands during execution (default false).", + "type": "boolean" } }, "type": "object" }, - "ZarfComponentActionSet": { + "ComponentActionSet": { "additionalProperties": false, - "description": "ZarfComponentActionSet is a set of actions to run during a zarf package operation.", + "description": "ComponentActionSet is a set of actions to run during a Zarf package operation.", "patternProperties": { "^x-": {} }, "properties": { - "after": { - "description": "Actions to run at the end of an operation.", - "items": { - "$ref": "#/$defs/ZarfComponentAction" - }, - "type": "array" - }, "before": { "description": "Actions to run at the start of an operation.", "items": { - "$ref": "#/$defs/ZarfComponentAction" + "$ref": "#/$defs/ComponentAction" }, "type": "array" }, "defaults": { - "$ref": "#/$defs/ZarfComponentActionDefaults", + "$ref": "#/$defs/ComponentActionDefaults", "description": "Default configuration for all actions in this set." }, "onFailure": { - "description": "Actions to run if all operations fail.", + "description": "Actions to run if any operation in this set fails.", "items": { - "$ref": "#/$defs/ZarfComponentAction" + "$ref": "#/$defs/ComponentAction" + }, + "type": "array" + }, + "onSuccess": { + "description": "Actions to run at the end of an operation if it succeeds.", + "items": { + "$ref": "#/$defs/ComponentAction" }, "type": "array" } }, "type": "object" }, - "ZarfComponentActionWait": { + "ComponentActionWait": { "additionalProperties": false, - "description": "ZarfComponentActionWait specifies a condition to wait for before continuing", + "description": "ComponentActionWait specifies a condition to wait for before continuing.", "patternProperties": { "^x-": {} }, "properties": { "cluster": { - "$ref": "#/$defs/ZarfComponentActionWaitCluster", + "$ref": "#/$defs/ComponentActionWaitCluster", "description": "Wait for a condition to be met in the cluster before continuing. Only one of cluster or network can be specified." }, "network": { - "$ref": "#/$defs/ZarfComponentActionWaitNetwork", + "$ref": "#/$defs/ComponentActionWaitNetwork", "description": "Wait for a condition to be met on the network before continuing. Only one of cluster or network can be specified." } }, "type": "object" }, - "ZarfComponentActionWaitCluster": { + "ComponentActionWaitCluster": { "additionalProperties": false, - "description": "ZarfComponentActionWaitCluster specifies a condition to wait for before continuing", + "description": "ComponentActionWaitCluster specifies a cluster-level condition to wait for.", "patternProperties": { "^x-": {} }, @@ -838,9 +444,9 @@ ], "type": "object" }, - "ZarfComponentActionWaitNetwork": { + "ComponentActionWaitNetwork": { "additionalProperties": false, - "description": "ZarfComponentActionWaitNetwork specifies a condition to wait for before continuing", + "description": "ComponentActionWaitNetwork specifies a network-level condition to wait for.", "patternProperties": { "^x-": {} }, @@ -877,114 +483,106 @@ ], "type": "object" }, - "ZarfComponentActions": { + "ComponentActions": { "additionalProperties": false, - "description": "ZarfComponentActions are ActionSets that map to different zarf package operations.", + "description": "ComponentActions are ActionSets that map to different Zarf package operations.", "patternProperties": { "^x-": {} }, "properties": { "onCreate": { - "$ref": "#/$defs/ZarfComponentActionSet", + "$ref": "#/$defs/ComponentActionSet", "description": "Actions to run during package creation." }, "onDeploy": { - "$ref": "#/$defs/ZarfComponentActionSet", + "$ref": "#/$defs/ComponentActionSet", "description": "Actions to run during package deployment." }, "onRemove": { - "$ref": "#/$defs/ZarfComponentActionSet", + "$ref": "#/$defs/ComponentActionSet", "description": "Actions to run during package removal." } }, "type": "object" }, - "ZarfComponentFeatures": { + "ComponentImport": { "additionalProperties": false, - "description": "ZarfComponentFeatures defines features of the Zarf CLI to enable for a component.", + "description": "ComponentImport is a reference to imported Zarf component configs.", "patternProperties": { "^x-": {} }, "properties": { - "injector": { - "$ref": "#/$defs/Injector", - "description": "Injector configuration for the component." - }, - "isAgent": { - "description": "Whether this component provides an agent.", - "type": "boolean" + "local": { + "description": "Local file path references to component config files to import.", + "items": { + "$ref": "#/$defs/ComponentImportLocal" + }, + "type": "array" }, - "isRegistry": { - "description": "Whether this component provides a registry.", - "type": "boolean" + "remote": { + "description": "OCI URL references to remote component config files to import; pulled at create time.", + "items": { + "$ref": "#/$defs/ComponentImportRemote" + }, + "type": "array" } }, "type": "object" }, - "ZarfComponentImport": { + "ComponentImportLocal": { "additionalProperties": false, - "description": "ZarfComponentImport structure for including imported Zarf components.", + "description": "ComponentImportLocal is a local file path reference to a component config.", "patternProperties": { "^x-": {} }, "properties": { "path": { - "description": "The path to the component config file to import.", - "type": "string" - }, - "url": { - "description": "The URL to a Zarf component config to import via OCI.", - "pattern": "^oci://.*$", + "description": "The local file path to the component config.", "type": "string" } }, + "required": [ + "path" + ], "type": "object" }, - "ZarfComponentOnlyCluster": { + "ComponentImportRemote": { "additionalProperties": false, - "description": "ZarfComponentOnlyCluster represents the architecture and K8s cluster distribution to filter on.", + "description": "ComponentImportRemote is a remote OCI URL reference to a component config.", "patternProperties": { "^x-": {} }, "properties": { - "architecture": { - "description": "Only create and deploy to clusters of the given architecture.", - "enum": [ - "amd64", - "arm64" - ], + "url": { + "description": "The OCI URL of the remote component config.", "type": "string" - }, - "distros": { - "description": "A list of kubernetes distros this package works with (Reserved for future use).", - "items": { - "examples": [ - "k3s", - "eks" - ], - "type": "string" - }, - "type": "array" } }, + "required": [ + "url" + ], "type": "object" }, - "ZarfComponentOnlyTarget": { + "ComponentTarget": { "additionalProperties": false, - "description": "ZarfComponentOnlyTarget filters a component to only show it for a given local OS and cluster.", + "description": "ComponentTarget filters a component to only apply for a given local OS, architecture, or flavor.", "patternProperties": { "^x-": {} }, "properties": { - "cluster": { - "$ref": "#/$defs/ZarfComponentOnlyCluster", - "description": "Only deploy component to specified clusters." + "architecture": { + "description": "Only include component for the given package architecture.", + "enum": [ + "amd64", + "arm64" + ], + "type": "string" }, "flavor": { "description": "Only include this component when a matching '--flavor' is specified on 'zarf package create'.", "type": "string" }, - "localOS": { + "os": { "description": "Only deploy component to specified OS.", "enum": [ "linux", @@ -996,25 +594,33 @@ }, "type": "object" }, - "ZarfFile": { + "File": { "additionalProperties": false, - "description": "ZarfFile defines a file to deploy.", + "description": "File defines a file to deploy.", "patternProperties": { "^x-": {} }, "properties": { + "checksum": { + "description": "Optional checksum of the file in the format \u003calgorithm\u003e:\u003cchecksum\u003e (e.g. sha256:abc123). Defaults to sha256 if no algorithm is specified.", + "type": "string" + }, + "destination": { + "description": "The absolute or relative path where the file or folder should be copied to during package deploy.", + "type": "string" + }, + "enableValues": { + "description": "EnableValues enables go-template processing on this file during deploy.", + "type": "boolean" + }, "executable": { - "description": "(files only) Determines if the file should be made executable during package deploy.", + "description": "Determines if the file should be made executable during package deploy.", "type": "boolean" }, "extractPath": { "description": "Local folder or file to be extracted from a 'source' archive.", "type": "string" }, - "shasum": { - "description": "(files only) Optional SHA256 checksum of the file.", - "type": "string" - }, "source": { "description": "Local folder or file path or remote URL to pull into the package.", "type": "string" @@ -1025,25 +631,64 @@ "type": "string" }, "type": "array" + } + }, + "required": [ + "source", + "destination" + ], + "type": "object" + }, + "GitSource": { + "additionalProperties": false, + "description": "GitSource represents a Helm chart stored in a Git repository.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "path": { + "description": "The subdirectory containing the chart within a Git repo.", + "type": "string" }, - "target": { - "description": "The absolute or relative path where the file or folder should be copied to during package deploy.", + "url": { + "description": "The URL of the Git repository where the Helm chart is stored.", + "type": "string" + } + }, + "required": [ + "url" + ], + "type": "object" + }, + "HelmRepositorySource": { + "additionalProperties": false, + "description": "HelmRepositorySource represents a Helm chart stored in a Helm repository.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "name": { + "description": "The name of a chart within a Helm repository.", "type": "string" }, - "template": { - "description": "Template enables go-template processing on this file during deploy.", - "type": "boolean" + "url": { + "description": "The URL of the chart repository where the Helm chart is stored.", + "type": "string" + }, + "version": { + "description": "The version of the chart in the Helm repository.", + "type": "string" } }, "required": [ - "source", - "target" + "url", + "version" ], "type": "object" }, - "ZarfImage": { + "Image": { "additionalProperties": false, - "description": "ZarfImage defines an OCI image to include in the package.", + "description": "Image defines an OCI image to include in the package.", "patternProperties": { "^x-": {} }, @@ -1066,33 +711,98 @@ ], "type": "object" }, - "ZarfManifest": { + "ImageArchive": { "additionalProperties": false, - "description": "ZarfManifest defines raw manifests Zarf will deploy as a helm chart.", + "description": "ImageArchive defines a tar archive of images to include in the package.", "patternProperties": { "^x-": {} }, "properties": { - "files": { - "description": "List of local K8s YAML files or remote URLs to deploy (in order).", + "images": { + "description": "The list of images contained in the archive.", "items": { "type": "string" }, "type": "array" }, - "kustomizations": { + "path": { + "description": "The path to the tar archive.", + "type": "string" + } + }, + "required": [ + "path", + "images" + ], + "type": "object" + }, + "KustomizeManifest": { + "additionalProperties": false, + "description": "KustomizeManifest defines kustomization settings for a manifest.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "allowAnyDirectory": { + "description": "Allow traversing directory above the current directory if needed for kustomization.", + "type": "boolean" + }, + "enablePlugins": { + "description": "Enable kustomize plugins when building manifests.", + "type": "boolean" + }, + "files": { "description": "List of local kustomization paths or remote URLs to include in the package.", "items": { "type": "string" }, "type": "array" - }, - "kustomizeAllowAnyDirectory": { - "description": "Allow traversing directory above the current directory if needed for kustomization. (Defaults to false)", + } + }, + "type": "object" + }, + "LocalSource": { + "additionalProperties": false, + "description": "LocalSource represents a Helm chart stored locally.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "path": { + "description": "The path to a local chart's folder or .tgz archive.", + "type": "string" + } + }, + "required": [ + "path" + ], + "type": "object" + }, + "Manifest": { + "additionalProperties": false, + "description": "Manifest defines raw manifests Zarf will deploy as a helm chart.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "enableValues": { + "description": "EnableValues enables go-template processing on these manifests during deploy.", "type": "boolean" }, + "files": { + "description": "List of local K8s YAML files or remote URLs to deploy (in order).", + "items": { + "type": "string" + }, + "type": "array" + }, + "kustomize": { + "$ref": "#/$defs/KustomizeManifest", + "description": "Kustomize settings for this manifest." + }, "name": { "description": "A name to give this collection of manifests; this will become the name of the dynamically-created helm chart.", + "maxLength": 40, "type": "string" }, "namespace": { @@ -1100,7 +810,7 @@ "type": "string" }, "serverSideApply": { - "description": "Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy.\n - \"true\": always use SSA\n - \"false\": always use CSA\n - \"auto\": use SSA for fresh installs; for upgrades, match whichever strategy\n was used when the chart was first installed\nDefaults to \"auto\" when omitted.", + "description": "Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy. Defaults to \"auto\" when omitted.", "enum": [ "true", "false", @@ -1108,12 +818,8 @@ ], "type": "string" }, - "template": { - "description": "Template enables go-template processing on these manifests during deploy.", - "type": "boolean" - }, - "wait": { - "description": "Whether to wait for manifest resources to be ready before continuing. Defaults to true.", + "skipWait": { + "description": "Whether to skip waiting for manifest resources to be ready before continuing.", "type": "boolean" } }, @@ -1122,17 +828,35 @@ ], "type": "object" }, - "ZarfMetadata": { + "OCISource": { "additionalProperties": false, - "description": "ZarfMetadata lists information about the current ZarfPackage.", + "description": "OCISource represents a Helm chart stored in an OCI registry.", "patternProperties": { "^x-": {} }, "properties": { - "allowNamespaceOverride": { - "description": "Whether to allow namespace overrides for this package.", - "type": "boolean" + "url": { + "description": "The URL of the OCI registry where the Helm chart is stored.", + "type": "string" }, + "version": { + "description": "The version of the chart in the OCI registry.", + "type": "string" + } + }, + "required": [ + "url", + "version" + ], + "type": "object" + }, + "PackageMetadata": { + "additionalProperties": false, + "description": "PackageMetadata holds information about the package.", + "patternProperties": { + "^x-": {} + }, + "properties": { "annotations": { "additionalProperties": { "type": "string" @@ -1157,12 +881,16 @@ "pattern": "^[a-z0-9][a-z0-9\\-]*$", "type": "string" }, + "preventNamespaceOverride": { + "description": "Prevent namespace overrides for this package.", + "type": "boolean" + }, "uncompressed": { "description": "Disable compression of this package.", "type": "boolean" }, "version": { - "description": "Generic string set by a package author to track the package version (Note: ZarfInitConfigs will always be versioned to the CLIVersion they were created with).", + "description": "Generic string set by a package author to track the package version.", "type": "string" } }, @@ -1171,9 +899,67 @@ ], "type": "object" }, - "ZarfValues": { + "SetValue": { + "additionalProperties": false, + "description": "SetValue declares a value that can be set during a package deploy.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "key": { + "description": "Key represents which value to assign to.", + "type": "string" + }, + "type": { + "description": "Type declares the kind of data being stored in the value.", + "type": "string" + }, + "value": { + "description": "Value is the current value at the key." + } + }, + "type": "object" + }, + "Shell": { + "additionalProperties": false, + "description": "Shell represents the desired shell to use for a given command.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "darwin": { + "description": "Darwin (macOS) shell preference.", + "examples": [ + "sh", + "bash", + "zsh" + ], + "type": "string" + }, + "linux": { + "description": "Linux shell preference.", + "examples": [ + "sh", + "bash", + "zsh" + ], + "type": "string" + }, + "windows": { + "description": "Windows shell preference.", + "examples": [ + "powershell", + "cmd", + "pwsh" + ], + "type": "string" + } + }, + "type": "object" + }, + "Values": { "additionalProperties": false, - "description": "ZarfValues defines values files and schema for templating and overriding Helm values.", + "description": "Values defines values files and schema for templating and overriding Helm values.", "patternProperties": { "^x-": {} }, @@ -1191,12 +977,34 @@ } }, "type": "object" + }, + "VersionRequirement": { + "additionalProperties": false, + "description": "VersionRequirement specifies a minimum Zarf version needed and the reason for the requirement.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "reason": { + "description": "The reason this version is required.", + "type": "string" + }, + "version": { + "description": "The minimum version of Zarf required.", + "type": "string" + } + }, + "required": [ + "version", + "reason" + ], + "type": "object" } }, - "$id": "https://github.com/zarf-dev/zarf/src/api/v1beta1/zarf-package", + "$id": "https://github.com/zarf-dev/zarf/src/api/v1beta1/package", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, - "description": "ZarfPackage the top-level structure of a Zarf config file.", + "description": "Package is the top-level structure of a Zarf package definition.", "patternProperties": { "^x-": {} }, @@ -1209,56 +1017,42 @@ "type": "string" }, "build": { - "$ref": "#/$defs/ZarfBuildData", + "$ref": "#/$defs/BuildData", "description": "Zarf-generated package build data." }, "components": { "description": "List of components to deploy in this package.", "items": { - "$ref": "#/$defs/ZarfComponent" - }, - "type": "array" - }, - "constants": { - "description": "Constant template values applied on deploy for K8s resources.", - "items": { - "$ref": "#/$defs/Constant" + "$ref": "#/$defs/Component" }, + "minItems": 1, "type": "array" }, "documentation": { "additionalProperties": { "type": "string" }, - "description": "Documentation files.", + "description": "Documentation files included in the package.", "type": "object" }, "kind": { - "default": "ZarfPackageConfig", "description": "The kind of Zarf package.", "enum": [ - "ZarfInitConfig", "ZarfPackageConfig" ], "type": "string" }, "metadata": { - "$ref": "#/$defs/ZarfMetadata", + "$ref": "#/$defs/PackageMetadata", "description": "Package metadata." }, "values": { - "$ref": "#/$defs/ZarfValues", - "description": "Values imports Zarf values files for templating." - }, - "variables": { - "description": "Variable template values applied on deploy for K8s resources.", - "items": { - "$ref": "#/$defs/InteractiveVariable" - }, - "type": "array" + "$ref": "#/$defs/Values", + "description": "Values imports Zarf values files for templating and overriding Helm values." } }, "required": [ + "apiVersion", "kind", "components" ], From 2894b0ba1a3adaa929e0b59f4f2d5d1ba36df7a9 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Thu, 28 May 2026 11:31:25 -0400 Subject: [PATCH 13/26] add deprecated fields Signed-off-by: Austin Abro --- src/api/v1beta1/component.go | 38 ++++++++++++++++++++++++++++++++++++ src/api/v1beta1/package.go | 26 ++++++++++++++++++++++++ 2 files changed, 64 insertions(+) diff --git a/src/api/v1beta1/component.go b/src/api/v1beta1/component.go index 6627332818..07e4b40b3e 100644 --- a/src/api/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -3,6 +3,8 @@ package v1beta1 +import "github.com/zarf-dev/zarf/src/api/v1alpha1" + // Component is the primary functional grouping of assets to deploy by Zarf. type Component struct { // The name of the component. @@ -31,6 +33,18 @@ type Component struct { Repositories []string `json:"repositories,omitempty"` // Custom commands to run at various stages of a package lifecycle. Actions ComponentActions `json:"actions,omitempty"` + // Data injections removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. + dataInjections []v1alpha1.ZarfDataInjection +} + +// GetDeprecatedDataInjections returns the v1alpha1 data injections carried as a backwards-compatibility shim. +func (c Component) GetDeprecatedDataInjections() []v1alpha1.ZarfDataInjection { + return c.dataInjections +} + +// SetDeprecatedDataInjections sets the v1alpha1 data injections carried as a backwards-compatibility shim. +func (c *Component) SetDeprecatedDataInjections(dataInjections []v1alpha1.ZarfDataInjection) { + c.dataInjections = dataInjections } // GetImages returns all image names specified in the component, including those from ImageArchives. @@ -164,6 +178,8 @@ type Chart struct { SkipSchemaValidation bool `json:"skipSchemaValidation,omitempty"` // Controls whether Helm uses Server-Side Apply (SSA) or client-side apply (CSA) when deploying this chart. Defaults to "auto" when omitted. ServerSideApply ServerSideApplyMode `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"` + // Chart variables removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. + variables []v1alpha1.ZarfChartVariable } // GetDeprecatedVersion returns the deprecated top-level chart version, used as a v1alpha1 backwards-compatibility shim. @@ -176,6 +192,16 @@ func (c *Chart) SetDeprecatedVersion(version string) { c.version = version } +// GetDeprecatedVariables returns the v1alpha1 chart variables carried as a backwards-compatibility shim. +func (c Chart) GetDeprecatedVariables() []v1alpha1.ZarfChartVariable { + return c.variables +} + +// SetDeprecatedVariables sets the v1alpha1 chart variables carried as a backwards-compatibility shim. +func (c *Chart) SetDeprecatedVariables(variables []v1alpha1.ZarfChartVariable) { + c.variables = variables +} + // ChartValue maps a values source path to a Helm chart target path. type ChartValue struct { // The source path for the value. @@ -312,6 +338,18 @@ type ComponentAction struct { Wait *ComponentActionWait `json:"wait,omitempty"` // EnableValues enables go-template processing on the cmd field. EnableValues bool `json:"enableValues,omitempty"` + // setVariables removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. + setVariables []v1alpha1.Variable +} + +// GetDeprecatedSetVariables returns the v1alpha1 setVariables carried as a backwards-compatibility shim. +func (a ComponentAction) GetDeprecatedSetVariables() []v1alpha1.Variable { + return a.setVariables +} + +// SetDeprecatedSetVariables sets the v1alpha1 setVariables carried as a backwards-compatibility shim. +func (a *ComponentAction) SetDeprecatedSetVariables(setVariables []v1alpha1.Variable) { + a.setVariables = setVariables } // SetValueType declares the expected input back from the cmd, allowing structured data to be parsed. diff --git a/src/api/v1beta1/package.go b/src/api/v1beta1/package.go index d9ed682f42..8cab16942f 100644 --- a/src/api/v1beta1/package.go +++ b/src/api/v1beta1/package.go @@ -4,6 +4,8 @@ // Package v1beta1 holds the definition of the v1beta1 Zarf Package. This API is work in progress and not yet used within Zarf. package v1beta1 +import "github.com/zarf-dev/zarf/src/api/v1alpha1" + // PackageKind is an enum of the different kinds of Zarf packages. type PackageKind string @@ -32,6 +34,30 @@ type Package struct { Values Values `json:"values,omitempty"` // Documentation files included in the package. Documentation map[string]string `json:"documentation,omitempty"` + // Variables removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. + variables []v1alpha1.InteractiveVariable + // Constants removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. + constants []v1alpha1.Constant +} + +// GetDeprecatedVariables returns the v1alpha1 variables carried as a backwards-compatibility shim. +func (pkg Package) GetDeprecatedVariables() []v1alpha1.InteractiveVariable { + return pkg.variables +} + +// SetDeprecatedVariables sets the v1alpha1 variables carried as a backwards-compatibility shim. +func (pkg *Package) SetDeprecatedVariables(variables []v1alpha1.InteractiveVariable) { + pkg.variables = variables +} + +// GetDeprecatedConstants returns the v1alpha1 constants carried as a backwards-compatibility shim. +func (pkg Package) GetDeprecatedConstants() []v1alpha1.Constant { + return pkg.constants +} + +// SetDeprecatedConstants sets the v1alpha1 constants carried as a backwards-compatibility shim. +func (pkg *Package) SetDeprecatedConstants(constants []v1alpha1.Constant) { + pkg.constants = constants } // HasImages returns true if one of the components contains an image. From b2eb1d25149e0d5aefe33bb661886de312fd3053 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Thu, 28 May 2026 11:45:59 -0400 Subject: [PATCH 14/26] add in missing fields Signed-off-by: Austin Abro --- src/api/v1alpha1/package.go | 2 -- src/api/v1beta1/package.go | 6 ++++++ src/pkg/schema/zarf-v1alpha1-schema.json | 4 ---- src/pkg/schema/zarf-v1beta1-schema.json | 15 +++++++++++++++ 4 files changed, 21 insertions(+), 6 deletions(-) diff --git a/src/api/v1alpha1/package.go b/src/api/v1alpha1/package.go index a10a0902db..d77cce55f3 100644 --- a/src/api/v1alpha1/package.go +++ b/src/api/v1alpha1/package.go @@ -267,8 +267,6 @@ type ZarfBuildData struct { Flavor string `json:"flavor,omitempty" jsonschema:"pattern=^[^/\\\\]*$"` // Whether this package was signed Signed *bool `json:"signed,omitempty"` - // The API version defined in the package definition used to build the package. - APIVersion string `json:"apiVersion,omitempty"` // Requirements for specific package operations. VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"` // ProvenanceFiles lists files present in the package that are not included in checksums.txt. diff --git a/src/api/v1beta1/package.go b/src/api/v1beta1/package.go index 8cab16942f..464d248a49 100644 --- a/src/api/v1beta1/package.go +++ b/src/api/v1beta1/package.go @@ -116,10 +116,16 @@ type BuildData struct { RegistryOverrides map[string]string `json:"registryOverrides,omitempty"` // Whether this package was created with differential components. Differential bool `json:"differential,omitempty"` + // Version of a previously built package used as the basis for creating this differential package. + DifferentialPackageVersion string `json:"differentialPackageVersion,omitempty"` // The flavor of Zarf used to build this package. Flavor string `json:"flavor,omitempty"` + // Whether this package was signed. + Signed *bool `json:"signed,omitempty"` // Requirements for specific Zarf versions needed to deploy this package. VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"` + // ProvenanceFiles lists files present in the package that are not included in checksums.txt. These are files added after checksum generation (e.g., signature files). + ProvenanceFiles []string `json:"provenanceFiles,omitempty"` // Checksum of a checksums.txt file that contains checksums all the layers within the package. AggregateChecksum string `json:"aggregateChecksum,omitempty"` } diff --git a/src/pkg/schema/zarf-v1alpha1-schema.json b/src/pkg/schema/zarf-v1alpha1-schema.json index 4605b67116..7e7b2ea428 100644 --- a/src/pkg/schema/zarf-v1alpha1-schema.json +++ b/src/pkg/schema/zarf-v1alpha1-schema.json @@ -316,10 +316,6 @@ "^x-": {} }, "properties": { - "apiVersion": { - "description": "The API version defined in the package definition used to build the package.", - "type": "string" - }, "architecture": { "description": "The architecture this package was created on.", "type": "string" diff --git a/src/pkg/schema/zarf-v1beta1-schema.json b/src/pkg/schema/zarf-v1beta1-schema.json index b3c123e9e4..0c3ee4761e 100644 --- a/src/pkg/schema/zarf-v1beta1-schema.json +++ b/src/pkg/schema/zarf-v1beta1-schema.json @@ -19,6 +19,10 @@ "description": "Whether this package was created with differential components.", "type": "boolean" }, + "differentialPackageVersion": { + "description": "Version of a previously built package used as the basis for creating this differential package.", + "type": "string" + }, "flavor": { "description": "The flavor of Zarf used to build this package.", "type": "string" @@ -34,6 +38,13 @@ }, "type": "array" }, + "provenanceFiles": { + "description": "ProvenanceFiles lists files present in the package that are not included in checksums.txt. These are files added after checksum generation (e.g., signature files).", + "items": { + "type": "string" + }, + "type": "array" + }, "registryOverrides": { "additionalProperties": { "type": "string" @@ -41,6 +52,10 @@ "description": "Any registry domains that were overridden on package create when pulling images.", "type": "object" }, + "signed": { + "description": "Whether this package was signed.", + "type": "boolean" + }, "timestamp": { "description": "The timestamp when this package was created.", "type": "string" From 081a9f2548eb6832e0189bb92df7aa203ca2ccec Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Fri, 29 May 2026 09:26:53 -0400 Subject: [PATCH 15/26] docs and schema Signed-off-by: Austin Abro --- zarf.schema.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/zarf.schema.json b/zarf.schema.json index 4605b67116..7e7b2ea428 100644 --- a/zarf.schema.json +++ b/zarf.schema.json @@ -316,10 +316,6 @@ "^x-": {} }, "properties": { - "apiVersion": { - "description": "The API version defined in the package definition used to build the package.", - "type": "string" - }, "architecture": { "description": "The architecture this package was created on.", "type": "string" From 6cd42e3b28aa1f5b0b5c27c88b824b575771c9eb Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Fri, 29 May 2026 09:38:37 -0400 Subject: [PATCH 16/26] component spec Signed-off-by: Austin Abro --- src/api/v1beta1/component.go | 21 +-- src/api/v1beta1/componentConfig.go | 26 ++- src/api/v1beta1/component_test.go | 52 +++--- src/api/v1beta1/package_test.go | 14 +- .../schema/zarf-v1beta1-component-schema.json | 168 ++++++++---------- 5 files changed, 139 insertions(+), 142 deletions(-) diff --git a/src/api/v1beta1/component.go b/src/api/v1beta1/component.go index 07e4b40b3e..f6f51231f0 100644 --- a/src/api/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -13,26 +13,7 @@ type Component struct { Description string `json:"description,omitempty"` // Do not install this component unless explicitly requested. Defaults to false, meaning the component is required. Optional bool `json:"optional,omitempty"` - // Filter when this component is included in package creation or deployment. - Target ComponentTarget `json:"target,omitempty"` - // Import a component from another Zarf component config. - Import ComponentImport `json:"import,omitempty"` - // The Zarf CLI service this component provides, such as the registry, injector, or agent. - Service Service `json:"service,omitempty" jsonschema:"enum=registry,enum=seed-registry,enum=injector,enum=agent,enum=git-server"` - // Kubernetes manifests to be included in a generated Helm chart on package deploy. - Manifests []Manifest `json:"manifests,omitempty"` - // Helm charts to install during package deploy. - Charts []Chart `json:"charts,omitempty"` - // Files or folders to place on disk during package deployment. - Files []File `json:"files,omitempty"` - // List of OCI images to include in the package. - Images []Image `json:"images,omitempty"` - // List of tar archives of images to include in the package. - ImageArchives []ImageArchive `json:"imageArchives,omitempty"` - // List of git repositories to include in the package. - Repositories []string `json:"repositories,omitempty"` - // Custom commands to run at various stages of a package lifecycle. - Actions ComponentActions `json:"actions,omitempty"` + ComponentSpec // Data injections removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. dataInjections []v1alpha1.ZarfDataInjection } diff --git a/src/api/v1beta1/componentConfig.go b/src/api/v1beta1/componentConfig.go index a3ad00cdcb..c5e756d930 100644 --- a/src/api/v1beta1/componentConfig.go +++ b/src/api/v1beta1/componentConfig.go @@ -12,13 +12,37 @@ type ComponentConfig struct { // Component metadata. Metadata ComponentMetadata `json:"metadata"` // The single component this config defines. - Component Component `json:"component"` + Component ComponentSpec `json:"component"` // Values imports Zarf values files for templating and overriding Helm values. Values Values `json:"values,omitempty"` // Zarf-generated publish data for the component config. PublishData ComponentPublishData `json:"publishData,omitempty"` } +// ComponentSpec is a reduced component definition used in component configs. +type ComponentSpec struct { + // Import a component from another Zarf component config. + Import ComponentImport `json:"import,omitempty"` + // Filter when this component is included in package creation or deployment. + Target ComponentTarget `json:"target,omitempty"` + // Kubernetes manifests to be included in a generated Helm chart on package deploy. + Manifests []Manifest `json:"manifests,omitempty"` + // Helm charts to install during package deploy. + Charts []Chart `json:"charts,omitempty"` + // Files or folders to place on disk during package deployment. + Files []File `json:"files,omitempty"` + // List of OCI images to include in the package. + Images []Image `json:"images,omitempty"` + // List of tar archives of images to include in the package. + ImageArchives []ImageArchive `json:"imageArchives,omitempty"` + // List of git repositories to include in the package. + Repositories []string `json:"repositories,omitempty"` + // Custom commands to run at various stages of a package lifecycle. + Actions ComponentActions `json:"actions,omitempty"` + // The Zarf CLI service this component provides, such as the registry, injector, or agent. + Service Service `json:"service,omitempty" jsonschema:"enum=registry,enum=seed-registry,enum=injector,enum=agent,enum=git-server"` +} + // ComponentMetadata holds metadata about a component config. type ComponentMetadata struct { // Name to identify this component config. diff --git a/src/api/v1beta1/component_test.go b/src/api/v1beta1/component_test.go index abc2a87002..e6f769aff7 100644 --- a/src/api/v1beta1/component_test.go +++ b/src/api/v1beta1/component_test.go @@ -28,9 +28,11 @@ func TestGetImages(t *testing.T) { name: "only Images field", component: Component{ Name: "test-component", - Images: []Image{ - {Name: "docker.io/library/nginx:latest"}, - {Name: "ghcr.io/zarf-dev/zarf:v0.32.6"}, + ComponentSpec: ComponentSpec{ + Images: []Image{ + {Name: "docker.io/library/nginx:latest"}, + {Name: "ghcr.io/zarf-dev/zarf:v0.32.6"}, + }, }, }, expected: []string{ @@ -42,12 +44,14 @@ func TestGetImages(t *testing.T) { name: "only ImageArchives with images", component: Component{ Name: "test-component", - ImageArchives: []ImageArchive{ - { - Path: "/tmp/images.tar", - Images: []string{ - "docker.io/library/redis:latest", - "docker.io/library/postgres:14", + ComponentSpec: ComponentSpec{ + ImageArchives: []ImageArchive{ + { + Path: "/tmp/images.tar", + Images: []string{ + "docker.io/library/redis:latest", + "docker.io/library/postgres:14", + }, }, }, }, @@ -61,21 +65,23 @@ func TestGetImages(t *testing.T) { name: "both Images and ImageArchives", component: Component{ Name: "test-component", - Images: []Image{ - {Name: "docker.io/library/nginx:latest"}, - }, - ImageArchives: []ImageArchive{ - { - Path: "/tmp/images1.tar", - Images: []string{ - "docker.io/library/redis:latest", - }, + ComponentSpec: ComponentSpec{ + Images: []Image{ + {Name: "docker.io/library/nginx:latest"}, }, - { - Path: "/tmp/images2.tar", - Images: []string{ - "docker.io/library/postgres:14", - "ghcr.io/zarf-dev/zarf:v0.32.6", + ImageArchives: []ImageArchive{ + { + Path: "/tmp/images1.tar", + Images: []string{ + "docker.io/library/redis:latest", + }, + }, + { + Path: "/tmp/images2.tar", + Images: []string{ + "docker.io/library/postgres:14", + "ghcr.io/zarf-dev/zarf:v0.32.6", + }, }, }, }, diff --git a/src/api/v1beta1/package_test.go b/src/api/v1beta1/package_test.go index f5fa692dbe..9a51596922 100644 --- a/src/api/v1beta1/package_test.go +++ b/src/api/v1beta1/package_test.go @@ -23,8 +23,8 @@ func TestPackageHasImages(t *testing.T) { pkg = Package{ Components: []Component{ { - Name: "with images", - Images: []Image{{Name: "docker.io/library/alpine:latest"}}, + Name: "with images", + ComponentSpec: ComponentSpec{Images: []Image{{Name: "docker.io/library/alpine:latest"}}}, }, }, } @@ -75,10 +75,12 @@ func TestPackageIsSBOMable(t *testing.T) { pkg := Package{ Components: []Component{ { - Name: "test-component", - Images: tt.images, - Files: tt.files, - ImageArchives: tt.imageArchives, + Name: "test-component", + ComponentSpec: ComponentSpec{ + Images: tt.images, + Files: tt.files, + ImageArchives: tt.imageArchives, + }, }, }, } diff --git a/src/pkg/schema/zarf-v1beta1-component-schema.json b/src/pkg/schema/zarf-v1beta1-component-schema.json index 194169dc0c..469d92c2d0 100644 --- a/src/pkg/schema/zarf-v1beta1-component-schema.json +++ b/src/pkg/schema/zarf-v1beta1-component-schema.json @@ -94,97 +94,6 @@ ], "type": "object" }, - "Component": { - "additionalProperties": false, - "description": "Component is the primary functional grouping of assets to deploy by Zarf.", - "patternProperties": { - "^x-": {} - }, - "properties": { - "actions": { - "$ref": "#/$defs/ComponentActions", - "description": "Custom commands to run at various stages of a package lifecycle." - }, - "charts": { - "description": "Helm charts to install during package deploy.", - "items": { - "$ref": "#/$defs/Chart" - }, - "type": "array" - }, - "description": { - "description": "Message to include during package deploy describing the purpose of this component.", - "type": "string" - }, - "files": { - "description": "Files or folders to place on disk during package deployment.", - "items": { - "$ref": "#/$defs/File" - }, - "type": "array" - }, - "imageArchives": { - "description": "List of tar archives of images to include in the package.", - "items": { - "$ref": "#/$defs/ImageArchive" - }, - "type": "array" - }, - "images": { - "description": "List of OCI images to include in the package.", - "items": { - "$ref": "#/$defs/Image" - }, - "type": "array" - }, - "import": { - "$ref": "#/$defs/ComponentImport", - "description": "Import a component from another Zarf component config." - }, - "manifests": { - "description": "Kubernetes manifests to be included in a generated Helm chart on package deploy.", - "items": { - "$ref": "#/$defs/Manifest" - }, - "type": "array" - }, - "name": { - "description": "The name of the component.", - "pattern": "^[a-z0-9][a-z0-9\\-]*$", - "type": "string" - }, - "optional": { - "description": "Do not install this component unless explicitly requested. Defaults to false, meaning the component is required.", - "type": "boolean" - }, - "repositories": { - "description": "List of git repositories to include in the package.", - "items": { - "type": "string" - }, - "type": "array" - }, - "service": { - "description": "The Zarf CLI service this component provides, such as the registry, injector, or agent.", - "enum": [ - "registry", - "seed-registry", - "injector", - "agent", - "git-server" - ], - "type": "string" - }, - "target": { - "$ref": "#/$defs/ComponentTarget", - "description": "Filter when this component is included in package creation or deployment." - } - }, - "required": [ - "name" - ], - "type": "object" - }, "ComponentAction": { "additionalProperties": false, "description": "ComponentAction represents a single action to run during a Zarf package operation.", @@ -559,6 +468,81 @@ ], "type": "object" }, + "ComponentSpec": { + "additionalProperties": false, + "description": "ComponentSpec is a reduced component definition used in component configs.", + "patternProperties": { + "^x-": {} + }, + "properties": { + "actions": { + "$ref": "#/$defs/ComponentActions", + "description": "Custom commands to run at various stages of a package lifecycle." + }, + "charts": { + "description": "Helm charts to install during package deploy.", + "items": { + "$ref": "#/$defs/Chart" + }, + "type": "array" + }, + "files": { + "description": "Files or folders to place on disk during package deployment.", + "items": { + "$ref": "#/$defs/File" + }, + "type": "array" + }, + "imageArchives": { + "description": "List of tar archives of images to include in the package.", + "items": { + "$ref": "#/$defs/ImageArchive" + }, + "type": "array" + }, + "images": { + "description": "List of OCI images to include in the package.", + "items": { + "$ref": "#/$defs/Image" + }, + "type": "array" + }, + "import": { + "$ref": "#/$defs/ComponentImport", + "description": "Import a component from another Zarf component config." + }, + "manifests": { + "description": "Kubernetes manifests to be included in a generated Helm chart on package deploy.", + "items": { + "$ref": "#/$defs/Manifest" + }, + "type": "array" + }, + "repositories": { + "description": "List of git repositories to include in the package.", + "items": { + "type": "string" + }, + "type": "array" + }, + "service": { + "description": "The Zarf CLI service this component provides, such as the registry, injector, or agent.", + "enum": [ + "registry", + "seed-registry", + "injector", + "agent", + "git-server" + ], + "type": "string" + }, + "target": { + "$ref": "#/$defs/ComponentTarget", + "description": "Filter when this component is included in package creation or deployment." + } + }, + "type": "object" + }, "ComponentTarget": { "additionalProperties": false, "description": "ComponentTarget filters a component to only apply for a given local OS, architecture, or flavor.", @@ -964,7 +948,7 @@ "type": "string" }, "component": { - "$ref": "#/$defs/Component", + "$ref": "#/$defs/ComponentSpec", "description": "The single component this config defines." }, "kind": { From 9bcc98a4acb29edd9b8d3ea16b82131659b81f2e Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Fri, 29 May 2026 10:11:07 -0400 Subject: [PATCH 17/26] original API version Signed-off-by: Austin Abro --- src/api/v1alpha1/package.go | 12 ++++++++++++ src/api/v1beta1/package.go | 12 ++++++++++++ 2 files changed, 24 insertions(+) diff --git a/src/api/v1alpha1/package.go b/src/api/v1alpha1/package.go index d77cce55f3..9f6068ad9e 100644 --- a/src/api/v1alpha1/package.go +++ b/src/api/v1alpha1/package.go @@ -273,6 +273,18 @@ type ZarfBuildData struct { // These are files added after checksum generation (e.g., signature files). // This list is authenticated through the signed zarf.yaml. ProvenanceFiles []string `json:"provenanceFiles,omitempty"` + // originalAPIVersion records the apiVersion the package was read from before any conversion. + originalAPIVersion string +} + +// OriginalAPIVersion returns the apiVersion the package was read from before any conversion. +func (b ZarfBuildData) OriginalAPIVersion() string { + return b.originalAPIVersion +} + +// SetOriginalAPIVersion records the apiVersion the package was read from before any conversion. +func (b *ZarfBuildData) SetOriginalAPIVersion(apiVersion string) { + b.originalAPIVersion = apiVersion } // ZarfValues imports package-level values files and validation. diff --git a/src/api/v1beta1/package.go b/src/api/v1beta1/package.go index 464d248a49..0a36c8d873 100644 --- a/src/api/v1beta1/package.go +++ b/src/api/v1beta1/package.go @@ -128,6 +128,18 @@ type BuildData struct { ProvenanceFiles []string `json:"provenanceFiles,omitempty"` // Checksum of a checksums.txt file that contains checksums all the layers within the package. AggregateChecksum string `json:"aggregateChecksum,omitempty"` + // originalAPIVersion records the apiVersion the package was read from before any conversion. + originalAPIVersion string +} + +// OriginalAPIVersion returns the apiVersion the package was read from before any conversion. +func (b BuildData) OriginalAPIVersion() string { + return b.originalAPIVersion +} + +// SetOriginalAPIVersion records the apiVersion the package was read from before any conversion. +func (b *BuildData) SetOriginalAPIVersion(apiVersion string) { + b.originalAPIVersion = apiVersion } // VersionRequirement specifies a minimum Zarf version needed and the reason for the requirement. From 7498a0da658d22bc2ce1a4d5b44b8ecaddd5f022 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 1 Jun 2026 09:08:26 -0400 Subject: [PATCH 18/26] yolo and group Signed-off-by: Austin Abro --- src/api/v1beta1/component.go | 12 ++++++++++++ src/api/v1beta1/package.go | 12 ++++++++++++ 2 files changed, 24 insertions(+) diff --git a/src/api/v1beta1/component.go b/src/api/v1beta1/component.go index f6f51231f0..1fd7527af7 100644 --- a/src/api/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -16,6 +16,8 @@ type Component struct { ComponentSpec // Data injections removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. dataInjections []v1alpha1.ZarfDataInjection + // group removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. + group string } // GetDeprecatedDataInjections returns the v1alpha1 data injections carried as a backwards-compatibility shim. @@ -28,6 +30,16 @@ func (c *Component) SetDeprecatedDataInjections(dataInjections []v1alpha1.ZarfDa c.dataInjections = dataInjections } +// GetDeprecatedGroup returns the v1alpha1 group carried as a backwards-compatibility shim. +func (c Component) GetDeprecatedGroup() string { + return c.group +} + +// SetDeprecatedGroup sets the v1alpha1 group carried as a backwards-compatibility shim. +func (c *Component) SetDeprecatedGroup(group string) { + c.group = group +} + // GetImages returns all image names specified in the component, including those from ImageArchives. func (c Component) GetImages() []string { images := []string{} diff --git a/src/api/v1beta1/package.go b/src/api/v1beta1/package.go index 0a36c8d873..c9da64e05d 100644 --- a/src/api/v1beta1/package.go +++ b/src/api/v1beta1/package.go @@ -96,6 +96,18 @@ type PackageMetadata struct { Annotations map[string]string `json:"annotations,omitempty"` // Prevent namespace overrides for this package. PreventNamespaceOverride bool `json:"preventNamespaceOverride,omitempty"` + // yolo removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. + yolo bool +} + +// GetDeprecatedYOLO returns the v1alpha1 YOLO field carried as a backwards-compatibility shim. +func (m PackageMetadata) GetDeprecatedYOLO() bool { + return m.yolo +} + +// SetDeprecatedYOLO sets the v1alpha1 YOLO field carried as a backwards-compatibility shim. +func (m *PackageMetadata) SetDeprecatedYOLO(yolo bool) { + m.yolo = yolo } // BuildData is written during package create to track details of the created package. From d50c81eaf79587716ee25ebd417a940581dc3a9f Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Tue, 2 Jun 2026 12:07:40 -0400 Subject: [PATCH 19/26] stop importing v1alpha1 Signed-off-by: Austin Abro --- src/api/v1beta1/component.go | 41 ++++------------ src/api/v1beta1/deprecated.go | 89 +++++++++++++++++++++++++++++++++++ src/api/v1beta1/package.go | 30 +++--------- 3 files changed, 104 insertions(+), 56 deletions(-) create mode 100644 src/api/v1beta1/deprecated.go diff --git a/src/api/v1beta1/component.go b/src/api/v1beta1/component.go index 1fd7527af7..3865838566 100644 --- a/src/api/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -3,8 +3,6 @@ package v1beta1 -import "github.com/zarf-dev/zarf/src/api/v1alpha1" - // Component is the primary functional grouping of assets to deploy by Zarf. type Component struct { // The name of the component. @@ -14,32 +12,23 @@ type Component struct { // Do not install this component unless explicitly requested. Defaults to false, meaning the component is required. Optional bool `json:"optional,omitempty"` ComponentSpec + // Data injections removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. - dataInjections []v1alpha1.ZarfDataInjection + dataInjections []ZarfDataInjection // group removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. group string } // GetDeprecatedDataInjections returns the v1alpha1 data injections carried as a backwards-compatibility shim. -func (c Component) GetDeprecatedDataInjections() []v1alpha1.ZarfDataInjection { +func (c Component) GetDeprecatedDataInjections() []ZarfDataInjection { return c.dataInjections } -// SetDeprecatedDataInjections sets the v1alpha1 data injections carried as a backwards-compatibility shim. -func (c *Component) SetDeprecatedDataInjections(dataInjections []v1alpha1.ZarfDataInjection) { - c.dataInjections = dataInjections -} - // GetDeprecatedGroup returns the v1alpha1 group carried as a backwards-compatibility shim. func (c Component) GetDeprecatedGroup() string { return c.group } -// SetDeprecatedGroup sets the v1alpha1 group carried as a backwards-compatibility shim. -func (c *Component) SetDeprecatedGroup(group string) { - c.group = group -} - // GetImages returns all image names specified in the component, including those from ImageArchives. func (c Component) GetImages() []string { images := []string{} @@ -171,8 +160,9 @@ type Chart struct { SkipSchemaValidation bool `json:"skipSchemaValidation,omitempty"` // Controls whether Helm uses Server-Side Apply (SSA) or client-side apply (CSA) when deploying this chart. Defaults to "auto" when omitted. ServerSideApply ServerSideApplyMode `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"` + // Chart variables removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. - variables []v1alpha1.ZarfChartVariable + variables []ZarfChartVariable } // GetDeprecatedVersion returns the deprecated top-level chart version, used as a v1alpha1 backwards-compatibility shim. @@ -180,21 +170,11 @@ func (c Chart) GetDeprecatedVersion() string { return c.version } -// SetDeprecatedVersion sets the deprecated top-level chart version, used as a v1alpha1 backwards-compatibility shim. -func (c *Chart) SetDeprecatedVersion(version string) { - c.version = version -} - // GetDeprecatedVariables returns the v1alpha1 chart variables carried as a backwards-compatibility shim. -func (c Chart) GetDeprecatedVariables() []v1alpha1.ZarfChartVariable { +func (c Chart) GetDeprecatedVariables() []ZarfChartVariable { return c.variables } -// SetDeprecatedVariables sets the v1alpha1 chart variables carried as a backwards-compatibility shim. -func (c *Chart) SetDeprecatedVariables(variables []v1alpha1.ZarfChartVariable) { - c.variables = variables -} - // ChartValue maps a values source path to a Helm chart target path. type ChartValue struct { // The source path for the value. @@ -332,19 +312,14 @@ type ComponentAction struct { // EnableValues enables go-template processing on the cmd field. EnableValues bool `json:"enableValues,omitempty"` // setVariables removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. - setVariables []v1alpha1.Variable + setVariables []Variable } // GetDeprecatedSetVariables returns the v1alpha1 setVariables carried as a backwards-compatibility shim. -func (a ComponentAction) GetDeprecatedSetVariables() []v1alpha1.Variable { +func (a ComponentAction) GetDeprecatedSetVariables() []Variable { return a.setVariables } -// SetDeprecatedSetVariables sets the v1alpha1 setVariables carried as a backwards-compatibility shim. -func (a *ComponentAction) SetDeprecatedSetVariables(setVariables []v1alpha1.Variable) { - a.setVariables = setVariables -} - // SetValueType declares the expected input back from the cmd, allowing structured data to be parsed. type SetValueType string diff --git a/src/api/v1beta1/deprecated.go b/src/api/v1beta1/deprecated.go new file mode 100644 index 0000000000..7ac60fd6b0 --- /dev/null +++ b/src/api/v1beta1/deprecated.go @@ -0,0 +1,89 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: 2021-Present The Zarf Authors + +package v1beta1 + +// These types are duplicated from v1alpha1 and carried as backwards-compatibility +// shims so v1alpha1 packages can be converted to v1beta1 without v1beta1 importing +// v1alpha1. They are not part of the v1beta1 schema. + +// VariableType represents a type of a Zarf package variable. +type VariableType string + +const ( + // RawVariableType is the default type for a Zarf package variable. + RawVariableType VariableType = "raw" + // FileVariableType is a type for a Zarf package variable that loads its contents from a file. + FileVariableType VariableType = "file" +) + +// Variable represents a variable that has a value set programmatically. +type Variable struct { + // The name to be used for the variable. + Name string + // Whether to mark this variable as sensitive to not print it in the log. + Sensitive bool + // Whether to automatically indent the variable's value (if multiline) when templating. + AutoIndent bool + // An optional regex pattern that a variable value must match before a package deployment can continue. + Pattern string + // Changes the handling of a variable to load contents differently (i.e. from a file rather than as a raw variable). + Type VariableType +} + +// InteractiveVariable is a variable that can be used to prompt a user for more information. +type InteractiveVariable struct { + Variable + // A description of the variable to be used when prompting the user a value. + Description string + // The default value to use for the variable. + Default string + // Whether to prompt the user for input for this variable. + Prompt bool +} + +// Constant are constants that can be used to dynamically template K8s resources or run in actions. +type Constant struct { + // The name to be used for the constant. + Name string + // The value to set for the constant during deploy. + Value string + // A description of the constant to explain its purpose on package create or deploy confirmation prompts. + Description string + // Whether to automatically indent the variable's value (if multiline) when templating. + AutoIndent bool + // An optional regex pattern that a constant value must match before a package can be created. + Pattern string +} + +// ZarfChartVariable represents a variable that can be set for a Helm chart overrides. +type ZarfChartVariable struct { + // The name of the variable. + Name string + // A brief description of what the variable controls. + Description string + // The path within the Helm chart values where this variable applies. + Path string +} + +// ZarfContainerTarget defines the destination info for a ZarfDataInjection target. +type ZarfContainerTarget struct { + // The namespace to target for data injection. + Namespace string + // The K8s selector to target for data injection. + Selector string + // The container name to target for data injection. + Container string + // The path within the container to copy the data into. + Path string +} + +// ZarfDataInjection is a data-injection definition. +type ZarfDataInjection struct { + // Either a path to a local folder/file or a remote URL of a file to inject into the given target pod + container. + Source string + // The target pod + container to inject the data into. + Target ZarfContainerTarget + // Compress the data before transmitting using gzip. + Compress bool +} diff --git a/src/api/v1beta1/package.go b/src/api/v1beta1/package.go index c9da64e05d..b16961f453 100644 --- a/src/api/v1beta1/package.go +++ b/src/api/v1beta1/package.go @@ -4,8 +4,6 @@ // Package v1beta1 holds the definition of the v1beta1 Zarf Package. This API is work in progress and not yet used within Zarf. package v1beta1 -import "github.com/zarf-dev/zarf/src/api/v1alpha1" - // PackageKind is an enum of the different kinds of Zarf packages. type PackageKind string @@ -34,32 +32,23 @@ type Package struct { Values Values `json:"values,omitempty"` // Documentation files included in the package. Documentation map[string]string `json:"documentation,omitempty"` + // Variables removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. - variables []v1alpha1.InteractiveVariable + variables []InteractiveVariable // Constants removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. - constants []v1alpha1.Constant + constants []Constant } // GetDeprecatedVariables returns the v1alpha1 variables carried as a backwards-compatibility shim. -func (pkg Package) GetDeprecatedVariables() []v1alpha1.InteractiveVariable { +func (pkg Package) GetDeprecatedVariables() []InteractiveVariable { return pkg.variables } -// SetDeprecatedVariables sets the v1alpha1 variables carried as a backwards-compatibility shim. -func (pkg *Package) SetDeprecatedVariables(variables []v1alpha1.InteractiveVariable) { - pkg.variables = variables -} - // GetDeprecatedConstants returns the v1alpha1 constants carried as a backwards-compatibility shim. -func (pkg Package) GetDeprecatedConstants() []v1alpha1.Constant { +func (pkg Package) GetDeprecatedConstants() []Constant { return pkg.constants } -// SetDeprecatedConstants sets the v1alpha1 constants carried as a backwards-compatibility shim. -func (pkg *Package) SetDeprecatedConstants(constants []v1alpha1.Constant) { - pkg.constants = constants -} - // HasImages returns true if one of the components contains an image. func (pkg Package) HasImages() bool { for _, component := range pkg.Components { @@ -105,11 +94,6 @@ func (m PackageMetadata) GetDeprecatedYOLO() bool { return m.yolo } -// SetDeprecatedYOLO sets the v1alpha1 YOLO field carried as a backwards-compatibility shim. -func (m *PackageMetadata) SetDeprecatedYOLO(yolo bool) { - m.yolo = yolo -} - // BuildData is written during package create to track details of the created package. type BuildData struct { // The machine name that created this package. @@ -144,8 +128,8 @@ type BuildData struct { originalAPIVersion string } -// OriginalAPIVersion returns the apiVersion the package was read from before any conversion. -func (b BuildData) OriginalAPIVersion() string { +// GetOriginalAPIVersion returns the apiVersion the package was read from before any conversion. +func (b BuildData) GetOriginalAPIVersion() string { return b.originalAPIVersion } From 43f70c25e940a8772fd247d4a7d945e80ff923ea Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Tue, 2 Jun 2026 16:24:51 -0400 Subject: [PATCH 20/26] package schema Signed-off-by: Austin Abro --- src/pkg/schema/generate.go | 2 +- ...arf-v1beta1-schema.json => zarf-v1beta1-package-schema.json} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename src/pkg/schema/{zarf-v1beta1-schema.json => zarf-v1beta1-package-schema.json} (100%) diff --git a/src/pkg/schema/generate.go b/src/pkg/schema/generate.go index 11165f4c31..af73b1daca 100644 --- a/src/pkg/schema/generate.go +++ b/src/pkg/schema/generate.go @@ -23,7 +23,7 @@ func main() { fmt.Println(err.Error()) os.Exit(1) } - if err := writeSchema("v1beta1", "zarf-v1beta1-schema.json", &v1beta1.Package{}); err != nil { + if err := writeSchema("v1beta1", "zarf-v1beta1-package-schema.json", &v1beta1.Package{}); err != nil { fmt.Println(err.Error()) os.Exit(1) } diff --git a/src/pkg/schema/zarf-v1beta1-schema.json b/src/pkg/schema/zarf-v1beta1-package-schema.json similarity index 100% rename from src/pkg/schema/zarf-v1beta1-schema.json rename to src/pkg/schema/zarf-v1beta1-package-schema.json From 5c0be33d820fdb6475d1d22b4853296ff1ff7bcf Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Tue, 2 Jun 2026 16:27:07 -0400 Subject: [PATCH 21/26] snake case Signed-off-by: Austin Abro --- src/api/v1beta1/{componentConfig.go => component_config.go} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/api/v1beta1/{componentConfig.go => component_config.go} (100%) diff --git a/src/api/v1beta1/componentConfig.go b/src/api/v1beta1/component_config.go similarity index 100% rename from src/api/v1beta1/componentConfig.go rename to src/api/v1beta1/component_config.go From d5ba3bc89c41312a7c32130c266cbeeb69a5536b Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Tue, 2 Jun 2026 16:36:13 -0400 Subject: [PATCH 22/26] value was unused Signed-off-by: Austin Abro --- src/api/v1beta1/component.go | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/api/v1beta1/component.go b/src/api/v1beta1/component.go index 3865838566..ad102aa843 100644 --- a/src/api/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -336,8 +336,6 @@ const ( type SetValue struct { // Key represents which value to assign to. Key string `json:"key,omitempty"` - // Value is the current value at the key. - Value any `json:"value,omitempty"` // Type declares the kind of data being stored in the value. Type SetValueType `json:"type,omitempty"` } From c24f772513c7e6851a8b6b416e4a301b242ab4c1 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Tue, 2 Jun 2026 16:42:04 -0400 Subject: [PATCH 23/26] omit empty Signed-off-by: Austin Abro --- src/api/v1beta1/package.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/api/v1beta1/package.go b/src/api/v1beta1/package.go index b16961f453..ca859bbce0 100644 --- a/src/api/v1beta1/package.go +++ b/src/api/v1beta1/package.go @@ -100,10 +100,10 @@ type BuildData struct { Hostname string `json:"hostname,omitempty"` // The username who created this package. User string `json:"user,omitempty"` + // The timestamp when this package was created. + Timestamp string `json:"timestamp,omitempty"` // The architecture this package was created on. Architecture string `json:"architecture"` - // The timestamp when this package was created. - Timestamp string `json:"timestamp"` // The version of Zarf used to build this package. Version string `json:"version"` // Any migrations that have been run on this package. @@ -123,7 +123,7 @@ type BuildData struct { // ProvenanceFiles lists files present in the package that are not included in checksums.txt. These are files added after checksum generation (e.g., signature files). ProvenanceFiles []string `json:"provenanceFiles,omitempty"` // Checksum of a checksums.txt file that contains checksums all the layers within the package. - AggregateChecksum string `json:"aggregateChecksum,omitempty"` + AggregateChecksum string `json:"aggregateChecksum"` // originalAPIVersion records the apiVersion the package was read from before any conversion. originalAPIVersion string } From ce2f4a426aacaeb412bb2a8b2e0586f7476c0f96 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Thu, 4 Jun 2026 13:16:00 -0400 Subject: [PATCH 24/26] inline Signed-off-by: Austin Abro --- src/api/v1beta1/component.go | 4 ++-- src/pkg/schema/zarf-v1beta1-component-schema.json | 3 --- src/pkg/schema/zarf-v1beta1-package-schema.json | 7 ++----- 3 files changed, 4 insertions(+), 10 deletions(-) diff --git a/src/api/v1beta1/component.go b/src/api/v1beta1/component.go index ad102aa843..aef150835f 100644 --- a/src/api/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -10,8 +10,8 @@ type Component struct { // Message to include during package deploy describing the purpose of this component. Description string `json:"description,omitempty"` // Do not install this component unless explicitly requested. Defaults to false, meaning the component is required. - Optional bool `json:"optional,omitempty"` - ComponentSpec + Optional bool `json:"optional,omitempty"` + ComponentSpec `json:",inline"` // Data injections removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. dataInjections []ZarfDataInjection diff --git a/src/pkg/schema/zarf-v1beta1-component-schema.json b/src/pkg/schema/zarf-v1beta1-component-schema.json index 469d92c2d0..7ce38cb77f 100644 --- a/src/pkg/schema/zarf-v1beta1-component-schema.json +++ b/src/pkg/schema/zarf-v1beta1-component-schema.json @@ -844,9 +844,6 @@ "type": { "description": "Type declares the kind of data being stored in the value.", "type": "string" - }, - "value": { - "description": "Value is the current value at the key." } }, "type": "object" diff --git a/src/pkg/schema/zarf-v1beta1-package-schema.json b/src/pkg/schema/zarf-v1beta1-package-schema.json index 0c3ee4761e..0dd10d28df 100644 --- a/src/pkg/schema/zarf-v1beta1-package-schema.json +++ b/src/pkg/schema/zarf-v1beta1-package-schema.json @@ -78,8 +78,8 @@ }, "required": [ "architecture", - "timestamp", - "version" + "version", + "aggregateChecksum" ], "type": "object" }, @@ -928,9 +928,6 @@ "type": { "description": "Type declares the kind of data being stored in the value.", "type": "string" - }, - "value": { - "description": "Value is the current value at the key." } }, "type": "object" From 0a3446d280dd1cc0a92d907e064b827ab1f783f1 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Tue, 9 Jun 2026 09:44:54 -0400 Subject: [PATCH 25/26] add deprecated static text Signed-off-by: Austin Abro --- src/api/v1beta1/component.go | 10 ++++++++++ src/api/v1beta1/package.go | 6 ++++++ 2 files changed, 16 insertions(+) diff --git a/src/api/v1beta1/component.go b/src/api/v1beta1/component.go index aef150835f..54ec0be925 100644 --- a/src/api/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -20,11 +20,15 @@ type Component struct { } // GetDeprecatedDataInjections returns the v1alpha1 data injections carried as a backwards-compatibility shim. +// +// Deprecated: only used to convert v1alpha1 packages; will be removed once v1alpha1 support is dropped. func (c Component) GetDeprecatedDataInjections() []ZarfDataInjection { return c.dataInjections } // GetDeprecatedGroup returns the v1alpha1 group carried as a backwards-compatibility shim. +// +// Deprecated: only used to convert v1alpha1 packages; will be removed once v1alpha1 support is dropped. func (c Component) GetDeprecatedGroup() string { return c.group } @@ -166,11 +170,15 @@ type Chart struct { } // GetDeprecatedVersion returns the deprecated top-level chart version, used as a v1alpha1 backwards-compatibility shim. +// +// Deprecated: only used to convert v1alpha1 packages; will be removed once v1alpha1 support is dropped. func (c Chart) GetDeprecatedVersion() string { return c.version } // GetDeprecatedVariables returns the v1alpha1 chart variables carried as a backwards-compatibility shim. +// +// Deprecated: only used to convert v1alpha1 packages; will be removed once v1alpha1 support is dropped. func (c Chart) GetDeprecatedVariables() []ZarfChartVariable { return c.variables } @@ -316,6 +324,8 @@ type ComponentAction struct { } // GetDeprecatedSetVariables returns the v1alpha1 setVariables carried as a backwards-compatibility shim. +// +// Deprecated: only used to convert v1alpha1 packages; will be removed once v1alpha1 support is dropped. func (a ComponentAction) GetDeprecatedSetVariables() []Variable { return a.setVariables } diff --git a/src/api/v1beta1/package.go b/src/api/v1beta1/package.go index ca859bbce0..100ab02b84 100644 --- a/src/api/v1beta1/package.go +++ b/src/api/v1beta1/package.go @@ -40,11 +40,15 @@ type Package struct { } // GetDeprecatedVariables returns the v1alpha1 variables carried as a backwards-compatibility shim. +// +// Deprecated: only used to convert v1alpha1 packages; will be removed once v1alpha1 support is dropped. func (pkg Package) GetDeprecatedVariables() []InteractiveVariable { return pkg.variables } // GetDeprecatedConstants returns the v1alpha1 constants carried as a backwards-compatibility shim. +// +// Deprecated: only used to convert v1alpha1 packages; will be removed once v1alpha1 support is dropped. func (pkg Package) GetDeprecatedConstants() []Constant { return pkg.constants } @@ -90,6 +94,8 @@ type PackageMetadata struct { } // GetDeprecatedYOLO returns the v1alpha1 YOLO field carried as a backwards-compatibility shim. +// +// Deprecated: only used to convert v1alpha1 packages; will be removed once v1alpha1 support is dropped. func (m PackageMetadata) GetDeprecatedYOLO() bool { return m.yolo } From 169ae154a8ffeb0227a862afbe92a2552760a9a1 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Tue, 9 Jun 2026 09:52:06 -0400 Subject: [PATCH 26/26] enable templating Signed-off-by: Austin Abro --- src/api/v1beta1/component.go | 12 ++++++------ src/pkg/schema/zarf-v1beta1-component-schema.json | 12 ++++++------ src/pkg/schema/zarf-v1beta1-package-schema.json | 12 ++++++------ 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/src/api/v1beta1/component.go b/src/api/v1beta1/component.go index 54ec0be925..e2a4aff6d3 100644 --- a/src/api/v1beta1/component.go +++ b/src/api/v1beta1/component.go @@ -132,8 +132,8 @@ type Manifest struct { SkipWait bool `json:"skipWait,omitempty"` // Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy. Defaults to "auto" when omitted. ServerSideApply ServerSideApplyMode `json:"serverSideApply,omitempty" jsonschema:"enum=true,enum=false,enum=auto"` - // EnableValues enables go-template processing on these manifests during deploy. - EnableValues bool `json:"enableValues,omitempty"` + // EnableTemplating enables go-template processing on these manifests during deploy. + EnableTemplating bool `json:"enableTemplating,omitempty"` } // Chart defines a helm chart to be deployed. @@ -237,8 +237,8 @@ type File struct { Symlinks []string `json:"symlinks,omitempty"` // Local folder or file to be extracted from a 'source' archive. ExtractPath string `json:"extractPath,omitempty"` - // EnableValues enables go-template processing on this file during deploy. - EnableValues bool `json:"enableValues,omitempty"` + // EnableTemplating enables go-template processing on this file during deploy. + EnableTemplating bool `json:"enableTemplating,omitempty"` } // Image defines an OCI image to include in the package. @@ -317,8 +317,8 @@ type ComponentAction struct { Description string `json:"description,omitempty"` // Wait for a condition to be met before continuing. Wait *ComponentActionWait `json:"wait,omitempty"` - // EnableValues enables go-template processing on the cmd field. - EnableValues bool `json:"enableValues,omitempty"` + // EnableTemplating enables go-template processing on the cmd field. + EnableTemplating bool `json:"enableTemplating,omitempty"` // setVariables removed from the v1beta1 schema; kept as a v1alpha1 backwards-compatibility shim. setVariables []Variable } diff --git a/src/pkg/schema/zarf-v1beta1-component-schema.json b/src/pkg/schema/zarf-v1beta1-component-schema.json index 7ce38cb77f..214dd6c356 100644 --- a/src/pkg/schema/zarf-v1beta1-component-schema.json +++ b/src/pkg/schema/zarf-v1beta1-component-schema.json @@ -113,8 +113,8 @@ "description": "The working directory to run the command in (default is CWD).", "type": "string" }, - "enableValues": { - "description": "EnableValues enables go-template processing on the cmd field.", + "enableTemplating": { + "description": "EnableTemplating enables go-template processing on the cmd field.", "type": "boolean" }, "env": { @@ -589,8 +589,8 @@ "description": "The absolute or relative path where the file or folder should be copied to during package deploy.", "type": "string" }, - "enableValues": { - "description": "EnableValues enables go-template processing on this file during deploy.", + "enableTemplating": { + "description": "EnableTemplating enables go-template processing on this file during deploy.", "type": "boolean" }, "executable": { @@ -765,8 +765,8 @@ "^x-": {} }, "properties": { - "enableValues": { - "description": "EnableValues enables go-template processing on these manifests during deploy.", + "enableTemplating": { + "description": "EnableTemplating enables go-template processing on these manifests during deploy.", "type": "boolean" }, "files": { diff --git a/src/pkg/schema/zarf-v1beta1-package-schema.json b/src/pkg/schema/zarf-v1beta1-package-schema.json index 0dd10d28df..46d89ef53d 100644 --- a/src/pkg/schema/zarf-v1beta1-package-schema.json +++ b/src/pkg/schema/zarf-v1beta1-package-schema.json @@ -287,8 +287,8 @@ "description": "The working directory to run the command in (default is CWD).", "type": "string" }, - "enableValues": { - "description": "EnableValues enables go-template processing on the cmd field.", + "enableTemplating": { + "description": "EnableTemplating enables go-template processing on the cmd field.", "type": "boolean" }, "env": { @@ -624,8 +624,8 @@ "description": "The absolute or relative path where the file or folder should be copied to during package deploy.", "type": "string" }, - "enableValues": { - "description": "EnableValues enables go-template processing on this file during deploy.", + "enableTemplating": { + "description": "EnableTemplating enables go-template processing on this file during deploy.", "type": "boolean" }, "executable": { @@ -800,8 +800,8 @@ "^x-": {} }, "properties": { - "enableValues": { - "description": "EnableValues enables go-template processing on these manifests during deploy.", + "enableTemplating": { + "description": "EnableTemplating enables go-template processing on these manifests during deploy.", "type": "boolean" }, "files": {