Move variable definitions from components to packages

.hooks/jsfh-config.json

@@ -2,5 +2,6 @@
   "custom_template_path": ".hooks/zarf-jsfh-template/base.md",
   "template_md_options": { "badge_as_image": true, "show_heading_numbers": false },
   "show_toc": false,
-  "show_breadcrumbs": false
+  "show_breadcrumbs": false,
+  "footer_show_time": false
 }

Makefile

@@ -16,6 +16,8 @@ ifneq ($(UNAME_S),Linux)
 	endif
 endif
 
+AGENT_IMAGE ?= defenseunicorns/zarf-agent:992efd
+
 CLI_VERSION := $(if $(shell git describe --tags), $(shell git describe --tags), "UnknownVersion")
 BUILD_ARGS := -s -w -X 'github.com/defenseunicorns/zarf/src/config.CLIVersion=$(CLI_VERSION)'
 .DEFAULT_GOAL := help
@@ -76,7 +78,7 @@ dev-agent-image:
 init-package: ## Create the zarf init package, macos "brew install coreutils" first
 	@test -s $(ZARF_BIN) || $(MAKE) build-cli
 
-	@test -s ./build/zarf-init-$(ARCH).tar.zst || $(ZARF_BIN) package create -o build -a $(ARCH) --confirm .
+	@test -s ./build/zarf-init-$(ARCH).tar.zst || $(ZARF_BIN) package create -o build -a $(ARCH) --set AGENT_IMAGE=$(AGENT_IMAGE) --confirm .
 
 ci-release: init-package ## Create the init package
 
@@ -89,7 +91,7 @@ build-examples:
 
 	@test -s ./build/zarf-package-component-choice-$(ARCH).tar.zst || $(ZARF_BIN) package create examples/component-choice -o build -a $(ARCH) --confirm
 
-	@test -s ./build/zarf-package-component-variables-$(ARCH).tar.zst || $(ZARF_BIN) package create examples/component-variables -o build -a $(ARCH) --confirm
+	@test -s ./build/zarf-package-package-variables-$(ARCH).tar.zst || $(ZARF_BIN) package create examples/package-variables --set CONFIG_MAP=simple-configmap.yaml --set ACTION=template -o build -a $(ARCH) --confirm
 
 	@test -s ./build/zarf-package-data-injection-demo-$(ARCH).tar || $(ZARF_BIN) package create examples/data-injection -o build -a $(ARCH) --confirm
 
@@ -101,8 +103,8 @@ build-examples:
 
 	@test -s ./build/zarf-package-flux-test-${ARCH}.tar.zst || $(ZARF_BIN) package create examples/flux-test -o build -a $(ARCH) --confirm
 
-## Run e2e tests. Will automatically build any required dependencies that aren't present. 
+## Run e2e tests. Will automatically build any required dependencies that aren't present.
 ## Requires an existing cluster for the env var APPLIANCE_MODE=true
 .PHONY: test-e2e
-test-e2e: init-package build-examples 
+test-e2e: init-package build-examples
 	cd src/test/e2e && go test -failfast -v -timeout 30m

adr/0006-package-variables.md

@@ -0,0 +1,31 @@
+# 6. package variables
+
+Date: 2022-07-28
+
+## Status
+
+Accepted
+
+## Context
+
+Currently, Zarf only allows variables to be specified within components which introduces the following limitations:
+
+ - Variables are scoped to the component making reuse between components impossible
+ - Variables cannot be used for elements within the package definition itself
+ - Variables can only be set at create time, not by a user at deploy time
+
+This forces a package creator to copy information within their package/component definitions and also requires them to make bespoke packages per environment even if only small changes are needed to the overall spec (such as changing a domain name).
+
+## Decision
+
+The decision was made to move variable definitions to the package level and to split "variables" into three distinct types:
+
+- Variables (specified with the `variables` yaml key) allow for the templating of component files similar to the component variables before them.  The main changes are that they are now specified at the package level (allowing for reuse between components) and have additional prompting and defaulting features to allow a package creator to ask for more information during `zarf package deploy`.
+- Constants (specified with the `constants` yaml key) also template component files, but must be specified at package create time.  This allows a package creator to use the same value in multiple places without the need for copying it and without the package deployer being able to override it.
+- Package Variables (specified by using `###ZARF_PKG_VAR_*###` in the package definition) allow package creators to template the same information multiple times within the package definition or dynamically specify values or defaults in constants and variables.
+
+## Consequences
+
+This makes it easier to build a single package that will apply to multiple environments and helps package creators to develop automation around their packages while keeping their package definitions DRY.  Choosing to have constants *and* variables also allows us to reduce potential confusion from package deployers who would otherwise be able to accidentally override values that are meant to be static.
+
+As for drawbacks, the largest one is that this provides the potential for a user to build imperative packages depending on what they template or are allowed to template.  This will need to be considered carefully in the future.  The current implementation also ties us to only templating string values for the time being and we will have to think through what should be technically variablizable in the future (for example variables cannot be used in component import paths because this would introduce a lot of fragility for not much perceived user benefit).

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf.md

@@ -26,4 +26,4 @@ zarf [COMMAND] [flags]
 * [zarf tools](zarf_tools.md)	 - Collection of additional tools to make airgap easier
 * [zarf version](zarf_version.md)	 - Displays the version of the Zarf binary
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_completion.md

@@ -30,4 +30,4 @@ See each sub-command's help for details on how to use the generated script.
 * [zarf completion powershell](zarf_completion_powershell.md)	 - Generate the autocompletion script for powershell
 * [zarf completion zsh](zarf_completion_zsh.md)	 - Generate the autocompletion script for zsh
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_completion_bash.md

@@ -49,4 +49,4 @@ zarf completion bash
 
 * [zarf completion](zarf_completion.md)	 - Generate the autocompletion script for the specified shell
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_completion_fish.md

@@ -40,4 +40,4 @@ zarf completion fish [flags]
 
 * [zarf completion](zarf_completion.md)	 - Generate the autocompletion script for the specified shell
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_completion_powershell.md

@@ -37,4 +37,4 @@ zarf completion powershell [flags]
 
 * [zarf completion](zarf_completion.md)	 - Generate the autocompletion script for the specified shell
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_completion_zsh.md

@@ -51,4 +51,4 @@ zarf completion zsh [flags]
 
 * [zarf completion](zarf_completion.md)	 - Generate the autocompletion script for the specified shell
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_connect.md

@@ -8,7 +8,7 @@ Uses a k8s port-forward to connect to resources within the cluster referenced by
 Three default options for this command are <REGISTRY|LOGGING|GIT>. These will connect to the Zarf created resources (assuming they were selected when performing the `zarf init` command).
 
 Packages can provide service manifests that define their own shortcut connection options. These options will be printed to the terminal when the package finishes deploying.
- If you don't remember what connection shortcuts your deployed package offers, you can search your cluster for services that have the 'zarf.dev/connect-name' label. The value of that label is the name you will pass into the 'zarf connect' command. 
+ If you don't remember what connection shortcuts your deployed package offers, you can search your cluster for services that have the 'zarf.dev/connect-name' label. The value of that label is the name you will pass into the 'zarf connect' command.
 
 Even if the packages you deploy don't define their own shortcut connection options, you can use the command flags to connect into specific resources. You can read the command flag descriptions below to get a better idea how to connect to whatever resource you are trying to connect to.
 
@@ -41,4 +41,4 @@ zarf connect <REGISTRY|LOGGING|GIT> [flags]
 * [zarf](zarf.md)	 - DevSecOps Airgap Toolkit
 * [zarf connect list](zarf_connect_list.md)	 - List all available connection shortcuts.
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_connect_list.md

@@ -24,4 +24,4 @@ zarf connect list [flags]
 
 * [zarf connect](zarf_connect.md)	 - Access services or pods deployed in the cluster.
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_destroy.md

@@ -36,4 +36,4 @@ zarf destroy [flags]
 
 * [zarf](zarf.md)	 - DevSecOps Airgap Toolkit
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_init.md

@@ -4,7 +4,7 @@ Prepares a k8s cluster for the deployment of Zarf packages
 
 ### Synopsis
 
-Injects a docker registry as well as other optional useful things (such as a git server and a logging stack) into a k8s cluster under the 'zarf' namespace to support future application deployments. 
+Injects a docker registry as well as other optional useful things (such as a git server and a logging stack) into a k8s cluster under the 'zarf' namespace to support future application deployments.
 If you do not have a k8s cluster already configured, this command will give you the ability to install a cluster locally.
 
 This command looks for a zarf-init package in the local directory that the command was executed from. If no package is found in the local directory and the Zarf CLI exists somewhere outside of the current directory, Zarf will failover and attempt to find a zarf-init package in the directory that the Zarf binary is located in.
@@ -38,4 +38,4 @@ zarf init [flags]
 
 * [zarf](zarf.md)	 - DevSecOps Airgap Toolkit
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_package.md

@@ -23,4 +23,4 @@ Zarf package commands for creating, deploying, and inspecting packages
 * [zarf package deploy](zarf_package_deploy.md)	 - Use to deploy a Zarf package from a local file or URL (runs offline)
 * [zarf package inspect](zarf_package_inspect.md)	 - Lists the payload of a Zarf package (runs offline)
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_package_create.md

@@ -19,6 +19,7 @@ zarf package create [DIRECTORY] [flags]
   -h, --help                      help for create
       --insecure                  Allow insecure registry connections when pulling OCI images
   -o, --output-directory string   Specify the output directory for the created Zarf package
+      --set stringToString        Specify package variables to set on the command line (KEY=value) (default [])
       --skip-sbom                 Skip generating SBOM for this package
       --tmpdir string             Specify the temporary directory to use for intermediate files
       --zarf-cache string         Specify the location of the Zarf image cache (default ".zarf-image-cache")
@@ -36,4 +37,4 @@ zarf package create [DIRECTORY] [flags]
 
 * [zarf package](zarf_package.md)	 - Zarf package commands for creating, deploying, and inspecting packages
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_package_deploy.md

@@ -13,13 +13,14 @@ zarf package deploy [PACKAGE] [flags]
 ### Options
 
 ```
-      --components string   Comma-separated list of components to install.  Adding this flag will skip the init prompts for which components to install
-      --confirm             Confirm package deployment without prompting
-  -h, --help                help for deploy
-      --insecure --shasum   Skip shasum validation of remote package. Required if deploying a remote package and --shasum is not provided
-      --sget string         Path to public sget key file for remote packages signed via cosign
-      --shasum --insecure   Shasum of the package to deploy. Required if deploying a remote package and --insecure is not provided
-      --tmpdir string       Specify the temporary directory to use for intermediate files
+      --components string    Comma-separated list of components to install.  Adding this flag will skip the init prompts for which components to install
+      --confirm              Confirm package deployment without prompting
+  -h, --help                 help for deploy
+      --insecure --shasum    Skip shasum validation of remote package. Required if deploying a remote package and --shasum is not provided
+      --set stringToString   Specify deployment variables to set on the command line (KEY=value) (default [])
+      --sget string          Path to public sget key file for remote packages signed via cosign
+      --shasum --insecure    Shasum of the package to deploy. Required if deploying a remote package and --insecure is not provided
+      --tmpdir string        Specify the temporary directory to use for intermediate files
 ```
 
 ### Options inherited from parent commands
@@ -34,4 +35,4 @@ zarf package deploy [PACKAGE] [flags]
 
 * [zarf package](zarf_package.md)	 - Zarf package commands for creating, deploying, and inspecting packages
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_package_inspect.md

@@ -30,4 +30,4 @@ zarf package inspect [PACKAGE] [flags]
 
 * [zarf package](zarf_package.md)	 - Zarf package commands for creating, deploying, and inspecting packages
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_prepare.md

@@ -20,8 +20,8 @@ Tools to help prepare assets for packaging
 
 * [zarf](zarf.md)	 - DevSecOps Airgap Toolkit
 * [zarf prepare find-images](zarf_prepare_find-images.md)	 - Evaluates components in a zarf file to identify images specified in their helm charts and manifests
-* [zarf prepare patch-git](zarf_prepare_patch-git.md)	 - Converts all .git URLs to the specified Zarf HOST and with the Zarf URL pattern in a given FILE.  NOTE: 
+* [zarf prepare patch-git](zarf_prepare_patch-git.md)	 - Converts all .git URLs to the specified Zarf HOST and with the Zarf URL pattern in a given FILE.  NOTE:
 This should only be used for manifests that are not mutated by the Zarf Agent Mutating Webhook.
 * [zarf prepare sha256sum](zarf_prepare_sha256sum.md)	 - Generate a SHA256SUM for the given file
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_prepare_find-images.md

@@ -17,6 +17,7 @@ zarf prepare find-images [flags]
 ```
   -h, --help                     help for find-images
   -p, --repo-chart-path string   If git repos hold helm charts, often found with gitops tools, specify the chart path, e.g. "/" or "/chart"
+      --set stringToString       Specify package variables to set on the command line (KEY=value) (default [])
       --tmpdir string            Specify the temporary directory to use for intermediate files
 ```
 
@@ -32,4 +33,4 @@ zarf prepare find-images [flags]
 
 * [zarf prepare](zarf_prepare.md)	 - Tools to help prepare assets for packaging
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_prepare_patch-git.md

@@ -1,6 +1,6 @@
 ## zarf prepare patch-git
 
-Converts all .git URLs to the specified Zarf HOST and with the Zarf URL pattern in a given FILE.  NOTE: 
+Converts all .git URLs to the specified Zarf HOST and with the Zarf URL pattern in a given FILE.  NOTE:
 This should only be used for manifests that are not mutated by the Zarf Agent Mutating Webhook.
 
 ```
@@ -25,4 +25,4 @@ zarf prepare patch-git [HOST] [FILE] [flags]
 
 * [zarf prepare](zarf_prepare.md)	 - Tools to help prepare assets for packaging
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_prepare_sha256sum.md

@@ -24,4 +24,4 @@ zarf prepare sha256sum [FILE|URL] [flags]
 
 * [zarf prepare](zarf_prepare.md)	 - Tools to help prepare assets for packaging
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools.md

@@ -24,4 +24,4 @@ Collection of additional tools to make airgap easier
 * [zarf tools monitor](zarf_tools_monitor.md)	 - Launch K9s tool for managing K8s clusters
 * [zarf tools registry](zarf_tools_registry.md)	 - Collection of registry commands provided by Crane
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools_archiver.md

@@ -22,4 +22,4 @@ Compress/Decompress tools for Zarf packages
 * [zarf tools archiver compress](zarf_tools_archiver_compress.md)	 - Compress a collection of sources based off of the destination file extension
 * [zarf tools archiver decompress](zarf_tools_archiver_decompress.md)	 - Decompress an archive (package) to a specified location.
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools_archiver_compress.md

@@ -24,4 +24,4 @@ zarf tools archiver compress [SOURCES] [ARCHIVE] [flags]
 
 * [zarf tools archiver](zarf_tools_archiver.md)	 - Compress/Decompress tools for Zarf packages
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools_archiver_decompress.md

@@ -24,4 +24,4 @@ zarf tools archiver decompress [ARCHIVE] [DESTINATION] [flags]
 
 * [zarf tools archiver](zarf_tools_archiver.md)	 - Compress/Decompress tools for Zarf packages
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools_get-admin-password.md

@@ -24,4 +24,4 @@ zarf tools get-admin-password [flags]
 
 * [zarf tools](zarf_tools.md)	 - Collection of additional tools to make airgap easier
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools_monitor.md

@@ -24,4 +24,4 @@ zarf tools monitor [flags]
 
 * [zarf tools](zarf_tools.md)	 - Collection of additional tools to make airgap easier
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools_registry.md

@@ -25,4 +25,4 @@ Collection of registry commands provided by Crane
 * [zarf tools registry pull](zarf_tools_registry_pull.md)	 - Pull remote images by reference and store their contents locally
 * [zarf tools registry push](zarf_tools_registry_push.md)	 - Push local image contents to a remote registry
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools_registry_catalog.md

@@ -24,4 +24,4 @@ zarf tools registry catalog [flags]
 
 * [zarf tools registry](zarf_tools_registry.md)	 - Collection of registry commands provided by Crane
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools_registry_copy.md

@@ -24,4 +24,4 @@ zarf tools registry copy SRC DST [flags]
 
 * [zarf tools registry](zarf_tools_registry.md)	 - Collection of registry commands provided by Crane
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools_registry_login.md

@@ -27,4 +27,4 @@ zarf tools registry login [OPTIONS] [SERVER] [flags]
 
 * [zarf tools registry](zarf_tools_registry.md)	 - Collection of registry commands provided by Crane
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools_registry_pull.md

@@ -26,4 +26,4 @@ zarf tools registry pull IMAGE TARBALL [flags]
 
 * [zarf tools registry](zarf_tools_registry.md)	 - Collection of registry commands provided by Crane
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_tools_registry_push.md

@@ -30,4 +30,4 @@ zarf tools registry push PATH IMAGE [flags]
 
 * [zarf tools registry](zarf_tools_registry.md)	 - Collection of registry commands provided by Crane
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022

docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_version.md

@@ -28,4 +28,4 @@ zarf version [flags]
 
 * [zarf](zarf.md)	 - DevSecOps Airgap Toolkit
 
-###### Auto generated by spf13/cobra on 17-Jul-2022
+###### Auto generated by spf13/cobra on 25-Jul-2022