Merge branch 'main' into restrict-gh-token-permissions

README.md

@@ -47,7 +47,7 @@ Zarf eliminates the [complexity of air gap software delivery](https://www.itopst
 
 ## 🛠️ Configurable Features
 
-- Customizable [variables and package templates](https://docs.zarf.dev/ref/variables/) with defaults and user prompting
+- Customizable [variables and package templates](https://docs.zarf.dev/ref/values/) with defaults and user prompting
 - [Composable packages](https://docs.zarf.dev/ref/components/#component-imports) to include multiple sub-packages/components
 - Component-level OS/architecture filtering
 
@@ -67,7 +67,7 @@ To discover more about Zarf and explore its features, please visit [docs.zarf.de
 - [packages](https://docs.zarf.dev/ref/packages)
 - [components](https://docs.zarf.dev/ref/components)
 - [actions](https://docs.zarf.dev/ref/actions)
-- [variables](https://docs.zarf.dev/ref/variables)
+- [variables](https://docs.zarf.dev/ref/values)
 - [SBOMs](https://docs.zarf.dev/ref/sboms)
 - and more!
 

hack/check-zarf-docs-and-schema.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env sh
 
-if [ -z "$(git status -s docs/ zarf.schema.json)" ]; then
+if [ -z "$(git status -s ./site/src/content/docs/commands/ ./zarf.schema.json)" ]; then
     echo "Success!"
     exit 0
 else
-    git diff docs/ zarf.schema.json
+    git diff ./site/src/content/docs/commands/ ./zarf.schema.json
     exit 1
 fi

site/src/components/SchemaItemProperties.astro

@@ -1,5 +1,5 @@
 ---
-const { item, include, invert } = Astro.props;
+const { item, include, invert, unwrap } = Astro.props;
 
 const includesElement = (key: string) => {
   if (!include) {
@@ -16,6 +16,21 @@ const json = await import("../assets/zarf.schema.json");
 // @ts-expect-error - We don't import a TS type for the schema, but we know it's structured correctly
 const itemSchema = json.definitions[item];
 
+if (unwrap) {
+  unwrap.forEach((wrapped: string) => {
+    if (itemSchema.properties[wrapped]) {
+      // @ts-expect-error - We don't import a TS type for the schema, but we know it's structured correctly
+      const wrappedSchema = json.definitions[wrapped];
+
+      delete itemSchema.properties[wrapped]
+      itemSchema.required = itemSchema.required.filter((elem: string) => elem != wrapped)
+
+      itemSchema.properties = {...wrappedSchema.properties, ...itemSchema.properties}
+      itemSchema.required = [...wrappedSchema.required, ...itemSchema.required]
+    }
+  });
+}
+
 const properties = Object.keys(itemSchema.properties)
   .filter(includesElement)
   .sort()

site/src/content/docs/faq.mdx

@@ -144,4 +144,4 @@ Typically you should not deploy a Zarf package in YOLO mode if the cluster has a
 
 A `skeleton` package is a bare-bones Zarf package definition alongside its associated local files and manifests that has been published to an OCI registry. These packages are intended for use with [component composability](/ref/components) to provide versioned imports for components that you wish to mix and match or modify with merge-overrides across multiple separate packages.
 
-Skeleton packages have not been run through the `zarf package create` process yet, and thus do not have any remote resources included (no images, repos, or remote manifests and files) thereby retaining any [create-time package configuration templates](/ref/variables) as they were defined in the original `zarf.yaml` (i.e. untemplated).
+Skeleton packages have not been run through the `zarf package create` process yet, and thus do not have any remote resources included (no images, repos, or remote manifests and files) thereby retaining any [create-time package configuration templates](/ref/values) as they were defined in the original `zarf.yaml` (i.e. untemplated).

site/src/content/docs/ref/components.mdx

@@ -117,7 +117,7 @@ Zarf dynamically generates a Helm Chart from the named manifest entries that you
 
 :::note
 
-Kustomizations are handled a bit differently than normal manifests in that Zarf will automatically run `kustomize build` on them during `zarf package create`, thus rendering the Kustomization into a single manifest file. This prevents needing to grab any remote Kustomization resources during `zarf package deploy` but also means that any Zarf [`variables`](/ref/variables/) will only apply to the rendered manifest not the `kustomize build` process.
+Kustomizations are handled a bit differently than normal manifests in that Zarf will automatically run `kustomize build` on them during `zarf package create`, thus rendering the Kustomization into a single manifest file. This prevents needing to grab any remote Kustomization resources during `zarf package deploy` but also means that any Zarf [`variables`](/ref/values/) will only apply to the rendered manifest not the `kustomize build` process.
 
 :::
 
@@ -222,7 +222,7 @@ The `import` key in Zarf supports two modes to pull in a component:
 
 :::caution
 
-The import `path` or `url` must be statically defined at create time.  You cannot use [package templates](/ref/variables/#create-time-package-configuration-templates) within them.
+The import `path` or `url` must be statically defined at create time.  You cannot use [package templates](/ref/create/#package-templates) within them.
 
 :::
 

site/src/content/docs/ref/create.mdx

@@ -96,3 +96,46 @@ You do not need to create init configs by yourself unless you want to customize
 To deploy a Zarf Package, you can use the command `zarf package deploy`. This will prompt you to select from all of the files in your current directory that match the name `zarf-package-*.tar.zst`. Alternatively, if you already know which package you want to deploy, you can simply use the command `zarf package deploy {PACKAGE_NAME}`.
 
 During the deployment process, Zarf will leverage the infrastructure created during the 'init' process (such as the Docker registry and Git server) to push all the necessary images and repositories required for the package to operate.
+
+
+### Package Templates
+
+:::caution
+
+`zarf package create` templates only template `###ZARF_PKG_TMPL_*###` entries the `zarf.yaml` file while `zarf package deploy` only templates other `manifests`, `charts`, `files`, and `actions`.  To learn more about using deployment values see the [Deployment Values](/ref/values) page.
+
+:::
+
+You can also specify `zarf.yaml` package configuration templates at package create time by including `###_ZARF_PKG_TMPL_*###` as the value for any string-type data in your package definition. These values are discovered during `zarf package create` and will always be prompted for if not using `--confirm` or `--set`. An example of this is below:
+
+```yaml
+kind: ZarfPackageConfig
+metadata:
+  name: 'pkg-variables'
+  description: 'Prompt for a variables during package create'
+
+constants:
+  - name: PROMPT_IMAGE
+    value: '###ZARF_PKG_TMPL_PROMPT_ON_CREATE###'
+
+components:
+  - name: zarf-prompt-image
+    required: true
+    images:
+      - '###ZARF_PKG_TMPL_PROMPT_ON_CREATE###'
+```
+
+:::caution
+
+It is not recommended to use package configuration templates for any `sensitive` data as this will be baked into the package as plain text.  Please use a deploy-time variable with the `sensitive` key set instead.
+
+:::
+
+:::note
+
+You can only template string values in this way as non-string values will not marshal/unmarshal properly through the yaml.
+
+Additionally, you cannot template the component import path using package configuration templates
+
+:::
+

site/src/content/docs/ref/values.mdx

@@ -0,0 +1,151 @@
+---
+title: Deployment Values
+sidebar:
+  order: 35
+---
+
+import Properties from '@components/SchemaItemProperties.astro';
+import ExampleYAML from "@components/ExampleYAML.astro";
+
+Deploy time values are used throughout the Zarf deployment process to template `manifests` and `files`, set Helm values, or provide environment variables for `actions`, and can be provided by the `zarf package deploy` user, the `zarf package create` user, or internally by Zarf itself.
+
+## Using Values
+
+### Value Templates
+
+Values can be templated into `manifests`, `files`, and `charts` using a unique `###ZARF_<VALUE_KEY>###` syntax anywhere in the file, where `<VALUE_KEY>` is the name of the value along with any associated prefix in ALL_CAPS (see [Setting Values](#setting-values) below).  This allows you to punch through other templating engines to place values precisely where you want in a given file.  You can also control how this templating happens when defining a value such as with the `autoIndent` key on `constants` and `variables`.  A simple value template for a [Zarf Variable](#variables-zarf_var_) named `DATABASE_USERNAME` would look like the following:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: db-configmap
+data:
+  username: ###ZARF_VAR_DATABASE_USERNAME###
+```
+
+### Helm Chart Mapping
+
+[Zarf Variables](#variables-zarf_var_) can also be mapped directly to Helm values within a given `charts` definition.  This is done with the `variables` key within a chart that allows you to take a Zarf Variable `name` and map it to a YAML path within that chart's Helm values.  This chart's Helm value will then be set to the current value of the Zarf Variable at the time of it's installation.
+
+```yaml
+    charts:
+      - name: wordpress
+        version: 16.0.4
+        namespace: wordpress
+        localPath: chart
+        variables:
+          - name: DATABASE_USERNAME
+            path: db.username
+```
+
+<Properties item="ZarfChartVariable" />
+
+:::caution
+
+Chart `variables` in Zarf are currently an `alpha` feature and may be subject to change in later versions of Zarf.
+
+:::
+
+### Environment Variables
+
+Zarf `actions` can also pull values from the shell's environment when running a `cmd`.  These values are available under the same `ZARF_<VALUE_KEY>` as value templates (without any `#`s) and can be used like the below:
+
+```yaml
+    actions:
+      onDeploy:
+        after:
+          - cmd: echo ${ZARF_VAR_DATABASE_USERNAME}
+```
+
+## Setting Values
+
+:::note
+
+All value `name` fields must match the regex pattern `^[A-Z0-9_]+$` ([Test](https://regex101.com/r/BG5ZqW/1)).
+
+:::
+
+### Variables (`ZARF_VAR_`)
+
+Variables are dynamic values that are set by the `zarf package deploy` user or internally by the outputs of `actions`.  When used they are prefixed with `ZARF_VAR`, and they can be defined with the top-level `variables` key for input by the user:
+
+```yaml
+variables:
+  name: DATABASE_USERNAME
+  description: 'The username for the database'
+```
+
+<Properties item="InteractiveVariable" unwrap={["Variable"]} />
+
+Or can be set within an `actions` `setVariables` key to take the value from the standard output of the given `cmd`:
+
+```yaml
+components:
+  - name: set-variable-example
+    actions:
+      onDeploy:
+        after:
+          - cmd: echo "username-value"
+            setVariables:
+              - name: DATABASE_USERNAME
+```
+
+<Properties item="Variable" />
+
+:::note
+
+Variables with `type: file` will be set to the filepath when used in `actions` (see [Environment Variables](#environment-variables) above) due to constraints on the size of environment variables in the shell.  This also allows for additional processing of the file by its filename.
+
+:::
+
+:::tip
+
+
+For user-specified variables, you can specify a `default` value for the variable to take in case a user does not provide one on deploy, and can specify whether to `prompt` the user for the variable when not using the `--confirm` or `--set` flags.
+
+```yaml
+variables:
+  name: DATABASE_USERNAME
+  default: 'postgres'
+  prompt: true
+```
+
+When not specifying `default`, `prompt`, `sensitive`, `autoIndent`, or `type` Zarf will default to `default: ""`, `prompt: false`, `sensitive: false`, `autoIndent: false`, and `type: "raw"`
+
+:::
+
+### Constants (`ZARF_CONST_`)
+
+Constants are static values that are set by the `zarf package create` user and are used as a way to bake in a common value that the package creator would like to template or use within the deployment process.  They are useful to centralize the setting of resources that will be baked into the package (such as image references) to have a singular place to update potentially many downstream references.  They are set with a top-level `constants` key as in the below:
+
+```yaml
+constants:
+  name: DATABASE_USERNAME
+  description: 'The username for the database'
+  value: 'postgres'
+```
+
+<Properties item="Constant" />
+
+
+### Internal Values (`ZARF_`)
+
+In addition to user supplied Variables, and Constants, Zarf maintains a list of internal variables that components can use for more advanced functionality (such as within [`init` packages](/ref/init-package)).  Below are the current values Zarf supports:
+
+- `STORAGE_CLASS`: Storage class specified for persistent storage within the Kubernetes cluster (maps to `--storage-class` on `zarf init`)
+- `REGISTRY`: Address of the registry server used during `zarf init` (maps to `--registry-url` on `zarf init`)
+- `NODEPORT`: Nodeport used for a registry internal to the cluster (maps to `--nodeport` on `zarf init`)
+- `REGISTRY_AUTH_PUSH`: Password for pushing images to the registry (maps to `--registry-push-password` on `zarf init`)
+- `REGISTRY_AUTH_PULL`: Password for pulling images from the registry (maps to `--registry-pull-password` on `zarf init`)
+- `GIT_PUSH`: Username utilized for pushing changes to the Git server (maps to `--git-push-username` on `zarf init`)
+- `GIT_AUTH_PUSH`: Password required for pushing changes to the Git server (maps to `--git-push-password` on `zarf init`)
+- `GIT_PULL`: Username employed for pulling changes from the Git server (maps to `--git-pull-username` on `zarf init`)
+- `GIT_AUTH_PULL`: Password required for pulling changes from the Git server (maps to `--git-pull-password` on `zarf init`)
+- `DATA_INJECTION_MARKER`: The marker used within a `dataInjection` target Pod `spec` that Zarf uses to track a data injection
+
+:::note
+
+Because files can be deployed without a Kubernetes cluster, some built-in values such as `###ZARF_REGISTRY###` may not be available if no previous component has required access to the cluster. If you need one of these built-in values, a prior component will need to have been called that requires access to the cluster, such as `images`, `repos`, `charts`, `manifests`, or `dataInjections`.
+
+:::