Initial docs updates for alpha/beta/stable

.github/workflows/test-ui.yml

@@ -45,16 +45,11 @@ jobs:
           path: "~/.cache/ms-playwright/"
           key: ${{ runner.os }}-browsers
 
-      - name: Ensure playright is installed
+      - name: Ensure playwright is installed
         run: npx playwright install
 
       - name: Run UI tests
-        run: >
-          export NODE_PATH=$(pwd)/src/ui/node_modules &&
-          npm --prefix src/ui run test:pre-init &&
-          npm --prefix src/ui run test:init &&
-          npm --prefix src/ui run test:post-init &&
-          npm --prefix src/ui run test:connect
+        run: make test-ui
 
       - name: Save logs
         if: always()

.github/workflows/test-upgrade.yml

@@ -39,6 +39,14 @@ jobs:
         with:
           download-init-package: true
 
+      # Note we move the kubelet data to reduce the chance for disk pressure during the tests
+      - name: Move the kubelet root directory for 'k3s'
+        run: |
+          sudo mkdir -p /mnt/kubelet-data
+          echo >> zarf-config.toml
+          echo [package.deploy.set] >> zarf-config.toml
+          echo "k3s_args = '--disable traefik --kubelet-arg \"eviction-hard=imagefs.available<1%,nodefs.available<1%\" --kubelet-arg \"eviction-minimum-reclaim=imagefs.available=1%,nodefs.available=1%\"'" >> zarf-config.toml
+
       - name: Initialize the cluster with the release version
         # NOTE: "PATH=$PATH" preserves the default user $PATH. This is needed to maintain the version of zarf installed
         #       in a previous step. This test run will the current release to create a K3s cluster.
@@ -47,14 +55,15 @@ jobs:
           sudo env "PATH=$PATH" CI=true zarf init --components k3s,git-server,logging --confirm
           sudo chown $USER /tmp/zarf-*.log
 
-      - name: Create the upgrade test packages
+      - name: Create and deploy the upgrade test packages
         # NOTE: "PATH=$PATH" preserves the default user $PATH. This is needed to maintain the version of zarf installed
         #       in a previous step. This test run will the current release to create a K3s cluster.
         # chown the logs since they were originally created as root
         run: |
           zarf package create src/test/upgrade --set PODINFO_VERSION=6.3.3 --confirm
-          zarf package create src/test/upgrade --set PODINFO_VERSION=6.3.4 --confirm
           sudo env "PATH=$PATH" CI=true zarf package deploy zarf-package-test-upgrade-package-amd64-6.3.3.tar.zst --confirm
+          sudo env "PATH=$PATH" CI=true zarf tools kubectl describe deployments -n=podinfo-upgrade
+          sudo env "PATH=$PATH" CI=true zarf tools kubectl describe pods -n=podinfo-upgrade
           sudo chown $USER /tmp/zarf-*.log
 
       - name: Build PR binary and zarf packages
@@ -68,11 +77,30 @@ jobs:
           sudo env "PATH=$PATH" CI=true APPLIANCE_MODE=true make test-e2e ARCH=amd64
           sudo chown $USER /tmp/zarf-*.log
 
+      - name: "Cleanup after running tests"
+        # NOTE: This reduces disk pressure before the upgrade-specific tests begin
+        run: |
+          sudo lsblk -f
+          sudo k3s crictl images
+          sudo env "PATH=$PATH" CI=true zarf tools kubectl describe nodes
+          sudo env "PATH=$PATH" CI=true zarf tools kubectl describe deployments -n=podinfo-upgrade
+          sudo env "PATH=$PATH" CI=true zarf tools kubectl describe pods -n=podinfo-upgrade
+
+          sudo k3s crictl rmi --prune
+          sudo rm -rf zarf-sbom /tmp/zarf-*/
+          sudo env "PATH=$PATH" CI=true make delete-packages
+          sudo build/zarf tools clear-cache
+
+          sudo lsblk -f
+          sudo env "PATH=$PATH" CI=true zarf tools kubectl describe nodes
+
       - name: Run the upgrade tests
         # NOTE: "PATH=$PATH" preserves the default user $PATH. This is needed to maintain the version of zarf installed
         #       in a previous step. This test run will the current release to create a K3s cluster.
         # chown the logs since they were originally created as root
         run: |
+          zarf package create src/test/upgrade --set PODINFO_VERSION=6.3.4 --confirm
+
           sudo env "PATH=$PATH" CI=true make test-upgrade ARCH=amd64
           sudo chown $USER /tmp/zarf-*.log
 

CONTRIBUTING.md

@@ -2,6 +2,8 @@
 
 First off, thanks so much for wanting to help out! :tada:
 
+This document describes the steps and requirements for contributing a bug fix or feature in a Pull Request to Zarf!  If you have any questions about the process or the pull request you are working on feel free to reach out in the [Zarf Dev Kubernetes Slack Channel](https://kubernetes.slack.com/archives/C03BP9Z3CMA).
+
 ## Developer Experience
 
 Continuous Delivery is core to our development philosophy. Check out [https://minimumcd.org](https://minimumcd.org/) for a good baseline agreement on what that means.

Makefile

@@ -122,7 +122,7 @@ build-examples: ## Build all of the example packages
 
 	@test -s ./build/zarf-package-dos-games-$(ARCH).tar.zst || $(ZARF_BIN) package create examples/dos-games -o build -a $(ARCH) --confirm
 
-	@test -s ./build/zarf-package-remote-manifests-$(ARCH)-0.0.1.tar.zst || $(ZARF_BIN) package create examples/remote-manifests -o build -a $(ARCH) --confirm
+	@test -s ./build/zarf-package-manifests-$(ARCH)-0.0.1.tar.zst || $(ZARF_BIN) package create examples/manifests -o build -a $(ARCH) --confirm
 
 	@test -s ./build/zarf-package-component-actions-$(ARCH).tar.zst || $(ZARF_BIN) package create examples/component-actions -o build -a $(ARCH) --confirm
 
@@ -168,8 +168,25 @@ test-unit: ensure-ui-build-dir ## Run unit tests within the src/pkg and the bigb
 	cd src/pkg && go test ./... -failfast -v -timeout 30m
 	cd src/extensions/bigbang && go test ./. -failfast -v timeout 30m
 
-.PHONY: test-built-ui
-test-built-ui: ## Run the Zarf UI E2E tests (requires `make build-ui` first)
+.PHONY: test-ui
+test-ui: ## Run the Zarf UI E2E tests (requires `make build-ui` first) (run with env CI=true to use build/zarf)
+	export NODE_PATH=$(CURDIR)/src/ui/node_modules && \
+	npm --prefix src/ui run test:pre-init && \
+	npm --prefix src/ui run test:init && \
+	npm --prefix src/ui run test:post-init && \
+	npm --prefix src/ui run test:connect
+
+.PHONY: test-ui-dev-server
+# INTERNAL: used to start a dev version of the API server for the Zarf Web UI tests (locally)
+test-ui-dev-server:
+	API_DEV_PORT=5173 \
+		API_PORT=3333 \
+		API_TOKEN=insecure \
+		go run -ldflags="$(BUILD_ARGS)" main.go dev ui -l=trace
+
+.PHONY: test-ui-build-server
+# INTERNAL: used to start the built version of the API server for the Zarf Web UI (in CI)
+test-ui-build-server: 
 	API_PORT=3333 API_TOKEN=insecure $(ZARF_BIN) dev ui
 
 # INTERNAL: used to test that a dev has ran `make docs-and-schema` in their PR

adr/0015-artifact-server-support.md

@@ -21,4 +21,4 @@ It was decided to go with #2 since this would allow us to support a wider array
 
 ## Consequences
 
-For now this should be an internal-only feature while we work through issues and continue to experiment with this functionality given that it may be confusing to use or have rough edges for a while.  This also ties us to building specific http request matching logic for various artifact technologies which currently is done first via User Agent, then by parsing the URL to look for the artifact protocol specific path information.  While this works, it must be created per artifact technology and right now only supports git (http), pip, npm, and generic repositories and registries in Gitea and Gitlab.
+For now this should be an `internal`-only "alpha" feature while we work through issues and continue to experiment with this functionality given that it may be confusing to use or have rough edges for a while.  This also ties us to building specific http request matching logic for various artifact technologies which currently is done first via User Agent, then by parsing the URL to look for the artifact protocol specific path information.  While this works, it must be created per artifact technology and right now only supports git (http), pip, npm, and generic repositories and registries in Gitea and Gitlab.

docs/2-the-zarf-cli/100-cli-commands/zarf.md

@@ -9,7 +9,7 @@ Zarf eliminates the complexity of air gap software delivery for Kubernetes clust
 using a declarative packaging strategy to support DevSecOps in offline and semi-connected environments.
 
 ```
-zarf [COMMAND] [flags]
+zarf COMMAND [flags]
 ```
 
 ## Options
@@ -28,10 +28,10 @@ zarf [COMMAND] [flags]
 ## SEE ALSO
 
 * [zarf completion](zarf_completion.md)	 - Generate the autocompletion script for the specified shell
-* [zarf connect](zarf_connect.md)	 - Access services or pods deployed in the cluster.
-* [zarf destroy](zarf_destroy.md)	 - Tear it all down, we'll miss you Zarf...
+* [zarf connect](zarf_connect.md)	 - Accesses services or pods deployed in the cluster
+* [zarf destroy](zarf_destroy.md)	 - Tears down Zarf and removes its components from the environment
 * [zarf init](zarf_init.md)	 - Prepares a k8s cluster for the deployment of Zarf packages
 * [zarf package](zarf_package.md)	 - Zarf package commands for creating, deploying, and inspecting packages
 * [zarf prepare](zarf_prepare.md)	 - Tools to help prepare assets for packaging
 * [zarf tools](zarf_tools.md)	 - Collection of additional tools to make airgap easier
-* [zarf version](zarf_version.md)	 - Version of the Zarf binary
+* [zarf version](zarf_version.md)	 - Shows the version of the running Zarf binary

docs/2-the-zarf-cli/100-cli-commands/zarf_connect.md

@@ -1,7 +1,7 @@
 # zarf connect
 <!-- Auto-generated by docs/gen-cli-docs.sh -->
 
-Access services or pods deployed in the cluster.
+Accesses services or pods deployed in the cluster
 
 ## Synopsis
 
@@ -14,7 +14,7 @@ Packages can provide service manifests that define their own shortcut connection
 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.
 
 ```
-zarf connect {REGISTRY|LOGGING|GIT|connect-name} [flags]
+zarf connect { REGISTRY | LOGGING | GIT | connect-name } [flags]
 ```
 
 ## Options
@@ -44,4 +44,4 @@ zarf connect {REGISTRY|LOGGING|GIT|connect-name} [flags]
 ## SEE ALSO
 
 * [zarf](zarf.md)	 - DevSecOps for Airgap
-* [zarf connect list](zarf_connect_list.md)	 - List all available connection shortcuts.
+* [zarf connect list](zarf_connect_list.md)	 - Lists all available connection shortcuts

docs/2-the-zarf-cli/100-cli-commands/zarf_connect_list.md

@@ -1,7 +1,7 @@
 # zarf connect list
 <!-- Auto-generated by docs/gen-cli-docs.sh -->
 
-List all available connection shortcuts.
+Lists all available connection shortcuts
 
 ```
 zarf connect list [flags]
@@ -27,4 +27,4 @@ zarf connect list [flags]
 
 ## SEE ALSO
 
-* [zarf connect](zarf_connect.md)	 - Access services or pods deployed in the cluster.
+* [zarf connect](zarf_connect.md)	 - Accesses services or pods deployed in the cluster

docs/2-the-zarf-cli/100-cli-commands/zarf_destroy.md

@@ -1,7 +1,7 @@
 # zarf destroy
 <!-- Auto-generated by docs/gen-cli-docs.sh -->
 
-Tear it all down, we'll miss you Zarf...
+Tears down Zarf and removes its components from the environment
 
 ## Synopsis
 
@@ -14,7 +14,7 @@ If Zarf deployed your k8s cluster, this command will also tear your cluster down
 If Zarf did not deploy your k8s cluster, this command will delete the Zarf namespace, delete secrets and labels that only Zarf cares about, and optionally uninstall components that Zarf deployed onto the cluster. Since this is a cleanup operation, Zarf will not stop the uninstalls if one of the resources produce an error while being deleted.
 
 ```
-zarf destroy [flags]
+zarf destroy --confirm [flags]
 ```
 
 ## Options

docs/2-the-zarf-cli/100-cli-commands/zarf_init.md

@@ -21,32 +21,33 @@ zarf init [flags]
 ## Examples
 
 ```
-# Initializing without any optional components:
-zarf init
 
-# Initializing w/ Zarfs internal git server:
-zarf init --components=git-server
+	# Initializing without any optional components:
+	zarf init
 
-# Initializing w/ Zarfs internal git server and PLG stack:
-zarf init --components=git-server,logging
+	# Initializing w/ Zarfs internal git server:
+	zarf init --components=git-server
 
-# Initializing w/ an internal registry but with a different nodeport:
-zarf init --nodeport=30333
+	# Initializing w/ Zarfs internal git server and PLG stack:
+	zarf init --components=git-server,logging
 
-# Initializing w/ an external registry:
-zarf init --registry-push-password={PASSWORD} --registry-push-username={USERNAME} --registry-url={URL}
+	# Initializing w/ an internal registry but with a different nodeport:
+	zarf init --nodeport=30333
 
-# Initializing w/ an external git server:
-zarf init --git-push-password={PASSWORD} --git-push-username={USERNAME} --git-url={URL}
+	# Initializing w/ an external registry:
+	zarf init --registry-push-password={PASSWORD} --registry-push-username={USERNAME} --registry-url={URL}
+
+	# Initializing w/ an external git server:
+	zarf init --git-push-password={PASSWORD} --git-push-username={USERNAME} --git-url={URL}
 
 ```
 
 ## Options
 
 ```
-      --artifact-push-token string      API Token for the push-user to access the artifact registry
-      --artifact-push-username string   Username to access to the artifact registry Zarf is configured to use. User must be able to upload package artifacts.
-      --artifact-url string             External artifact registry url to use for this Zarf cluster
+      --artifact-push-token string      [alpha] API Token for the push-user to access the artifact registry
+      --artifact-push-username string   [alpha] Username to access to the artifact registry Zarf is configured to use. User must be able to upload package artifacts.
+      --artifact-url string             [alpha] External artifact registry url to use for this Zarf cluster
       --components string               Specify which optional components to install.  E.g. --components=git-server,logging
       --confirm                         Confirms package deployment without prompting. ONLY use with packages you trust. Skips prompts to review SBOM, configure variables, select optional components and review potential breaking changes.
       --git-pull-password string        Password for the pull-only user to access the git server

docs/2-the-zarf-cli/100-cli-commands/zarf_package.md

@@ -25,10 +25,10 @@ Zarf package commands for creating, deploying, and inspecting packages
 ## SEE ALSO
 
 * [zarf](zarf.md)	 - DevSecOps for Airgap
-* [zarf package create](zarf_package_create.md)	 - Use to create a Zarf package from a given directory or the current directory
-* [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)
-* [zarf package list](zarf_package_list.md)	 - List out all of the packages that have been deployed to the cluster
-* [zarf package publish](zarf_package_publish.md)	 - Publish a Zarf package to a remote registry
-* [zarf package pull](zarf_package_pull.md)	 - Pull a Zarf package from a remote registry and save to the local file system
-* [zarf package remove](zarf_package_remove.md)	 - Use to remove a Zarf package that has been deployed already
+* [zarf package create](zarf_package_create.md)	 - Creates a Zarf package from a given directory or the current directory
+* [zarf package deploy](zarf_package_deploy.md)	 - Deploys a Zarf package from a local file or URL (runs offline)
+* [zarf package inspect](zarf_package_inspect.md)	 - Displays the definition of a Zarf package (runs offline)
+* [zarf package list](zarf_package_list.md)	 - Lists out all of the packages that have been deployed to the cluster (runs offline)
+* [zarf package publish](zarf_package_publish.md)	 - Publishes a Zarf package to a remote registry
+* [zarf package pull](zarf_package_pull.md)	 - Pulls a Zarf package from a remote registry and save to the local file system
+* [zarf package remove](zarf_package_remove.md)	 - Removes a Zarf package that has been deployed already (runs offline)

docs/2-the-zarf-cli/100-cli-commands/zarf_package_create.md

@@ -1,23 +1,23 @@
 # zarf package create
 <!-- Auto-generated by docs/gen-cli-docs.sh -->
 
-Use to create a Zarf package from a given directory or the current directory
+Creates a Zarf package from a given directory or the current directory
 
 ## Synopsis
 
-Builds an archive of resources and dependencies defined by the 'zarf.yaml' in the active directory.
+Builds an archive of resources and dependencies defined by the 'zarf.yaml' in the specified directory.
 Private registries and repositories are accessed via credentials in your local '~/.docker/config.json', '~/.git-credentials' and '~/.netrc'.
 
 
 ```
-zarf package create [DIRECTORY] [flags]
+zarf package create [ DIRECTORY ] [flags]
 ```
 
 ## Options
 
 ```
       --confirm                            Confirm package creation without prompting
-      --differential string                Build a package that only contains the differential changes from local resources and differing remote resources from the specified previously built package
+      --differential string                [beta] Build a package that only contains the differential changes from local resources and differing remote resources from the specified previously built package
   -h, --help                               help for create
   -k, --key string                         Path to private key file for signing packages
       --key-pass string                    Password to the private key file used for signing packages

docs/2-the-zarf-cli/100-cli-commands/zarf_package_deploy.md

@@ -1,14 +1,15 @@
 # zarf package deploy
 <!-- Auto-generated by docs/gen-cli-docs.sh -->
 
-Use to deploy a Zarf package from a local file or URL (runs offline)
+Deploys a Zarf package from a local file or URL (runs offline)
 
 ## Synopsis
 
-Uses current kubecontext to deploy the packaged tarball onto a k8s cluster.
+Unpacks resources and dependencies from a Zarf package archive and deploys them onto the target system.
+Kubernetes clusters are accessed via credentials in your current kubecontext defined in '~/.kube/config'
 
 ```
-zarf package deploy [PACKAGE] [flags]
+zarf package deploy [ PACKAGE ] [flags]
 ```
 
 ## Options

docs/2-the-zarf-cli/100-cli-commands/zarf_package_inspect.md

@@ -1,15 +1,14 @@
 # zarf package inspect
 <!-- Auto-generated by docs/gen-cli-docs.sh -->
 
-Lists the payload of a Zarf package (runs offline)
+Displays the definition of a Zarf package (runs offline)
 
 ## Synopsis
 
-Lists the payload of a compiled package file (runs offline)
-Unpacks the package tarball into a temp directory and displays the contents of the archive.
+Displays the 'zarf.yaml' definition for the specified package and optionally allows SBOMs to be viewed
 
 ```
-zarf package inspect [PACKAGE] [flags]
+zarf package inspect [ PACKAGE ] [flags]
 ```
 
 ## Options

docs/2-the-zarf-cli/100-cli-commands/zarf_package_list.md

@@ -1,7 +1,7 @@
 # zarf package list
 <!-- Auto-generated by docs/gen-cli-docs.sh -->
 
-List out all of the packages that have been deployed to the cluster
+Lists out all of the packages that have been deployed to the cluster (runs offline)
 
 ```
 zarf package list [flags]

docs/2-the-zarf-cli/100-cli-commands/zarf_package_publish.md

@@ -1,21 +1,21 @@
 # zarf package publish
 <!-- Auto-generated by docs/gen-cli-docs.sh -->
 
-Publish a Zarf package to a remote registry
+Publishes a Zarf package to a remote registry
 
 ```
-zarf package publish [PACKAGE|SKELETON DIRECTORY] [REPOSITORY] [flags]
+zarf package publish { PACKAGE | SKELETON DIRECTORY } REPOSITORY [flags]
 ```
 
 ## Examples
 
 ```
 
-# Publish a package to a remote registry
-zarf package publish my-package.tar oci://my-registry.com/my-namespace
+	# Publish a package to a remote registry
+	zarf package publish my-package.tar oci://my-registry.com/my-namespace
 
-# Publish a skeleton package to a remote registry
-zarf package publish ./path/to/dir oci://my-registry.com/my-namespace
+	# Publish a skeleton package to a remote registry
+	zarf package publish ./path/to/dir oci://my-registry.com/my-namespace
 
 ```