From 568a16092cd448e266c075cb2992c77541ffdbcc Mon Sep 17 00:00:00 2001 From: Austin Abro <37223396+AustinAbro321@users.noreply.github.com> Date: Wed, 31 Jul 2024 09:07:38 -0400 Subject: [PATCH] refactor: utilize invopop comment feature (#2781) Signed-off-by: Austin Abro --- src/cmd/internal.go | 26 ++- src/extensions/bigbang/bigbang.go | 10 +- src/pkg/packager/actions/actions.go | 2 +- src/pkg/packager/composer/list.go | 4 +- src/pkg/packager/publish.go | 4 +- src/pkg/variables/types.go | 45 ++-- src/types/component.go | 327 +++++++++++++++++----------- src/types/extensions/bigbang.go | 17 +- src/types/extensions/common.go | 6 +- src/types/k8s.go | 95 +++++--- src/types/package.go | 95 +++++--- src/types/runtime.go | 200 +++++++++-------- zarf.schema.json | 282 +++++++++++++----------- 13 files changed, 666 insertions(+), 447 deletions(-) diff --git a/src/cmd/internal.go b/src/cmd/internal.go index 907125688d..3d77c01190 100644 --- a/src/cmd/internal.go +++ b/src/cmd/internal.go @@ -7,6 +7,7 @@ package cmd import ( "context" "encoding/json" + "errors" "fmt" "os" "path/filepath" @@ -156,12 +157,30 @@ tableOfContents: false }, } +func addGoComments(reflector *jsonschema.Reflector) error { + addCommentErr := errors.New("this command must be called from the root of the Zarf repo") + + typePackagePath := filepath.Join("src", "types") + if err := reflector.AddGoComments("github.com/zarf-dev/zarf", typePackagePath); err != nil { + return fmt.Errorf("%w: %w", addCommentErr, err) + } + varPackagePath := filepath.Join("src", "pkg", "variables") + if err := reflector.AddGoComments("github.com/zarf-dev/zarf", varPackagePath); err != nil { + return fmt.Errorf("%w: %w", addCommentErr, err) + } + return nil +} + var genConfigSchemaCmd = &cobra.Command{ Use: "gen-config-schema", Aliases: []string{"gc"}, Short: lang.CmdInternalConfigSchemaShort, RunE: func(_ *cobra.Command, _ []string) error { reflector := jsonschema.Reflector(jsonschema.Reflector{ExpandedStruct: true}) + if err := addGoComments(&reflector); err != nil { + return err + } + schema := reflector.Reflect(&types.ZarfPackage{}) output, err := json.MarshalIndent(schema, "", " ") if err != nil { @@ -183,7 +202,12 @@ var genTypesSchemaCmd = &cobra.Command{ Aliases: []string{"gt"}, Short: lang.CmdInternalTypesSchemaShort, RunE: func(_ *cobra.Command, _ []string) error { - schema := jsonschema.Reflect(&zarfTypes{}) + reflector := jsonschema.Reflector(jsonschema.Reflector{ExpandedStruct: true}) + if err := addGoComments(&reflector); err != nil { + return err + } + + schema := reflector.Reflect(&zarfTypes{}) output, err := json.MarshalIndent(schema, "", " ") if err != nil { return fmt.Errorf("unable to generate the JSON schema for the Zarf types DeployedPackage, ZarfPackage, and ZarfState: %w", err) diff --git a/src/extensions/bigbang/bigbang.go b/src/extensions/bigbang/bigbang.go index 7eedf66255..951ae88ccf 100644 --- a/src/extensions/bigbang/bigbang.go +++ b/src/extensions/bigbang/bigbang.go @@ -154,10 +154,10 @@ func Run(ctx context.Context, YOLO bool, tmpPaths *layout.ComponentPaths, c type MaxTotalSeconds: &maxTotalSeconds, Wait: &types.ZarfComponentActionWait{ Cluster: &types.ZarfComponentActionWaitCluster{ - Kind: "HelmRelease", - Identifier: hr.Metadata.Name, - Namespace: hr.Metadata.Namespace, - Condition: "ready", + Kind: "HelmRelease", + Name: hr.Metadata.Name, + Namespace: hr.Metadata.Namespace, + Condition: "ready", }, }, } @@ -171,7 +171,7 @@ func Run(ctx context.Context, YOLO bool, tmpPaths *layout.ComponentPaths, c type action.Wait.Cluster = &types.ZarfComponentActionWaitCluster{ Kind: "APIService", // https://github.com/kubernetes-sigs/metrics-server#compatibility-matrix - Identifier: "v1beta1.metrics.k8s.io", + Name: "v1beta1.metrics.k8s.io", } } diff --git a/src/pkg/packager/actions/actions.go b/src/pkg/packager/actions/actions.go index 250e7bf100..ee66b84c39 100644 --- a/src/pkg/packager/actions/actions.go +++ b/src/pkg/packager/actions/actions.go @@ -183,7 +183,7 @@ func convertWaitToCmd(wait types.ZarfComponentActionWait, timeout *int) (string, // Build a call to the zarf tools wait-for command. return fmt.Sprintf("./zarf tools wait-for %s %s %s %s %s", - cluster.Kind, cluster.Identifier, cluster.Condition, ns, timeoutString), nil + cluster.Kind, cluster.Name, cluster.Condition, ns, timeoutString), nil } network := wait.Network diff --git a/src/pkg/packager/composer/list.go b/src/pkg/packager/composer/list.go index 06f67ec816..0edb04d448 100644 --- a/src/pkg/packager/composer/list.go +++ b/src/pkg/packager/composer/list.go @@ -71,8 +71,8 @@ func (n *Node) Prev() *Node { // otherwise the name of the component will be used func (n *Node) ImportName() string { name := n.ZarfComponent.Name - if n.Import.ComponentName != "" { - name = n.Import.ComponentName + if n.Import.Name != "" { + name = n.Import.Name } return name } diff --git a/src/pkg/packager/publish.go b/src/pkg/packager/publish.go index bf664f2739..4cefc1d872 100644 --- a/src/pkg/packager/publish.go +++ b/src/pkg/packager/publish.go @@ -112,8 +112,8 @@ func (p *Packager) Publish(ctx context.Context) (err error) { ex = append(ex, types.ZarfComponent{ Name: fmt.Sprintf("import-%s", c.Name), Import: types.ZarfComponentImport{ - ComponentName: c.Name, - URL: helpers.OCIURLPrefix + remote.Repo().Reference.String(), + Name: c.Name, + URL: helpers.OCIURLPrefix + remote.Repo().Reference.String(), }, }) } diff --git a/src/pkg/variables/types.go b/src/pkg/variables/types.go index b106e911fa..6b3be2863b 100644 --- a/src/pkg/variables/types.go +++ b/src/pkg/variables/types.go @@ -29,35 +29,48 @@ var ( // Variable represents a variable that has a value set programmatically type Variable struct { - Name string `json:"name" jsonschema:"description=The name to be used for the variable,pattern=^[A-Z0-9_]+$"` - Sensitive bool `json:"sensitive,omitempty" jsonschema:"description=Whether to mark this variable as sensitive to not print it in the log"` - AutoIndent bool `json:"autoIndent,omitempty" jsonschema:"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_."` - Pattern string `json:"pattern,omitempty" jsonschema:"description=An optional regex pattern that a variable value must match before a package deployment can continue."` - Type VariableType `json:"type,omitempty" jsonschema:"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,enum=file"` + // 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"` - Description string `json:"description,omitempty" jsonschema:"description=A description of the variable to be used when prompting the user a value"` - Default string `json:"default,omitempty" jsonschema:"description=The default value to use for the variable"` - Prompt bool `json:"prompt,omitempty" jsonschema:"description=Whether to prompt the user for input for this variable"` + 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 { - Name string `json:"name" jsonschema:"description=The name to be used for the constant,pattern=^[A-Z0-9_]+$"` - Value string `json:"value" jsonschema:"description=The value to set for the constant during deploy"` - // Include a description that will only be displayed during package create/deploy confirm prompts - Description string `json:"description,omitempty" jsonschema:"description=A description of the constant to explain its purpose on package create or deploy confirmation prompts"` - AutoIndent bool `json:"autoIndent,omitempty" jsonschema:"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_."` - Pattern string `json:"pattern,omitempty" jsonschema:"description=An optional regex pattern that a constant value must match before a package can be created."` + // 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"` - Value string `json:"value" jsonschema:"description=The value the variable is currently set with"` + // The value the variable is currently set with + Value string `json:"value"` } // Validate runs all validation checks on a package constant. diff --git a/src/types/component.go b/src/types/component.go index 4ccf392970..b43493ad0a 100644 --- a/src/types/component.go +++ b/src/types/component.go @@ -13,61 +13,59 @@ import ( // ZarfComponent is the primary functional grouping of assets to deploy by Zarf. type ZarfComponent struct { - // Name is the unique identifier for this component - Name string `json:"name" jsonschema:"description=The name of the component,pattern=^[a-z0-9][a-z0-9\\-]*$"` + // The name of the component. + Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"` - // Description is a message given to a user when deciding to enable this component or not - Description string `json:"description,omitempty" jsonschema:"description=Message to include during package deploy describing the purpose of this component"` + // Message to include during package deploy describing the purpose of this component. + Description string `json:"description,omitempty"` - // Default changes the default option when deploying this component - Default bool `json:"default,omitempty" jsonschema:"description=Determines the default Y/N state for installing this component on package deploy"` + // Determines the default Y/N state for installing this component on package deploy. + Default bool `json:"default,omitempty"` - // Required makes this component mandatory for package deployment - Required *bool `json:"required,omitempty" jsonschema:"description=Do not prompt user to install this component, always install on package deploy."` + // Do not prompt user to install this component. + Required *bool `json:"required,omitempty"` - // Only include compatible components during package deployment - Only ZarfComponentOnlyTarget `json:"only,omitempty" jsonschema:"description=Filter when this component is included in package creation or deployment"` + // Filter when this component is included in package creation or deployment. + Only ZarfComponentOnlyTarget `json:"only,omitempty"` - // DeprecatedGroup is a key to match other components to produce a user selector field, used to create a BOOLEAN XOR for a set of components - // - // Note: ignores default and required flags - DeprecatedGroup string `json:"group,omitempty" jsonschema:"description=[Deprecated] Create a user selector field based on all components in the same group. This will be removed in Zarf v1.0.0. Consider using 'only.flavor' instead.,deprecated=true"` + // [Deprecated] Create a user selector field based on all components in the same group. This will be removed in Zarf v1.0.0. Consider using 'only.flavor' instead. + DeprecatedGroup string `json:"group,omitempty" jsonschema:"deprecated=true"` - // DeprecatedCosignKeyPath to cosign public key for signed online resources - DeprecatedCosignKeyPath string `json:"cosignKeyPath,omitempty" jsonschema:"description=[Deprecated] Specify a path to a public key to validate signed online resources. This will be removed in Zarf v1.0.0.,deprecated=true"` + // [Deprecated] Specify a path to a public key to validate signed online resources. This will be removed in Zarf v1.0.0. + DeprecatedCosignKeyPath string `json:"cosignKeyPath,omitempty" jsonschema:"deprecated=true"` - // Import refers to another zarf.yaml package component. - Import ZarfComponentImport `json:"import,omitempty" jsonschema:"description=Import a component from another Zarf package"` + // Import a component from another Zarf package. + Import ZarfComponentImport `json:"import,omitempty"` - // Manifests are raw manifests that get converted into zarf-generated helm charts during deploy - Manifests []ZarfManifest `json:"manifests,omitempty" jsonschema:"description=Kubernetes manifests to be included in a generated Helm chart on package deploy"` + // Kubernetes manifests to be included in a generated Helm chart on package deploy. + Manifests []ZarfManifest `json:"manifests,omitempty"` - // Charts are helm charts to install during package deploy - Charts []ZarfChart `json:"charts,omitempty" jsonschema:"description=Helm charts to install during package deploy"` + // Helm charts to install during package deploy. + Charts []ZarfChart `json:"charts,omitempty"` - // Data packages to push into a running cluster - DataInjections []ZarfDataInjection `json:"dataInjections,omitempty" jsonschema:"description=Datasets to inject into a container in the target cluster"` + // Datasets to inject into a container in the target cluster. + DataInjections []ZarfDataInjection `json:"dataInjections,omitempty"` - // Files are files to place on disk during deploy - Files []ZarfFile `json:"files,omitempty" jsonschema:"description=Files or folders to place on disk during package deployment"` + // Files or folders to place on disk during package deployment. + Files []ZarfFile `json:"files,omitempty"` - // Images are the online images needed to be included in the zarf package - Images []string `json:"images,omitempty" jsonschema:"description=List of OCI images to include in the package"` + // List of OCI images to include in the package. + Images []string `json:"images,omitempty"` - // Repos are any git repos that need to be pushed into the git server - Repos []string `json:"repos,omitempty" jsonschema:"description=List of git repos to include in the package"` + // List of git repos to include in the package. + Repos []string `json:"repos,omitempty"` - // Extensions provide additional functionality to a component - Extensions extensions.ZarfComponentExtensions `json:"extensions,omitempty" jsonschema:"description=Extend component functionality with additional features"` + // Extend component functionality with additional features. + Extensions extensions.ZarfComponentExtensions `json:"extensions,omitempty"` - // DeprecatedScripts are custom commands that run before or after package deployment - DeprecatedScripts DeprecatedZarfComponentScripts `json:"scripts,omitempty" jsonschema:"description=[Deprecated] (replaced by actions) Custom commands to run before or after package deployment. This will be removed in Zarf v1.0.0.,deprecated=true"` + // [Deprecated] (replaced by actions) Custom commands to run before or after package deployment. This will be removed in Zarf v1.0.0. + DeprecatedScripts DeprecatedZarfComponentScripts `json:"scripts,omitempty" jsonschema:"deprecated=true"` - // Replaces scripts, fine-grained control over commands to run at various stages of a package lifecycle - Actions ZarfComponentActions `json:"actions,omitempty" jsonschema:"description=Custom commands to run at various stages of a package lifecycle"` + // Custom commands to run at various stages of a package lifecycle. + Actions ZarfComponentActions `json:"actions,omitempty"` } -// RequiresCluster returns if the component requires a cluster connection to deploy +// 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 @@ -93,153 +91,232 @@ func (c ZarfComponent) IsRequired() bool { // ZarfComponentOnlyTarget filters a component to only show it for a given local OS and cluster. type ZarfComponentOnlyTarget struct { - LocalOS string `json:"localOS,omitempty" jsonschema:"description=Only deploy component to specified OS,enum=linux,enum=darwin,enum=windows"` - Cluster ZarfComponentOnlyCluster `json:"cluster,omitempty" jsonschema:"description=Only deploy component to specified clusters"` - Flavor string `json:"flavor,omitempty" jsonschema:"description=Only include this component when a matching '--flavor' is specified on 'zarf package create'"` + // 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"` + // 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 { - Architecture string `json:"architecture,omitempty" jsonschema:"description=Only create and deploy to clusters of the given architecture,enum=amd64,enum=arm64"` - Distros []string `json:"distros,omitempty" jsonschema:"description=A list of kubernetes distros this package works with (Reserved for future use),example=k3s,example=eks"` + // 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"` } // ZarfFile defines a file to deploy. type ZarfFile struct { - Source string `json:"source" jsonschema:"description=Local folder or file path or remote URL to pull into the package"` - Shasum string `json:"shasum,omitempty" jsonschema:"description=(files only) Optional SHA256 checksum of the file"` - Target string `json:"target" jsonschema:"description=The absolute or relative path where the file or folder should be copied to during package deploy"` - Executable bool `json:"executable,omitempty" jsonschema:"description=(files only) Determines if the file should be made executable during package deploy"` - Symlinks []string `json:"symlinks,omitempty" jsonschema:"description=List of symlinks to create during package deploy"` - ExtractPath string `json:"extractPath,omitempty" jsonschema:"description=Local folder or file to be extracted from a 'source' archive"` + // 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"` } // ZarfChart defines a helm chart to be deployed. type ZarfChart struct { - Name string `json:"name" jsonschema:"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"` - Version string `json:"version,omitempty" jsonschema:"description=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')"` - URL string `json:"url,omitempty" jsonschema:"example=OCI registry: oci://ghcr.io/stefanprodan/charts/podinfo,example=helm chart repo: https://stefanprodan.github.io/podinfo,example=git repo: https://github.com/stefanprodan/podinfo (note the '@' syntax for 'repos' is supported here too)" jsonschema_description:"The URL of the OCI registry, chart repository, or git repo where the helm chart is stored"` - RepoName string `json:"repoName,omitempty" jsonschema:"description=The name of a chart within a Helm repository (defaults to the Zarf name of the chart)"` - GitPath string `json:"gitPath,omitempty" jsonschema:"description=(git repo only) The sub directory to the chart within a git repo,example=charts/your-chart"` - LocalPath string `json:"localPath,omitempty" jsonschema:"description=The path to a local chart's folder or .tgz archive"` - Namespace string `json:"namespace,omitempty" jsonschema:"description=The namespace to deploy the chart to"` - ReleaseName string `json:"releaseName,omitempty" jsonschema:"description=The name of the Helm release to create (defaults to the Zarf name of the chart)"` - NoWait bool `json:"noWait,omitempty" jsonschema:"description=Whether to not wait for chart resources to be ready before continuing"` - ValuesFiles []string `json:"valuesFiles,omitempty" jsonschema:"description=List of local values file paths or remote URLs to include in the package; these will be merged together when deployed"` - Variables []ZarfChartVariable `json:"variables,omitempty" jsonschema:"description=[alpha] List of variables to set in the Helm chart"` + // 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 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 URL of the OCI registry, chart repository, or git repo where the helm chart is stored. + URL string `json:"url,omitempty" jsonschema:"example=OCI registry: oci://ghcr.io/stefanprodan/charts/podinfo,example=helm chart repo: https://stefanprodan.github.io/podinfo,example=git repo: https://github.com/stefanprodan/podinfo (note the '@' syntax for 'repos' is supported here too)"` + // The name of a chart within a Helm repository (defaults to the Zarf name of the chart). + RepoName string `json:"repoName,omitempty"` + // (git repo only) The sub directory to the chart within a git repo. + GitPath string `json:"gitPath,omitempty" jsonschema:"example=charts/your-chart"` + // The path to a local chart's folder or .tgz archive. + LocalPath string `json:"localPath,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. + NoWait bool `json:"noWait,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"` } // ZarfChartVariable represents a variable that can be set for a Helm chart overrides. type ZarfChartVariable struct { - Name string `json:"name" jsonschema:"description=The name of the variable,pattern=^[A-Z0-9_]+$"` - Description string `json:"description" jsonschema:"description=A brief description of what the variable controls"` - Path string `json:"path" jsonschema:"description=The path within the Helm chart values where this variable applies"` + // 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"` } // ZarfManifest defines raw manifests Zarf will deploy as a helm chart. type ZarfManifest struct { - Name string `json:"name" jsonschema:"description=A name to give this collection of manifests; this will become the name of the dynamically-created helm chart"` - Namespace string `json:"namespace,omitempty" jsonschema:"description=The namespace to deploy the manifests to"` - Files []string `json:"files,omitempty" jsonschema:"description=List of local K8s YAML files or remote URLs to deploy (in order)"` - KustomizeAllowAnyDirectory bool `json:"kustomizeAllowAnyDirectory,omitempty" jsonschema:"description=Allow traversing directory above the current directory if needed for kustomization"` - Kustomizations []string `json:"kustomizations,omitempty" jsonschema:"description=List of local kustomization paths or remote URLs to include in the package"` - NoWait bool `json:"noWait,omitempty" jsonschema:"description=Whether to not wait for manifest resources to be ready before continuing"` + // 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. + 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. + NoWait bool `json:"noWait,omitempty"` } -// DeprecatedZarfComponentScripts are scripts that run before or after a component is deployed +// DeprecatedZarfComponentScripts are scripts that run before or after a component is deployed. type DeprecatedZarfComponentScripts struct { - ShowOutput bool `json:"showOutput,omitempty" jsonschema:"description=Show the output of the script during package deployment"` - TimeoutSeconds int `json:"timeoutSeconds,omitempty" jsonschema:"description=Timeout in seconds for the script"` - Retry bool `json:"retry,omitempty" jsonschema:"description=Retry the script if it fails"` - Prepare []string `json:"prepare,omitempty" jsonschema:"description=Scripts to run before the component is added during package create"` - Before []string `json:"before,omitempty" jsonschema:"description=Scripts to run before the component is deployed"` - After []string `json:"after,omitempty" jsonschema:"description=Scripts to run after the component successfully deploys"` + // Show the output of the script during package deployment. + ShowOutput bool `json:"showOutput,omitempty"` + // Timeout in seconds for the script. + TimeoutSeconds int `json:"timeoutSeconds,omitempty"` + // Retry the script if it fails. + Retry bool `json:"retry,omitempty"` + // Scripts to run before the component is added during package create. + Prepare []string `json:"prepare,omitempty"` + // Scripts to run before the component is deployed. + Before []string `json:"before,omitempty"` + // Scripts to run after the component successfully deploys. + After []string `json:"after,omitempty"` } -// ZarfComponentActions are ActionSets that map to different zarf package operations +// ZarfComponentActions are ActionSets that map to different zarf package operations. type ZarfComponentActions struct { - OnCreate ZarfComponentActionSet `json:"onCreate,omitempty" jsonschema:"description=Actions to run during package creation"` - OnDeploy ZarfComponentActionSet `json:"onDeploy,omitempty" jsonschema:"description=Actions to run during package deployment"` - OnRemove ZarfComponentActionSet `json:"onRemove,omitempty" jsonschema:"description=Actions to run during package removal"` + // Actions to run during package creation. + OnCreate ZarfComponentActionSet `json:"onCreate,omitempty"` + // Actions to run during package deployment. + OnDeploy ZarfComponentActionSet `json:"onDeploy,omitempty"` + // Actions to run during package removal. + OnRemove ZarfComponentActionSet `json:"onRemove,omitempty"` } -// ZarfComponentActionSet is a set of actions to run during a zarf package operation +// ZarfComponentActionSet is a set of actions to run during a zarf package operation. type ZarfComponentActionSet struct { - Defaults ZarfComponentActionDefaults `json:"defaults,omitempty" jsonschema:"description=Default configuration for all actions in this set"` - Before []ZarfComponentAction `json:"before,omitempty" jsonschema:"description=Actions to run at the start of an operation"` - After []ZarfComponentAction `json:"after,omitempty" jsonschema:"description=Actions to run at the end of an operation"` - OnSuccess []ZarfComponentAction `json:"onSuccess,omitempty" jsonschema:"description=Actions to run if all operations succeed"` - OnFailure []ZarfComponentAction `json:"onFailure,omitempty" jsonschema:"description=Actions to run if all operations fail"` + // Default configuration for all actions in this set. + Defaults ZarfComponentActionDefaults `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 succeed. + OnSuccess []ZarfComponentAction `json:"onSuccess,omitempty"` + // Actions to run if all operations fail. + OnFailure []ZarfComponentAction `json:"onFailure,omitempty"` } -// ZarfComponentActionDefaults sets the default configs for child actions +// ZarfComponentActionDefaults sets the default configs for child actions. type ZarfComponentActionDefaults struct { - Mute bool `json:"mute,omitempty" jsonschema:"description=Hide the output of commands during execution (default false)"` - MaxTotalSeconds int `json:"maxTotalSeconds,omitempty" jsonschema:"description=Default timeout in seconds for commands (default to 0, no timeout)"` - MaxRetries int `json:"maxRetries,omitempty" jsonschema:"description=Retry commands given number of times if they fail (default 0)"` - Dir string `json:"dir,omitempty" jsonschema:"description=Working directory for commands (default CWD)"` - Env []string `json:"env,omitempty" jsonschema:"description=Additional environment variables for commands"` - Shell exec.Shell `json:"shell,omitempty" jsonschema:"description=(cmd only) Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems"` + // Hide the output of commands during execution (default false). + Mute bool `json:"mute,omitempty"` + // Default timeout in seconds for commands (default to 0, no timeout). + MaxTotalSeconds int `json:"maxTotalSeconds,omitempty"` + // Retry commands given number of times if they fail (default 0). + MaxRetries int `json:"maxRetries,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. + Shell exec.Shell `json:"shell,omitempty"` } -// ZarfComponentAction represents a single action to run during a zarf package operation +// ZarfComponentAction represents a single action to run during a zarf package operation. type ZarfComponentAction struct { - Mute *bool `json:"mute,omitempty" jsonschema:"description=Hide the output of the command during package deployment (default false)"` - MaxTotalSeconds *int `json:"maxTotalSeconds,omitempty" jsonschema:"description=Timeout in seconds for the command (default to 0, no timeout for cmd actions and 300, 5 minutes for wait actions)"` - MaxRetries *int `json:"maxRetries,omitempty" jsonschema:"description=Retry the command if it fails up to given number of times (default 0)"` - Dir *string `json:"dir,omitempty" jsonschema:"description=The working directory to run the command in (default is CWD)"` - Env []string `json:"env,omitempty" jsonschema:"description=Additional environment variables to set for the command"` - Cmd string `json:"cmd,omitempty" jsonschema:"description=The command to run. Must specify either cmd or wait for the action to do anything."` - Shell *exec.Shell `json:"shell,omitempty" jsonschema:"description=(cmd only) Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems"` - DeprecatedSetVariable string `json:"setVariable,omitempty" jsonschema:"description=[Deprecated] (replaced by setVariables) (onDeploy/cmd only) The name of a variable to update with the output of the command. This variable will be available to all remaining actions and components in the package. This will be removed in Zarf v1.0.0,pattern=^[A-Z0-9_]+$"` - SetVariables []variables.Variable `json:"setVariables,omitempty" jsonschema:"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."` - Description string `json:"description,omitempty" jsonschema:"description=Description of the action to be displayed during package execution instead of the command"` - Wait *ZarfComponentActionWait `json:"wait,omitempty" jsonschema:"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."` + // 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 300, 5 minutes for wait actions). + MaxTotalSeconds *int `json:"maxTotalSeconds,omitempty"` + // Retry the command if it fails up to given number of times (default 0). + MaxRetries *int `json:"maxRetries,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. + Shell *exec.Shell `json:"shell,omitempty"` + // [Deprecated] (replaced by setVariables) (onDeploy/cmd only) The name of a variable to update with the output of the command. This variable will be available to all remaining actions and components in the package. This will be removed in Zarf v1.0.0. + DeprecatedSetVariable string `json:"setVariable,omitempty" jsonschema:"pattern=^[A-Z0-9_]+$"` + // (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 []variables.Variable `json:"setVariables,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"` } // ZarfComponentActionWait specifies a condition to wait for before continuing type ZarfComponentActionWait struct { - Cluster *ZarfComponentActionWaitCluster `json:"cluster,omitempty" jsonschema:"description=Wait for a condition to be met in the cluster before continuing. Only one of cluster or network can be specified."` - Network *ZarfComponentActionWaitNetwork `json:"network,omitempty" jsonschema:"description=Wait for a condition to be met on the network before continuing. Only one of cluster or network can be specified."` + // 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"` + // 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"` } // ZarfComponentActionWaitCluster specifies a condition to wait for before continuing type ZarfComponentActionWaitCluster struct { - Kind string `json:"kind" jsonschema:"description=The kind of resource to wait for,example=Pod,example=Deployment)"` - Identifier string `json:"name" jsonschema:"description=The name of the resource or selector to wait for,example=podinfo,example=app=podinfo"` - Namespace string `json:"namespace,omitempty" jsonschema:"description=The namespace of the resource to wait for"` - Condition string `json:"condition,omitempty" jsonschema:"description=The condition or jsonpath state to wait for; defaults to exist, a special condition that will wait for the resource to exist,example=Ready,example=Available,'{.status.availableReplicas}'=23"` + // 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. + 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"` } // ZarfComponentActionWaitNetwork specifies a condition to wait for before continuing type ZarfComponentActionWaitNetwork struct { - Protocol string `json:"protocol" jsonschema:"description=The protocol to wait for,enum=tcp,enum=http,enum=https"` - Address string `json:"address" jsonschema:"description=The address to wait for,example=localhost:8080,example=1.1.1.1"` - Code int `json:"code,omitempty" jsonschema:"description=The HTTP status code to wait for if using http or https,example=200,example=404"` + // 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"` } // ZarfContainerTarget defines the destination info for a ZarfData target type ZarfContainerTarget struct { - Namespace string `json:"namespace" jsonschema:"description=The namespace to target for data injection"` - Selector string `json:"selector" jsonschema:"description=The K8s selector to target for data injection,example=app=data-injection"` - Container string `json:"container" jsonschema:"description=The container name to target for data injection"` - Path string `json:"path" jsonschema:"description=The path within the container to copy the data into"` + // 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 { - Source string `json:"source" jsonschema:"description=Either a path to a local folder/file or a remote URL of a file to inject into the given target pod + container"` - Target ZarfContainerTarget `json:"target" jsonschema:"description=The target pod + container to inject the data into"` - Compress bool `json:"compress,omitempty" jsonschema:"description=Compress the data before transmitting using gzip. Note: this requires support for tar/gzip locally and in the target image."` + // 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 { - ComponentName string `json:"name,omitempty" jsonschema:"description=The name of the component to import from the referenced zarf.yaml"` - // For further explanation see https://regex101.com/r/nxX8vx/1 - Path string `json:"path,omitempty" jsonschema:"description=The relative path to a directory containing a zarf.yaml to import from"` - // For further explanation see https://regex101.com/r/nxX8vx/1 - URL string `json:"url,omitempty" jsonschema:"description=[beta] The URL to a Zarf package to import via OCI,pattern=^oci://.*$"` + // 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. + Path string `json:"path,omitempty"` + // [beta] The URL to a Zarf package to import via OCI. + URL string `json:"url,omitempty" jsonschema:"pattern=^oci://.*$"` } // JSONSchemaExtend extends the generated json schema during `zarf internal gen-config-schema` diff --git a/src/types/extensions/bigbang.go b/src/types/extensions/bigbang.go index 8078e0be04..af357d5990 100644 --- a/src/types/extensions/bigbang.go +++ b/src/types/extensions/bigbang.go @@ -4,11 +4,16 @@ // Package extensions contains the types for all official extensions. package extensions -// BigBang defines a file to deploy. +// BigBang holds the configuration for the Big Bang extension. type BigBang struct { - Version string `json:"version" jsonschema:"description=The version of Big Bang to use"` - Repo string `json:"repo,omitempty" jsonschema:"description=Override repo to pull Big Bang from instead of Repo One"` - ValuesFiles []string `json:"valuesFiles,omitempty" jsonschema:"description=The list of values files to pass to Big Bang; these will be merged together"` - SkipFlux bool `json:"skipFlux,omitempty" jsonschema:"description=Whether to skip deploying flux; Defaults to false"` - FluxPatchFiles []string `json:"fluxPatchFiles,omitempty" jsonschema:"description=Optional paths to Flux kustomize strategic merge patch files"` + // The version of Big Bang to use. + Version string `json:"version"` + // Override repo to pull Big Bang from instead of Repo One. + Repo string `json:"repo,omitempty"` + // The list of values files to pass to Big Bang; these will be merged together. + ValuesFiles []string `json:"valuesFiles,omitempty"` + // Whether to skip deploying flux; Defaults to false. + SkipFlux bool `json:"skipFlux,omitempty"` + // Optional paths to Flux kustomize strategic merge patch files. + FluxPatchFiles []string `json:"fluxPatchFiles,omitempty"` } diff --git a/src/types/extensions/common.go b/src/types/extensions/common.go index e84091e339..1df82730ab 100644 --- a/src/types/extensions/common.go +++ b/src/types/extensions/common.go @@ -4,8 +4,8 @@ // Package extensions contains the types for all official extensions. package extensions -// ZarfComponentExtensions is a struct that contains all the official extensions +// ZarfComponentExtensions is a struct that contains all the official extensions. type ZarfComponentExtensions struct { - // Big Bang Configurations - BigBang *BigBang `json:"bigbang,omitempty" jsonschema:"description=Configurations for installing Big Bang and Flux in the cluster"` + // Configurations for installing Big Bang and Flux in the cluster. + BigBang *BigBang `json:"bigbang,omitempty"` } diff --git a/src/types/k8s.go b/src/types/k8s.go index a8f61856ce..6804de17ee 100644 --- a/src/types/k8s.go +++ b/src/types/k8s.go @@ -58,15 +58,23 @@ type GeneratedPKI struct { // ZarfState is maintained as a secret in the Zarf namespace to track Zarf init data. type ZarfState struct { - ZarfAppliance bool `json:"zarfAppliance" jsonschema:"description=Indicates if Zarf was initialized while deploying its own k8s cluster"` - Distro string `json:"distro" jsonschema:"description=K8s distribution of the cluster Zarf was deployed to"` - Architecture string `json:"architecture" jsonschema:"description=Machine architecture of the k8s node(s)"` - StorageClass string `json:"storageClass" jsonschema:"Default StorageClass value Zarf uses for variable templating"` - AgentTLS GeneratedPKI `json:"agentTLS" jsonschema:"PKI certificate information for the agent pods Zarf manages"` - - GitServer GitServerInfo `json:"gitServer" jsonschema:"description=Information about the repository Zarf is configured to use"` - RegistryInfo RegistryInfo `json:"registryInfo" jsonschema:"description=Information about the container registry Zarf is configured to use"` - ArtifactServer ArtifactServerInfo `json:"artifactServer" jsonschema:"description=Information about the artifact registry Zarf is configured to use"` + // Indicates if Zarf was initialized while deploying its own k8s cluster + ZarfAppliance bool `json:"zarfAppliance"` + // K8s distribution of the cluster Zarf was deployed to + Distro string `json:"distro"` + // Machine architecture of the k8s node(s) + Architecture string `json:"architecture"` + // Default StorageClass value Zarf uses for variable templating + StorageClass string `json:"storageClass"` + // PKI certificate information for the agent pods Zarf manages + AgentTLS GeneratedPKI `json:"agentTLS"` + + // Information about the repository Zarf is configured to use + GitServer GitServerInfo `json:"gitServer"` + // Information about the container registry Zarf is configured to use + RegistryInfo RegistryInfo `json:"registryInfo"` + // Information about the artifact registry Zarf is configured to use + ArtifactServer ArtifactServerInfo `json:"artifactServer"` } // DeployedPackage contains information about a Zarf Package that has been deployed to a cluster @@ -81,6 +89,17 @@ type DeployedPackage struct { ConnectStrings ConnectStrings `json:"connectStrings,omitempty"` } +// ConnectString contains information about a connection made with Zarf connect. +type ConnectString struct { + // Descriptive text that explains what the resource you would be connecting to is used for + Description string `json:"description"` + // URL path that gets appended to the k8s port-forward result + URL string `json:"url"` +} + +// ConnectStrings is a map of connect names to connection information. +type ConnectStrings map[string]ConnectString + // DeployedComponent contains information about a Zarf Package Component that has been deployed to a cluster. type DeployedComponent struct { Name string `json:"name"` @@ -105,13 +124,18 @@ type InstalledChart struct { // GitServerInfo contains information Zarf uses to communicate with a git repository to push/pull repositories to. type GitServerInfo struct { - PushUsername string `json:"pushUsername" jsonschema:"description=Username of a user with push access to the git repository"` - PushPassword string `json:"pushPassword" jsonschema:"description=Password of a user with push access to the git repository"` - PullUsername string `json:"pullUsername" jsonschema:"description=Username of a user with pull-only access to the git repository. If not provided for an external repository then the push-user is used"` - PullPassword string `json:"pullPassword" jsonschema:"description=Password of a user with pull-only access to the git repository. If not provided for an external repository then the push-user is used"` - - Address string `json:"address" jsonschema:"description=URL address of the git server"` - InternalServer bool `json:"internalServer" jsonschema:"description=Indicates if we are using a git server that Zarf is directly managing"` + // Username of a user with push access to the git repository + PushUsername string `json:"pushUsername"` + // Password of a user with push access to the git repository + PushPassword string `json:"pushPassword"` + // Username of a user with pull-only access to the git repository. If not provided for an external repository then the push-user is used + PullUsername string `json:"pullUsername"` + // Password of a user with pull-only access to the git repository. If not provided for an external repository then the push-user is used + PullPassword string `json:"pullPassword"` + // URL address of the git server + Address string `json:"address"` + // Indicates if we are using a git server that Zarf is directly managing + InternalServer bool `json:"internalServer"` } // FillInEmptyValues sets every necessary value that's currently empty to a reasonable default @@ -153,11 +177,14 @@ func (gs *GitServerInfo) FillInEmptyValues() error { // ArtifactServerInfo contains information Zarf uses to communicate with a artifact registry to push/pull repositories to. type ArtifactServerInfo struct { - PushUsername string `json:"pushUsername" jsonschema:"description=Username of a user with push access to the artifact registry"` - PushToken string `json:"pushPassword" jsonschema:"description=Password of a user with push access to the artifact registry"` - - Address string `json:"address" jsonschema:"description=URL address of the artifact registry"` - InternalServer bool `json:"internalServer" jsonschema:"description=Indicates if we are using a artifact registry that Zarf is directly managing"` + // Username of a user with push access to the artifact registry + PushUsername string `json:"pushUsername"` + // Password of a user with push access to the artifact registry + PushToken string `json:"pushPassword"` + // URL address of the artifact registry + Address string `json:"address"` + // Indicates if we are using a artifact registry that Zarf is directly managing + InternalServer bool `json:"internalServer"` } // FillInEmptyValues sets every necessary value that's currently empty to a reasonable default @@ -176,16 +203,22 @@ func (as *ArtifactServerInfo) FillInEmptyValues() { // RegistryInfo contains information Zarf uses to communicate with a container registry to push/pull images. type RegistryInfo struct { - PushUsername string `json:"pushUsername" jsonschema:"description=Username of a user with push access to the registry"` - PushPassword string `json:"pushPassword" jsonschema:"description=Password of a user with push access to the registry"` - PullUsername string `json:"pullUsername" jsonschema:"description=Username of a user with pull-only access to the registry. If not provided for an external registry than the push-user is used"` - PullPassword string `json:"pullPassword" jsonschema:"description=Password of a user with pull-only access to the registry. If not provided for an external registry than the push-user is used"` - - Address string `json:"address" jsonschema:"description=URL address of the registry"` - NodePort int `json:"nodePort" jsonschema:"description=Nodeport of the registry. Only needed if the registry is running inside the kubernetes cluster"` - InternalRegistry bool `json:"internalRegistry" jsonschema:"description=Indicates if we are using a registry that Zarf is directly managing"` - - Secret string `json:"secret" jsonschema:"description=Secret value that the registry was seeded with"` + // Username of a user with push access to the registry + PushUsername string `json:"pushUsername"` + // Password of a user with push access to the registry + PushPassword string `json:"pushPassword"` + // Username of a user with pull-only access to the registry. If not provided for an external registry than the push-user is used + PullUsername string `json:"pullUsername"` + // Password of a user with pull-only access to the registry. If not provided for an external registry than the push-user is used + PullPassword string `json:"pullPassword"` + // URL address of the registry + Address string `json:"address"` + // Nodeport of the registry. Only needed if the registry is running inside the kubernetes cluster + NodePort int `json:"nodePort"` + // Indicates if we are using a registry that Zarf is directly managing + InternalRegistry bool `json:"internalRegistry"` + // Secret value that the registry was seeded with + Secret string `json:"secret"` } // FillInEmptyValues sets every necessary value not already set to a reasonable default diff --git a/src/types/package.go b/src/types/package.go index cb097d6e42..bb4b0edc0a 100644 --- a/src/types/package.go +++ b/src/types/package.go @@ -18,12 +18,18 @@ const ( // ZarfPackage the top-level structure of a Zarf config file. type ZarfPackage struct { - Kind ZarfPackageKind `json:"kind" jsonschema:"description=The kind of Zarf package,enum=ZarfInitConfig,enum=ZarfPackageConfig,default=ZarfPackageConfig"` - Metadata ZarfMetadata `json:"metadata,omitempty" jsonschema:"description=Package metadata"` - Build ZarfBuildData `json:"build,omitempty" jsonschema:"description=Zarf-generated package build data"` - Components []ZarfComponent `json:"components" jsonschema:"description=List of components to deploy in this package,minItems=1"` - Constants []variables.Constant `json:"constants,omitempty" jsonschema:"description=Constant template values applied on deploy for K8s resources"` - Variables []variables.InteractiveVariable `json:"variables,omitempty" jsonschema:"description=Variable template values applied on deploy for K8s resources"` + // The kind of Zarf package. + Kind ZarfPackageKind `json:"kind" jsonschema:"enum=ZarfInitConfig,enum=ZarfPackageConfig,default=ZarfPackageConfig"` + // Package metadata. + Metadata ZarfMetadata `json:"metadata,omitempty"` + // 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"` + // Constant template values applied on deploy for K8s resources. + Constants []variables.Constant `json:"constants,omitempty"` + // Variable template values applied on deploy for K8s resources. + Variables []variables.InteractiveVariable `json:"variables,omitempty"` } // IsInitConfig returns whether a Zarf package is an init config. @@ -43,35 +49,58 @@ func (pkg ZarfPackage) IsSBOMAble() bool { // ZarfMetadata lists information about the current ZarfPackage. type ZarfMetadata struct { - // The Name regex permits lowercase letters, numbers, and hyphens not at the start - // https://regex101.com/r/FLdG9G/2 - Name string `json:"name" jsonschema:"description=Name to identify this Zarf package,pattern=^[a-z0-9][a-z0-9\\-]*$"` - Description string `json:"description,omitempty" jsonschema:"description=Additional information about this package"` - Version string `json:"version,omitempty" jsonschema:"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)"` - URL string `json:"url,omitempty" jsonschema:"description=Link to package information when online"` - Image string `json:"image,omitempty" jsonschema:"description=An image URL to embed in this package (Reserved for future use in Zarf UI)"` - Uncompressed bool `json:"uncompressed,omitempty" jsonschema:"description=Disable compression of this package"` - Architecture string `json:"architecture,omitempty" jsonschema:"description=The target cluster architecture for this package,example=arm64,example=amd64"` - YOLO bool `json:"yolo,omitempty" jsonschema:"description=Yaml OnLy Online (YOLO): True enables deploying a Zarf package without first running zarf init against the cluster. This is ideal for connected environments where you want to use existing VCS and container registries."` - Authors string `json:"authors,omitempty" jsonschema:"description=Comma-separated list of package authors (including contact info),example=Doug <hello@defenseunicorns.com>, Pepr <hello@defenseunicorns.com>"` - Documentation string `json:"documentation,omitempty" jsonschema:"description=Link to package documentation when online"` - Source string `json:"source,omitempty" jsonschema:"description=Link to package source code when online"` - Vendor string `json:"vendor,omitempty" jsonschema_description:"Name of the distributing entity, organization or individual."` - AggregateChecksum string `json:"aggregateChecksum,omitempty" jsonschema:"description=Checksum of a checksums.txt file that contains checksums all the layers within the package."` + // Name to identify this Zarf package. + Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"` + // Additional information about this 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"` + // Link to package information when online. + URL string `json:"url,omitempty"` + // An image URL to embed in this package (Reserved for future use in Zarf UI). + Image string `json:"image,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"` + // Yaml OnLy Online (YOLO): True enables deploying a Zarf package without first running zarf init against the cluster. This is ideal for connected environments where you want to use existing VCS and container registries. + YOLO bool `json:"yolo,omitempty"` + // Comma-separated list of package authors (including contact info). + Authors string `json:"authors,omitempty" jsonschema:"example=Doug <hello@defenseunicorns.com>, Pepr <hello@defenseunicorns.com>"` + // Link to package documentation when online. + Documentation string `json:"documentation,omitempty"` + // Link to package source code when online. + Source string `json:"source,omitempty"` + // Name of the distributing entity, organization or individual. + Vendor string `json:"vendor,omitempty"` + // Checksum of a checksums.txt file that contains checksums all the layers within the package. + AggregateChecksum string `json:"aggregateChecksum,omitempty"` } // ZarfBuildData is written during the packager.Create() operation to track details of the created package. type ZarfBuildData struct { - Terminal string `json:"terminal" jsonschema:"description=The machine name that created this package"` - User string `json:"user" jsonschema:"description=The username who created this package"` - Architecture string `json:"architecture" jsonschema:"description=The architecture this package was created on"` - Timestamp string `json:"timestamp" jsonschema:"description=The timestamp when this package was created"` - Version string `json:"version" jsonschema:"description=The version of Zarf used to build this package"` - Migrations []string `json:"migrations,omitempty" jsonschema:"description=Any migrations that have been run on this package"` - RegistryOverrides map[string]string `json:"registryOverrides,omitempty" jsonschema:"description=Any registry domains that were overridden on package create when pulling images"` - Differential bool `json:"differential,omitempty" jsonschema:"description=Whether this package was created with differential components"` - DifferentialPackageVersion string `json:"differentialPackageVersion,omitempty" jsonschema:"description=Version of a previously built package used as the basis for creating this differential package"` - DifferentialMissing []string `json:"differentialMissing,omitempty" jsonschema:"description=List of components that were not included in this package due to differential packaging"` - LastNonBreakingVersion string `json:"lastNonBreakingVersion,omitempty" jsonschema:"description=The minimum version of Zarf that does not have breaking package structure changes"` - Flavor string `json:"flavor,omitempty" jsonschema:"description=The flavor of Zarf used to build this package"` + // The machine name that created this package. + Terminal string `json:"terminal"` + // The username who created this package. + User string `json:"user"` + // 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. + Migrations []string `json:"migrations,omitempty"` + // Any registry domains that were overridden on package create when pulling images. + 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"` } diff --git a/src/types/runtime.go b/src/types/runtime.go index b4a7d44ad2..0298d80346 100644 --- a/src/types/runtime.go +++ b/src/types/runtime.go @@ -18,22 +18,34 @@ const ( // ZarfCommonOptions tracks the user-defined preferences used across commands. type ZarfCommonOptions struct { - Confirm bool `json:"confirm" jsonschema:"description=Verify that Zarf should perform an action"` - Insecure bool `json:"insecure" jsonschema:"description=Allow insecure connections for remote packages"` - CachePath string `json:"cachePath" jsonschema:"description=Path to use to cache images and git repos on package create"` - TempDirectory string `json:"tempDirectory" jsonschema:"description=Location Zarf should use as a staging ground when managing files and images for package creation and deployment"` - OCIConcurrency int `jsonschema:"description=Number of concurrent layer operations to perform when interacting with a remote package"` + // Verify that Zarf should perform an action + Confirm bool + // Allow insecure connections for remote packages + Insecure bool + // Path to use to cache images and git repos on package create + CachePath string + // Location Zarf should use as a staging ground when managing files and images for package creation and deployment + TempDirectory string + // Number of concurrent layer operations to perform when interacting with a remote package + OCIConcurrency int } // ZarfPackageOptions tracks the user-defined preferences during common package operations. type ZarfPackageOptions struct { - Shasum string `json:"shasum" jsonschema:"description=The SHA256 checksum of the package"` - PackageSource string `json:"packageSource" jsonschema:"description=Location where a Zarf package can be found"` - OptionalComponents string `json:"optionalComponents" jsonschema:"description=Comma separated list of optional components"` - SGetKeyPath string `json:"sGetKeyPath" jsonschema:"description=Location where the public key component of a cosign key-pair can be found"` - SetVariables map[string]string `json:"setVariables" jsonschema:"description=Key-Value map of variable names and their corresponding values that will be used to template manifests and files in the Zarf package"` - PublicKeyPath string `json:"publicKeyPath" jsonschema:"description=Location where the public key component of a cosign key-pair can be found"` - Retries int `json:"retries" jsonschema:"description=The number of retries to perform for Zarf deploy operations like image pushes or Helm installs"` + // The SHA256 checksum of the package + Shasum string + // Location where a Zarf package can be found + PackageSource string + // Comma separated list of optional components + OptionalComponents string + // Location where the public key component of a cosign key-pair can be found + SGetKeyPath string + // Key-Value map of variable names and their corresponding values that will be used to template manifests and files in the Zarf package + SetVariables map[string]string + // Location where the public key component of a cosign key-pair can be found + PublicKeyPath string + // The number of retries to perform for Zarf deploy operations like image pushes or Helm installs + Retries int } // ZarfInspectOptions tracks the user-defined preferences during a package inspection. @@ -48,125 +60,125 @@ type ZarfInspectOptions struct { // ZarfFindImagesOptions tracks the user-defined preferences during a prepare find-images search. type ZarfFindImagesOptions struct { - RepoHelmChartPath string `json:"repoHelmChartPath" jsonschema:"description=Path to the helm chart directory"` - KubeVersionOverride string `json:"kubeVersionOverride" jsonschema:"description=Kubernetes version to use for the helm chart"` - RegistryURL string `json:"registryURL" jsonschema:"description=Manual override for ###ZARF_REGISTRY###"` - Why string `json:"why" jsonschema:"description=Find the location of the image given as an argument and print it to the console"` - SkipCosign bool `json:"skip-cosign" jsonschema:"description=Optionally skip lookup of cosign artifacts when finding images"` + // Path to the helm chart directory + RepoHelmChartPath string + // Kubernetes version to use for the helm chart + KubeVersionOverride string + // Manual override for ###ZARF_REGISTRY### + RegistryURL string + // Find the location of the image given as an argument and print it to the console + Why string + // Optionally skip lookup of cosign artifacts when finding images + SkipCosign bool } // ZarfDeployOptions tracks the user-defined preferences during a package deploy. type ZarfDeployOptions struct { - AdoptExistingResources bool `json:"adoptExistingResources" jsonschema:"description=Whether to adopt any pre-existing K8s resources into the Helm charts managed by Zarf"` - SkipWebhooks bool `json:"componentWebhooks" jsonschema:"description=Skip waiting for external webhooks to execute as each package component is deployed"` - Timeout time.Duration `json:"timeout" jsonschema:"description=Timeout for performing Helm operations"` - - // TODO (@WSTARR): This is a library only addition to Zarf and should be refactored in the future (potentially to utilize component composability). As is it should NOT be exposed directly on the CLI - ValuesOverridesMap map[string]map[string]map[string]interface{} `json:"valuesOverridesMap" jsonschema:"description=[Library Only] A map of component names to chart names containing Helm Chart values to override values on deploy"` + // Whether to adopt any pre-existing K8s resources into the Helm charts managed by Zarf + AdoptExistingResources bool + // Skip waiting for external webhooks to execute as each package component is deployed + SkipWebhooks bool + // Timeout for performing Helm operations + Timeout time.Duration + // [Library Only] A map of component names to chart names containing Helm Chart values to override values on deploy + ValuesOverridesMap map[string]map[string]map[string]interface{} } // ZarfMirrorOptions tracks the user-defined preferences during a package mirror. type ZarfMirrorOptions struct { - NoImgChecksum bool `json:"noImgChecksum" jsonschema:"description=Whether to skip adding a Zarf checksum to image references."` + // Whether to skip adding a Zarf checksum to image references + NoImgChecksum bool } // ZarfPublishOptions tracks the user-defined preferences during a package publish. type ZarfPublishOptions struct { - PackageDestination string `json:"packageDestination" jsonschema:"description=Location where the Zarf package will be published to"` - SigningKeyPassword string `json:"signingKeyPassword" jsonschema:"description=Password to the private key signature file that will be used to sign the published package"` - SigningKeyPath string `json:"signingKeyPath" jsonschema:"description=Location where the private key component of a cosign key-pair can be found"` + // Location where the Zarf package will be published to + PackageDestination string + // Password to the private key signature file that will be used to sign the published package + SigningKeyPassword string + // Location where the private key component of a cosign key-pair can be found + SigningKeyPath string } // ZarfPullOptions tracks the user-defined preferences during a package pull. type ZarfPullOptions struct { - OutputDirectory string `json:"outputDirectory" jsonschema:"description=Location where the pulled Zarf package will be placed"` + // Location where the pulled Zarf package will be placed + OutputDirectory string } // ZarfGenerateOptions tracks the user-defined options during package generation. type ZarfGenerateOptions struct { - Name string `json:"name" jsonschema:"description=Name of the package being generated"` - URL string `json:"url" jsonschema:"description=URL to the source git repository"` - Version string `json:"version" jsonschema:"description=Version of the chart to use"` - GitPath string `json:"gitPath" jsonschema:"description=Relative path to the chart in the git repository"` - Output string `json:"output" jsonschema:"description=Location where the finalized zarf.yaml will be placed"` + // Name of the package being generated + Name string + // URL to the source git repository + URL string + // Version of the chart to use + Version string + // Relative path to the chart in the git repository + GitPath string + // Location where the finalized zarf.yaml will be placed + Output string } // ZarfInitOptions tracks the user-defined options during cluster initialization. type ZarfInitOptions struct { - // Zarf init is installing the k3s component - ApplianceMode bool `json:"applianceMode" jsonschema:"description=Indicates if Zarf was initialized while deploying its own k8s cluster"` - - // Using alternative services - GitServer GitServerInfo `json:"gitServer" jsonschema:"description=Information about the repository Zarf is going to be using"` - RegistryInfo RegistryInfo `json:"registryInfo" jsonschema:"description=Information about the container registry Zarf is going to be using"` - ArtifactServer ArtifactServerInfo `json:"artifactServer" jsonschema:"description=Information about the artifact registry Zarf is going to be using"` - - StorageClass string `json:"storageClass" jsonschema:"description=StorageClass of the k8s cluster Zarf is initializing"` + // Indicates if Zarf was initialized while deploying its own k8s cluster + ApplianceMode bool + // Information about the repository Zarf is going to be using + GitServer GitServerInfo + // Information about the container registry Zarf is going to be using + RegistryInfo RegistryInfo + // Information about the artifact registry Zarf is going to be using + ArtifactServer ArtifactServerInfo + // StorageClass of the k8s cluster Zarf is initializing + StorageClass string } // ZarfCreateOptions tracks the user-defined options used to create the package. type ZarfCreateOptions struct { - SkipSBOM bool `json:"skipSBOM" jsonschema:"description=Disable the generation of SBOM materials during package creation"` - BaseDir string `json:"baseDir" jsonschema:"description=Location where the Zarf package will be created from"` - Output string `json:"output" jsonschema:"description=Location where the finalized Zarf package will be placed"` - ViewSBOM bool `json:"sbom" jsonschema:"description=Whether to pause to allow for viewing the SBOM post-creation"` - SBOMOutputDir string `json:"sbomOutput" jsonschema:"description=Location to output an SBOM into after package creation"` - SetVariables map[string]string `json:"setVariables" jsonschema:"description=Key-Value map of variable names and their corresponding values that will be used to template against the Zarf package being used"` - MaxPackageSizeMB int `json:"maxPackageSizeMB" jsonschema:"description=Size of chunks to use when splitting a zarf package into multiple files in megabytes"` - SigningKeyPath string `json:"signingKeyPath" jsonschema:"description=Location where the private key component of a cosign key-pair can be found"` - SigningKeyPassword string `json:"signingKeyPassword" jsonschema:"description=Password to the private key signature file that will be used to sigh the created package"` - DifferentialPackagePath string `json:"differentialPackagePath" jsonschema:"description=Path to a previously built package used as the basis for creating a differential package"` - RegistryOverrides map[string]string `json:"registryOverrides" jsonschema:"description=A map of domains to override on package create when pulling images"` - Flavor string `json:"flavor" jsonschema:"description=An optional variant that controls which components will be included in a package"` - IsSkeleton bool `json:"isSkeleton" jsonschema:"description=Whether to create a skeleton package"` - NoYOLO bool `json:"noYOLO" jsonschema:"description=Whether to create a YOLO package"` + // Disable the generation of SBOM materials during package creation + SkipSBOM bool + // Location where the Zarf package will be created from + BaseDir string + // Location where the finalized Zarf package will be placed + Output string + // Whether to pause to allow for viewing the SBOM post-creation + ViewSBOM bool + // Location to output an SBOM into after package creation + SBOMOutputDir string + // Key-Value map of variable names and their corresponding values that will be used to template against the Zarf package being used + SetVariables map[string]string + // Size of chunks to use when splitting a zarf package into multiple files in megabytes + MaxPackageSizeMB int + // Location where the private key component of a cosign key-pair can be found + SigningKeyPath string + // Password to the private key signature file that will be used to sigh the created package + SigningKeyPassword string + // Path to a previously built package used as the basis for creating a differential package + DifferentialPackagePath string + // A map of domains to override on package create when pulling images + RegistryOverrides map[string]string + // An optional variant that controls which components will be included in a package + Flavor string + // Whether to create a skeleton package + IsSkeleton bool + // Whether to create a YOLO package + NoYOLO bool } // ZarfSplitPackageData contains info about a split package. type ZarfSplitPackageData struct { - Sha256Sum string `json:"sha256Sum" jsonschema:"description=The sha256sum of the package"` - Bytes int64 `json:"bytes" jsonschema:"description=The size of the package in bytes"` - Count int `json:"count" jsonschema:"description=The number of parts the package is split into"` -} - -// ConnectString contains information about a connection made with Zarf connect. -type ConnectString struct { - Description string `json:"description" jsonschema:"description=Descriptive text that explains what the resource you would be connecting to is used for"` - URL string `json:"url" jsonschema:"description=URL path that gets appended to the k8s port-forward result"` + // The sha256sum of the package + Sha256Sum string + // The size of the package in bytes + Bytes int64 + // The number of parts the package is split into + Count int } -// ConnectStrings is a map of connect names to connection information. -type ConnectStrings map[string]ConnectString - // DifferentialData contains image and repository information about the package a Differential Package is Based on. type DifferentialData struct { DifferentialImages map[string]bool DifferentialRepos map[string]bool DifferentialPackageVersion string } - -// PackageFinding is a struct that contains a finding about something wrong with a package -type PackageFinding struct { - // YqPath is the path to the key where the error originated from, this is sometimes empty in the case of a general error - YqPath string - Description string - // Item is the value of a key that is causing an error, for example a bad image name - Item string - // PackageNameOverride shows the name of the package that the error originated from - // If it is not set the base package will be used when displaying the error - PackageNameOverride string - // PackagePathOverride shows the path to the package that the error originated from - // If it is not set the base package will be used when displaying the error - PackagePathOverride string - Severity Severity -} - -// Severity is the type of package error -// Either Err or Warning -type Severity int - -// different severities of package errors -const ( - SevErr Severity = iota + 1 - SevWarn -) diff --git a/zarf.schema.json b/zarf.schema.json index b5c7a971d4..f4a0690553 100644 --- a/zarf.schema.json +++ b/zarf.schema.json @@ -6,29 +6,29 @@ "properties": { "version": { "type": "string", - "description": "The version of Big Bang to use" + "description": "The version of Big Bang to use." }, "repo": { "type": "string", - "description": "Override repo to pull Big Bang from instead of Repo One" + "description": "Override repo to pull Big Bang from instead of Repo One." }, "valuesFiles": { "items": { "type": "string" }, "type": "array", - "description": "The list of values files to pass to Big Bang; these will be merged together" + "description": "The list of values files to pass to Big Bang; these will be merged together." }, "skipFlux": { "type": "boolean", - "description": "Whether to skip deploying flux; Defaults to false" + "description": "Whether to skip deploying flux; Defaults to false." }, "fluxPatchFiles": { "items": { "type": "string" }, "type": "array", - "description": "Optional paths to Flux kustomize strategic merge patch files" + "description": "Optional paths to Flux kustomize strategic merge patch files." } }, "additionalProperties": false, @@ -36,6 +36,7 @@ "required": [ "version" ], + "description": "BigBang holds the configuration for the Big Bang extension.", "patternProperties": { "^x-": {} } @@ -70,6 +71,7 @@ "name", "value" ], + "description": "Constant are constants that can be used to dynamically template K8s resources or run in actions.", "patternProperties": { "^x-": {} } @@ -78,40 +80,41 @@ "properties": { "showOutput": { "type": "boolean", - "description": "Show the output of the script during package deployment" + "description": "Show the output of the script during package deployment." }, "timeoutSeconds": { "type": "integer", - "description": "Timeout in seconds for the script" + "description": "Timeout in seconds for the script." }, "retry": { "type": "boolean", - "description": "Retry the script if it fails" + "description": "Retry the script if it fails." }, "prepare": { "items": { "type": "string" }, "type": "array", - "description": "Scripts to run before the component is added during package create" + "description": "Scripts to run before the component is added during package create." }, "before": { "items": { "type": "string" }, "type": "array", - "description": "Scripts to run before the component is deployed" + "description": "Scripts to run before the component is deployed." }, "after": { "items": { "type": "string" }, "type": "array", - "description": "Scripts to run after the component successfully deploys" + "description": "Scripts to run after the component successfully deploys." } }, "additionalProperties": false, "type": "object", + "description": "DeprecatedZarfComponentScripts are scripts that run before or after a component is deployed.", "patternProperties": { "^x-": {} } @@ -161,6 +164,7 @@ "required": [ "name" ], + "description": "InteractiveVariable is a variable that can be used to prompt a user for more information", "patternProperties": { "^x-": {} } @@ -241,6 +245,7 @@ "required": [ "name" ], + "description": "Variable represents a variable that has a value set programmatically", "patternProperties": { "^x-": {} } @@ -249,60 +254,60 @@ "properties": { "terminal": { "type": "string", - "description": "The machine name that created this package" + "description": "The machine name that created this package." }, "user": { "type": "string", - "description": "The username who created this package" + "description": "The username who created this package." }, "architecture": { "type": "string", - "description": "The architecture this package was created on" + "description": "The architecture this package was created on." }, "timestamp": { "type": "string", - "description": "The timestamp when this package was created" + "description": "The timestamp when this package was created." }, "version": { "type": "string", - "description": "The version of Zarf used to build this package" + "description": "The version of Zarf used to build this package." }, "migrations": { "items": { "type": "string" }, "type": "array", - "description": "Any migrations that have been run on this package" + "description": "Any migrations that have been run on this package." }, "registryOverrides": { "additionalProperties": { "type": "string" }, "type": "object", - "description": "Any registry domains that were overridden on package create when pulling images" + "description": "Any registry domains that were overridden on package create when pulling images." }, "differential": { "type": "boolean", - "description": "Whether this package was created with differential components" + "description": "Whether this package was created with differential components." }, "differentialPackageVersion": { "type": "string", - "description": "Version of a previously built package used as the basis for creating this differential package" + "description": "Version of a previously built package used as the basis for creating this differential package." }, "differentialMissing": { "items": { "type": "string" }, "type": "array", - "description": "List of components that were not included in this package due to differential packaging" + "description": "List of components that were not included in this package due to differential packaging." }, "lastNonBreakingVersion": { "type": "string", - "description": "The minimum version of Zarf that does not have breaking package structure changes" + "description": "The minimum version of Zarf that does not have breaking package structure changes." }, "flavor": { "type": "string", - "description": "The flavor of Zarf used to build this package" + "description": "The flavor of Zarf used to build this package." } }, "additionalProperties": false, @@ -314,6 +319,7 @@ "timestamp", "version" ], + "description": "ZarfBuildData is written during the packager.Create() operation to track details of the created package.", "patternProperties": { "^x-": {} } @@ -322,15 +328,15 @@ "properties": { "name": { "type": "string", - "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 repo." }, "version": { "type": "string", - "description": "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')" + "description": "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')." }, "url": { "type": "string", - "description": "The URL of the OCI registry, chart repository, or git repo where the helm chart is stored", + "description": "The URL of the OCI registry, chart repository, or git repo where the helm chart is stored.", "examples": [ "OCI registry: oci://ghcr.io/stefanprodan/charts/podinfo", "helm chart repo: https://stefanprodan.github.io/podinfo", @@ -339,44 +345,44 @@ }, "repoName": { "type": "string", - "description": "The name of a chart within a Helm repository (defaults to the Zarf name of the chart)" + "description": "The name of a chart within a Helm repository (defaults to the Zarf name of the chart)." }, "gitPath": { "type": "string", - "description": "(git repo only) The sub directory to the chart within a git repo", + "description": "(git repo only) The sub directory to the chart within a git repo.", "examples": [ "charts/your-chart" ] }, "localPath": { "type": "string", - "description": "The path to a local chart's folder or .tgz archive" + "description": "The path to a local chart's folder or .tgz archive." }, "namespace": { "type": "string", - "description": "The namespace to deploy the chart to" + "description": "The namespace to deploy the chart to." }, "releaseName": { "type": "string", - "description": "The name of the Helm release to create (defaults to the Zarf name of the chart)" + "description": "The name of the Helm release to create (defaults to the Zarf name of the chart)." }, "noWait": { "type": "boolean", - "description": "Whether to not wait for chart resources to be ready before continuing" + "description": "Whether to not wait for chart resources to be ready before continuing." }, "valuesFiles": { "items": { "type": "string" }, "type": "array", - "description": "List of local values file paths or remote URLs to include in the package; these will be merged together when deployed" + "description": "List of local values file paths or remote URLs to include in the package; these will be merged together when deployed." }, "variables": { "items": { "$ref": "#/$defs/ZarfChartVariable" }, "type": "array", - "description": "[alpha] List of variables to set in the Helm chart" + "description": "[alpha] List of variables to set in the Helm chart." } }, "additionalProperties": false, @@ -384,6 +390,7 @@ "required": [ "name" ], + "description": "ZarfChart defines a helm chart to be deployed.", "patternProperties": { "^x-": {} } @@ -393,15 +400,15 @@ "name": { "type": "string", "pattern": "^[A-Z0-9_]+$", - "description": "The name of the variable" + "description": "The name of the variable." }, "description": { "type": "string", - "description": "A brief description of what the variable controls" + "description": "A brief description of what the variable controls." }, "path": { "type": "string", - "description": "The path within the Helm chart values where this variable applies" + "description": "The path within the Helm chart values where this variable applies." } }, "additionalProperties": false, @@ -411,6 +418,7 @@ "description", "path" ], + "description": "ZarfChartVariable represents a variable that can be set for a Helm chart overrides.", "patternProperties": { "^x-": {} } @@ -420,23 +428,23 @@ "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9\\-]*$", - "description": "The name of the component" + "description": "The name of the component." }, "description": { "type": "string", - "description": "Message to include during package deploy describing the purpose of this component" + "description": "Message to include during package deploy describing the purpose of this component." }, "default": { "type": "boolean", - "description": "Determines the default Y/N state for installing this component on package deploy" + "description": "Determines the default Y/N state for installing this component on package deploy." }, "required": { "type": "boolean", - "description": "Do not prompt user to install this component" + "description": "Do not prompt user to install this component." }, "only": { "$ref": "#/$defs/ZarfComponentOnlyTarget", - "description": "Filter when this component is included in package creation or deployment" + "description": "Filter when this component is included in package creation or deployment." }, "group": { "type": "string", @@ -448,61 +456,61 @@ }, "import": { "$ref": "#/$defs/ZarfComponentImport", - "description": "Import a component from another Zarf package" + "description": "Import a component from another Zarf package." }, "manifests": { "items": { "$ref": "#/$defs/ZarfManifest" }, "type": "array", - "description": "Kubernetes manifests to be included in a generated Helm chart on package deploy" + "description": "Kubernetes manifests to be included in a generated Helm chart on package deploy." }, "charts": { "items": { "$ref": "#/$defs/ZarfChart" }, "type": "array", - "description": "Helm charts to install during package deploy" + "description": "Helm charts to install during package deploy." }, "dataInjections": { "items": { "$ref": "#/$defs/ZarfDataInjection" }, "type": "array", - "description": "Datasets to inject into a container in the target cluster" + "description": "Datasets to inject into a container in the target cluster." }, "files": { "items": { "$ref": "#/$defs/ZarfFile" }, "type": "array", - "description": "Files or folders to place on disk during package deployment" + "description": "Files or folders to place on disk during package deployment." }, "images": { "items": { "type": "string" }, "type": "array", - "description": "List of OCI images to include in the package" + "description": "List of OCI images to include in the package." }, "repos": { "items": { "type": "string" }, "type": "array", - "description": "List of git repos to include in the package" + "description": "List of git repos to include in the package." }, "extensions": { "$ref": "#/$defs/ZarfComponentExtensions", - "description": "Extend component functionality with additional features" + "description": "Extend component functionality with additional features." }, "scripts": { "$ref": "#/$defs/DeprecatedZarfComponentScripts", - "description": "[Deprecated] (replaced by actions) Custom commands to run before or after package deployment. This will be removed in Zarf v1.0.0." + "description": "[Deprecated] (replaced by actions) Custom commands to run before or after package deployment. This will be removed in Zarf v1.0.0." }, "actions": { "$ref": "#/$defs/ZarfComponentActions", - "description": "Custom commands to run at various stages of a package lifecycle" + "description": "Custom commands to run at various stages of a package lifecycle." } }, "additionalProperties": false, @@ -510,6 +518,7 @@ "required": [ "name" ], + "description": "ZarfComponent is the primary functional grouping of assets to deploy by Zarf.", "patternProperties": { "^x-": {} } @@ -518,26 +527,26 @@ "properties": { "mute": { "type": "boolean", - "description": "Hide the output of the command during package deployment (default false)" + "description": "Hide the output of the command during package deployment (default false)." }, "maxTotalSeconds": { "type": "integer", - "description": "Timeout in seconds for the command (default to 0" + "description": "Timeout in seconds for the command (default to 0, no timeout for cmd actions and 300, 5 minutes for wait actions)." }, "maxRetries": { "type": "integer", - "description": "Retry the command if it fails up to given number of times (default 0)" + "description": "Retry the command if it fails up to given number of times (default 0)." }, "dir": { "type": "string", - "description": "The working directory to run the command in (default is CWD)" + "description": "The working directory to run the command in (default is CWD)." }, "env": { "items": { "type": "string" }, "type": "array", - "description": "Additional environment variables to set for the command" + "description": "Additional environment variables to set for the command." }, "cmd": { "type": "string", @@ -545,12 +554,12 @@ }, "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": "(cmd only) Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems." }, "setVariable": { "type": "string", "pattern": "^[A-Z0-9_]+$", - "description": "[Deprecated] (replaced by setVariables) (onDeploy/cmd only) The name of a variable to update with the output of the command. This variable will be available to all remaining actions and components in the package. This will be removed in Zarf v1.0.0" + "description": "[Deprecated] (replaced by setVariables) (onDeploy/cmd only) The name of a variable to update with the output of the command. This variable will be available to all remaining actions and components in the package. This will be removed in Zarf v1.0.0." }, "setVariables": { "items": { @@ -561,7 +570,7 @@ }, "description": { "type": "string", - "description": "Description of the action to be displayed during package execution instead of the command" + "description": "Description of the action to be displayed during package execution instead of the command." }, "wait": { "$ref": "#/$defs/ZarfComponentActionWait", @@ -570,6 +579,7 @@ }, "additionalProperties": false, "type": "object", + "description": "ZarfComponentAction represents a single action to run during a zarf package operation.", "patternProperties": { "^x-": {} } @@ -578,34 +588,35 @@ "properties": { "mute": { "type": "boolean", - "description": "Hide the output of commands during execution (default false)" + "description": "Hide the output of commands during execution (default false)." }, "maxTotalSeconds": { "type": "integer", - "description": "Default timeout in seconds for commands (default to 0" + "description": "Default timeout in seconds for commands (default to 0, no timeout)." }, "maxRetries": { "type": "integer", - "description": "Retry commands given number of times if they fail (default 0)" + "description": "Retry commands given number of times if they fail (default 0)." }, "dir": { "type": "string", - "description": "Working directory for commands (default CWD)" + "description": "Working directory for commands (default CWD)." }, "env": { "items": { "type": "string" }, "type": "array", - "description": "Additional environment variables for commands" + "description": "Additional environment variables for commands." }, "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": "(cmd only) Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems." } }, "additionalProperties": false, "type": "object", + "description": "ZarfComponentActionDefaults sets the default configs for child actions.", "patternProperties": { "^x-": {} } @@ -614,39 +625,40 @@ "properties": { "defaults": { "$ref": "#/$defs/ZarfComponentActionDefaults", - "description": "Default configuration for all actions in this set" + "description": "Default configuration for all actions in this set." }, "before": { "items": { "$ref": "#/$defs/ZarfComponentAction" }, "type": "array", - "description": "Actions to run at the start of an operation" + "description": "Actions to run at the start of an operation." }, "after": { "items": { "$ref": "#/$defs/ZarfComponentAction" }, "type": "array", - "description": "Actions to run at the end of an operation" + "description": "Actions to run at the end of an operation." }, "onSuccess": { "items": { "$ref": "#/$defs/ZarfComponentAction" }, "type": "array", - "description": "Actions to run if all operations succeed" + "description": "Actions to run if all operations succeed." }, "onFailure": { "items": { "$ref": "#/$defs/ZarfComponentAction" }, "type": "array", - "description": "Actions to run if all operations fail" + "description": "Actions to run if all operations fail." } }, "additionalProperties": false, "type": "object", + "description": "ZarfComponentActionSet is a set of actions to run during a zarf package operation.", "patternProperties": { "^x-": {} } @@ -664,6 +676,7 @@ }, "additionalProperties": false, "type": "object", + "description": "ZarfComponentActionWait specifies a condition to wait for before continuing", "patternProperties": { "^x-": {} } @@ -672,27 +685,27 @@ "properties": { "kind": { "type": "string", - "description": "The kind of resource to wait for", + "description": "The kind of resource to wait for.", "examples": [ "Pod", - "Deployment)" + "Deployment" ] }, "name": { "type": "string", - "description": "The name of the resource or selector to wait for", + "description": "The name of the resource or selector to wait for.", "examples": [ "podinfo", - "app=podinfo" + "app=podinfo" ] }, "namespace": { "type": "string", - "description": "The namespace of the resource to wait for" + "description": "The namespace of the resource to wait for." }, "condition": { "type": "string", - "description": "The condition or jsonpath state to wait for; defaults to exist", + "description": "The condition or jsonpath state to wait for; defaults to exist, a special condition that will wait for the resource to exist.", "examples": [ "Ready", "Available" @@ -705,6 +718,7 @@ "kind", "name" ], + "description": "ZarfComponentActionWaitCluster specifies a condition to wait for before continuing", "patternProperties": { "^x-": {} } @@ -718,11 +732,11 @@ "http", "https" ], - "description": "The protocol to wait for" + "description": "The protocol to wait for." }, "address": { "type": "string", - "description": "The address to wait for", + "description": "The address to wait for.", "examples": [ "localhost:8080", "1.1.1.1" @@ -730,7 +744,7 @@ }, "code": { "type": "integer", - "description": "The HTTP status code to wait for if using http or https", + "description": "The HTTP status code to wait for if using http or https.", "examples": [ 200, 404 @@ -743,6 +757,7 @@ "protocol", "address" ], + "description": "ZarfComponentActionWaitNetwork specifies a condition to wait for before continuing", "patternProperties": { "^x-": {} } @@ -751,19 +766,20 @@ "properties": { "onCreate": { "$ref": "#/$defs/ZarfComponentActionSet", - "description": "Actions to run during package creation" + "description": "Actions to run during package creation." }, "onDeploy": { "$ref": "#/$defs/ZarfComponentActionSet", - "description": "Actions to run during package deployment" + "description": "Actions to run during package deployment." }, "onRemove": { "$ref": "#/$defs/ZarfComponentActionSet", - "description": "Actions to run during package removal" + "description": "Actions to run during package removal." } }, "additionalProperties": false, "type": "object", + "description": "ZarfComponentActions are ActionSets that map to different zarf package operations.", "patternProperties": { "^x-": {} } @@ -772,11 +788,12 @@ "properties": { "bigbang": { "$ref": "#/$defs/BigBang", - "description": "Configurations for installing Big Bang and Flux in the cluster" + "description": "Configurations for installing Big Bang and Flux in the cluster." } }, "additionalProperties": false, "type": "object", + "description": "ZarfComponentExtensions is a struct that contains all the official extensions.", "patternProperties": { "^x-": {} } @@ -785,14 +802,14 @@ "properties": { "name": { "type": "string", - "description": "The name of the component to import from the referenced zarf.yaml" + "description": "The name of the component to import from the referenced zarf.yaml." }, "path": { "not": { "pattern": "###ZARF_PKG_TMPL_" }, "type": "string", - "description": "The relative path to a directory containing a zarf.yaml to import from" + "description": "The path to the directory containing the zarf.yaml to import." }, "url": { "not": { @@ -800,11 +817,12 @@ }, "type": "string", "pattern": "^oci://.*$", - "description": "[beta] The URL to a Zarf package to import via OCI" + "description": "[beta] The URL to a Zarf package to import via OCI." } }, "additionalProperties": false, "type": "object", + "description": "ZarfComponentImport structure for including imported Zarf components.", "patternProperties": { "^x-": {} } @@ -817,7 +835,7 @@ "amd64", "arm64" ], - "description": "Only create and deploy to clusters of the given architecture" + "description": "Only create and deploy to clusters of the given architecture." }, "distros": { "items": { @@ -828,11 +846,12 @@ ] }, "type": "array", - "description": "A list of kubernetes distros this package works with (Reserved for future use)" + "description": "A list of kubernetes distros this package works with (Reserved for future use)." } }, "additionalProperties": false, "type": "object", + "description": "ZarfComponentOnlyCluster represents the architecture and K8s cluster distribution to filter on.", "patternProperties": { "^x-": {} } @@ -846,19 +865,20 @@ "darwin", "windows" ], - "description": "Only deploy component to specified OS" + "description": "Only deploy component to specified OS." }, "cluster": { "$ref": "#/$defs/ZarfComponentOnlyCluster", - "description": "Only deploy component to specified clusters" + "description": "Only deploy component to specified clusters." }, "flavor": { "type": "string", - "description": "Only include this component when a matching '--flavor' is specified on 'zarf package create'" + "description": "Only include this component when a matching '--flavor' is specified on 'zarf package create'." } }, "additionalProperties": false, "type": "object", + "description": "ZarfComponentOnlyTarget filters a component to only show it for a given local OS and cluster.", "patternProperties": { "^x-": {} } @@ -867,22 +887,22 @@ "properties": { "namespace": { "type": "string", - "description": "The namespace to target for data injection" + "description": "The namespace to target for data injection." }, "selector": { "type": "string", - "description": "The K8s selector to target for data injection", + "description": "The K8s selector to target for data injection.", "examples": [ - "app=data-injection" + "app=data-injection" ] }, "container": { "type": "string", - "description": "The container name to target for data injection" + "description": "The container name to target for data injection." }, "path": { "type": "string", - "description": "The path within the container to copy the data into" + "description": "The path within the container to copy the data into." } }, "additionalProperties": false, @@ -893,6 +913,7 @@ "container", "path" ], + "description": "ZarfContainerTarget defines the destination info for a ZarfData target", "patternProperties": { "^x-": {} } @@ -901,15 +922,15 @@ "properties": { "source": { "type": "string", - "description": "Either a path to a local folder/file or a remote URL of a file to inject into the given target pod + container" + "description": "Either a path to a local folder/file or a remote URL of a file to inject into the given target pod + container." }, "target": { "$ref": "#/$defs/ZarfContainerTarget", - "description": "The target pod + container to inject the data into" + "description": "The target pod + container to inject the data into." }, "compress": { "type": "boolean", - "description": "Compress the data before transmitting using gzip. Note: this requires support for tar/gzip locally and in the target image." + "description": "Compress the data before transmitting using gzip. Note: this requires support for tar/gzip locally and in the target image." } }, "additionalProperties": false, @@ -918,6 +939,7 @@ "source", "target" ], + "description": "ZarfDataInjection is a data-injection definition.", "patternProperties": { "^x-": {} } @@ -926,30 +948,30 @@ "properties": { "source": { "type": "string", - "description": "Local folder or file path or remote URL to pull into the package" + "description": "Local folder or file path or remote URL to pull into the package." }, "shasum": { "type": "string", - "description": "(files only) Optional SHA256 checksum of the file" + "description": "(files only) Optional SHA256 checksum of the file." }, "target": { "type": "string", - "description": "The absolute or relative path where the file or folder should be copied to during package deploy" + "description": "The absolute or relative path where the file or folder should be copied to during package deploy." }, "executable": { "type": "boolean", - "description": "(files only) Determines if the file should be made executable during package deploy" + "description": "(files only) Determines if the file should be made executable during package deploy." }, "symlinks": { "items": { "type": "string" }, "type": "array", - "description": "List of symlinks to create during package deploy" + "description": "List of symlinks to create during package deploy." }, "extractPath": { "type": "string", - "description": "Local folder or file to be extracted from a 'source' archive" + "description": "Local folder or file to be extracted from a 'source' archive." } }, "additionalProperties": false, @@ -958,6 +980,7 @@ "source", "target" ], + "description": "ZarfFile defines a file to deploy.", "patternProperties": { "^x-": {} } @@ -966,33 +989,33 @@ "properties": { "name": { "type": "string", - "description": "A name to give this collection of manifests; this will become the name of the dynamically-created helm chart" + "description": "A name to give this collection of manifests; this will become the name of the dynamically-created helm chart." }, "namespace": { "type": "string", - "description": "The namespace to deploy the manifests to" + "description": "The namespace to deploy the manifests to." }, "files": { "items": { "type": "string" }, "type": "array", - "description": "List of local K8s YAML files or remote URLs to deploy (in order)" + "description": "List of local K8s YAML files or remote URLs to deploy (in order)." }, "kustomizeAllowAnyDirectory": { "type": "boolean", - "description": "Allow traversing directory above the current directory if needed for kustomization" + "description": "Allow traversing directory above the current directory if needed for kustomization." }, "kustomizations": { "items": { "type": "string" }, "type": "array", - "description": "List of local kustomization paths or remote URLs to include in the package" + "description": "List of local kustomization paths or remote URLs to include in the package." }, "noWait": { "type": "boolean", - "description": "Whether to not wait for manifest resources to be ready before continuing" + "description": "Whether to not wait for manifest resources to be ready before continuing." } }, "additionalProperties": false, @@ -1000,6 +1023,7 @@ "required": [ "name" ], + "description": "ZarfManifest defines raw manifests Zarf will deploy as a helm chart.", "patternProperties": { "^x-": {} } @@ -1009,31 +1033,31 @@ "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9\\-]*$", - "description": "Name to identify this Zarf package" + "description": "Name to identify this Zarf package." }, "description": { "type": "string", - "description": "Additional information about this package" + "description": "Additional information about this package." }, "version": { "type": "string", - "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 (Note: ZarfInitConfigs will always be versioned to the CLIVersion they were created with)." }, "url": { "type": "string", - "description": "Link to package information when online" + "description": "Link to package information when online." }, "image": { "type": "string", - "description": "An image URL to embed in this package (Reserved for future use in Zarf UI)" + "description": "An image URL to embed in this package (Reserved for future use in Zarf UI)." }, "uncompressed": { "type": "boolean", - "description": "Disable compression of this package" + "description": "Disable compression of this package." }, "architecture": { "type": "string", - "description": "The target cluster architecture for this package", + "description": "The target cluster architecture for this package.", "examples": [ "arm64", "amd64" @@ -1045,18 +1069,18 @@ }, "authors": { "type": "string", - "description": "Comma-separated list of package authors (including contact info)", + "description": "Comma-separated list of package authors (including contact info).", "examples": [ "Doug <hello@defenseunicorns.com>, Pepr <hello@defenseunicorns.com>" ] }, "documentation": { "type": "string", - "description": "Link to package documentation when online" + "description": "Link to package documentation when online." }, "source": { "type": "string", - "description": "Link to package source code when online" + "description": "Link to package source code when online." }, "vendor": { "type": "string", @@ -1072,6 +1096,7 @@ "required": [ "name" ], + "description": "ZarfMetadata lists information about the current ZarfPackage.", "patternProperties": { "^x-": {} } @@ -1084,16 +1109,16 @@ "ZarfInitConfig", "ZarfPackageConfig" ], - "description": "The kind of Zarf package", + "description": "The kind of Zarf package.", "default": "ZarfPackageConfig" }, "metadata": { "$ref": "#/$defs/ZarfMetadata", - "description": "Package metadata" + "description": "Package metadata." }, "build": { "$ref": "#/$defs/ZarfBuildData", - "description": "Zarf-generated package build data" + "description": "Zarf-generated package build data." }, "components": { "items": { @@ -1101,21 +1126,21 @@ }, "type": "array", "minItems": 1, - "description": "List of components to deploy in this package" + "description": "List of components to deploy in this package." }, "constants": { "items": { "$ref": "#/$defs/Constant" }, "type": "array", - "description": "Constant template values applied on deploy for K8s resources" + "description": "Constant template values applied on deploy for K8s resources." }, "variables": { "items": { "$ref": "#/$defs/InteractiveVariable" }, "type": "array", - "description": "Variable template values applied on deploy for K8s resources" + "description": "Variable template values applied on deploy for K8s resources." } }, "additionalProperties": false, @@ -1124,6 +1149,7 @@ "kind", "components" ], + "description": "ZarfPackage the top-level structure of a Zarf config file.", "patternProperties": { "^x-": {} }