Merge branch 'main' into 1582-error-handling-for-package-deployment

.gitignore

@@ -20,6 +20,7 @@
 *.tgz
 *.vbox
 *.zst
+*.zim
 assets/
 build
 bundle/

Makefile

@@ -130,7 +130,7 @@ build-examples: ## Build all of the example packages
 
 	@test -s ./build/zarf-package-variables-$(ARCH).tar.zst || $(ZARF_BIN) package create examples/variables --set NGINX_VERSION=1.23.3 -o build -a $(ARCH) --confirm
 
-	@test -s ./build/zarf-package-data-injection-$(ARCH).tar || $(ZARF_BIN) package create examples/data-injection -o build -a $(ARCH) --confirm
+	@test -s ./build/zarf-package-kiwix-$(ARCH)-3.5.0.tar || $(ZARF_BIN) package create examples/kiwix -o build -a $(ARCH) --confirm
 
 	@test -s ./build/zarf-package-git-data-$(ARCH)-0.0.1.tar.zst || $(ZARF_BIN) package create examples/git-data -o build -a $(ARCH) --confirm
 

docs/0-zarf-overview.md

@@ -67,7 +67,7 @@ Given Zarf's being a "K8s cluster to serve _other_ K8s clusters", the following
 - Pre-compiled binaries: to provide the software necessary to start and support the Zarf cluster.
 - [Component actions](3-create-a-zarf-package/7-component-actions.md): to support scripts and commands that run at various stages of the Zarf [package create lifecycle](./3-create-a-zarf-package/5-package-create-lifecycle.md), and [package deploy lifecycle](./4-deploy-a-zarf-package/1-package-deploy-lifecycle.md).
 - Helm charts, kustomizations, and other K8s manifests: to apply in a Kubernetes cluster.
-- [Data injections](../examples/data-injection/README.md): to declaratively inject data into running containers in a Kubernetes cluster.
+- [Data injections](../examples/kiwix/README.md): to declaratively inject data into running containers in a Kubernetes cluster.
 
 ## How To Use Zarf
 

docs/3-create-a-zarf-package/2-zarf-components.md

@@ -160,7 +160,7 @@ The [`podinfo-flux`](/examples/podinfo-flux/) example showcases a simple GitOps
 
 <Properties item="ZarfComponent" include={["dataInjections"]} />
 
-<ExampleYAML example="data-injection" component="with-init-container" />
+<ExampleYAML example="kiwix" component="kiwix-serve" />
 
 ### Component Imports
 

examples/component-actions/README.md

@@ -4,7 +4,7 @@ import ExampleYAML from '@site/src/components/ExampleYAML';
 
 :::note
 
-Component Actions have replaced Component Scripts. Zarf will still read scripts entries, but will convert them to actions. Component Scripts will be removed in a future release. Please update your package configurations to use Component Actions instead.
+Component Actions have replaced Component Scripts. Zarf will still read `scripts` entries, but will convert them to `actions`. Component Scripts will be removed in a future release. Please update your package configurations to use Component Actions instead.
 
 :::
 

examples/component-actions/zarf.yaml

@@ -13,47 +13,54 @@ components:
     actions:
       # runs during "zarf package create"
       onCreate:
-        # defaults are applied to all actions in this actionSet
+        # defaults are applied to all actions in this action set - below are the default defaults
         defaults:
           dir: ""
           env: []
           maxRetries: 0
-          maxTotalSeconds: 30
+          maxTotalSeconds: 300
+          mute: false
+          shell:
+            darwin: sh
+            linux: sh
+            windows: powershell
         # runs before the component is created
         before:
-          # on Windows, touch is replaced with New-Item
+          # on Windows with `pwsh` or `powershell`, `touch` is replaced with New-Item
           - cmd: touch test-create-before.txt
+            # description shows a more user friendly message when waiting for the command
+            description: Create a test file
             # dir is the directory to run the command in
             dir: ""
-            # this environment variable will be set for this action only
+            # env sets environment variables for this action only
             env:
               - thing=stuff
-            # the number of times to retry the action if it fails
+            # maxRetries is the number of times to retry the action if it fails
             maxRetries: 0
-            # the maximum amount of times the action can run before it is killed, including retries
+            # maxTotalSeconds is the maximum amount of times the action can run before it is killed, including retries
             maxTotalSeconds: 30
-            # determine if actions output should be printed to the console
+            # mute determine if actions output should be printed to the console
             mute: false
-        # runs after the component is deployed
+            # shell sets the preferred shell across operating systems, in this case "pwsh" instead of "powershell" on Windows
+            shell:
+              windows: pwsh
+        # runs after the component is created
         after:
+          # actions in a list run in order
           - cmd: touch test-create-after.txt
-          - cmd: sleep 1
+          - cmd: sleep 0.5
           - cmd: echo "I can print!"
-            # prefer to run the above command in "cmd" instead of "powershell" on Windows
-            shell:
-              windows: cmd
-          - cmd: sleep 1
+          - cmd: sleep 0.5
+          # cmd actions can also specify a multiline string to run like a script
           - cmd: |
               echo "multiline!"
-              sleep 1
+              sleep 0.5
               echo "updates!"
-              sleep 3
-              echo "in!"
               sleep 1
+              echo "in!"
+              sleep 0.5
               echo "realtime!"
-              sleep 1
-            description: multiline & description demo
-          - cmd: sleep 1
+              sleep 0.5
 
   - name: on-deploy-and-remove
     actions:
@@ -105,18 +112,21 @@ components:
           # setting this variable will allow it to be used in other actions with additional variables
           # set in other actions or components
           - cmd: echo "hiss"
+            # setVariables defines a list of variables to set from the `cmd` standard out.
             setVariables:
               - name: SNAKE_SOUND
-                # You can also mark variables as sensitive to prevent them from being output in the Zarf log
+                # marks this variable as sensitive to prevent it from being output in the Zarf log
                 sensitive: true
+                # autoIndent tells Zarf to maintain spacing for any newlines when templating into a yaml file 
+                autoIndent: true
         # onSuccess will only run if steps in this component are successful
         onSuccess:
-          # this action will have access to the variables set in a previous component
+          # this action will print the CAT_SOUND variable that was set in a previous component
           - cmd: echo "the cat says ${ZARF_VAR_CAT_SOUND}"
-          # this action will have access to the variables set at the top of the zarf.yaml file
+          # this action will print the DOG_SOUND variable set at the top of the zarf.yaml file
           - cmd: echo "the dog says ${ZARF_VAR_DOG_SOUND}"
-          # this action will have access to the variables set within this component
-          # NOTE: when including a variable in a command output this will be written to the log regardless of the sensitive setting
+          # this action will print the SNAKE_SOUND variable set within this component
+          # > NOTE: when including a variable in a command output this will be written to the log regardless of the sensitive setting
           # - use `mute` if you want to silence the command output for sensitive variables
           - cmd: echo "the snake says ${ZARF_VAR_SNAKE_SOUND}"
           # variables are also exposed as TF_VAR_name for terraform, note the lowercase variable name
@@ -147,7 +157,7 @@ components:
           - cmd: echo "😭😭😭 this action failed because it took too long to run 😭😭😭"
 
   - name: on-remove
-    # A manifest so we can test the onRemove action
+    # A manifest that we expect to be removed by Zarf
     manifests:
       - name: test-configmap
         files:
@@ -156,10 +166,10 @@ components:
       # runs during "zarf package remove"
       onRemove:
         before:
-          # because this runs before remove this should be found
+          # because this runs before the manifest is removed this should return our manifest
           - cmd: ./zarf tools kubectl get configmap -n zarf remove-test-configmap || echo "Not Found"
         after:
-          # because this runs after remove this should no longer be found
+          # because this runs after the manifest is removed this should no longer be found
           - cmd: ./zarf tools kubectl get configmap -n zarf remove-test-configmap || echo "Not Found"
 
   - name: on-deploy-with-env-var
@@ -179,6 +189,7 @@ components:
           - description: Cloudflare 1.1.1.1 site to be available
             maxTotalSeconds: 15
             wait:
+              # wait for a network address to return a 200 OK response
               network:
                 protocol: https
                 address: 1.1.1.1
@@ -196,6 +207,7 @@ components:
           - description: The simple-configmap to exist
             maxTotalSeconds: 5
             wait:
+              # wait for the configmap to be available in the cluster
               cluster:
                 kind: configmap
                 name: simple-configmap

examples/dos-games/README.md

@@ -1,6 +1,6 @@
 import ExampleYAML from "@site/src/components/ExampleYAML";
 
-# DOS Games in the Cluster!
+# Retro Arcade
 
 This example provides the basis for Zarf's [Retro Arcade](../../docs/5-zarf-tutorials/3-deploy-a-retro-arcade.md) tutorial.  It deploys a Dos Games arcade into the cluster and provides an easy way to connect and play games.
 

examples/git-data/README.md

@@ -1,6 +1,6 @@
 import ExampleYAML from "@site/src/components/ExampleYAML";
 
-# Git Data
+# Git Repositories
 
 This example shows how to package `git` repositories within a Zarf package.  This package does not deploy anything itself but pushes assets to the specified `git` service to be consumed as desired.  Within Zarf, there are a few ways to include `git` repositories (as described below).
 

examples/kiwix/README.md

@@ -0,0 +1,26 @@
+import ExampleYAML from "@site/src/components/ExampleYAML";
+
+# Data Injections (Kiwix)
+
+This example shows Zarf's ability to inject data into a container running in a pod, in this case to initialize a [Kiwix server](https://www.kiwix.org/en/) to allow offline viewing of documentation and wiki pages.
+
+
+Data injections allow for data that is not included in the container image to be injected at deploy time and are declared using the `dataInjections` key within a component.  Once the specified container is started, Zarf will copy the files and folders from the specified source into the specified container and path.
+
+:::caution
+
+Data injections depend on the `tar` (and for `compress`, `gzip`) executables and their implementation across operating systems.  Between macOS and Linux there is general agreement on how these utilities should function, however on Windows you may see issues enabling compression.
+
+To resolve this you can either disable compression or use the GNU core-utils version of `tar` and `gzip`.
+
+:::
+
+## `zarf.yaml` {#zarf.yaml}
+
+:::info
+
+To view the example in its entirety, select the `Edit this page` link below the article and select the parent folder.
+
+:::
+
+<ExampleYAML example="kiwix" showLink={false} />