Revert "Multi-Distro Support - Update Docs (#289)"

This reverts commit a378468.

docs/workstation.md

@@ -1,9 +1,10 @@
 # Workstation Setup
 
-There are several ways to use Zarf & the tooling needed depends on what you plan to do with it.  Here are some of the most common use cases, along with what you'll need to install on your workstation to play along.
+There are several ways to use Zarf & the tooling needed depends on what plan to do with it.  Here are some of the most common use cases, along with what you'll need to install on your workstation to play along.
 
  
 
+
 ## Just gimmie Zarf!
 
 The simplest path to Zarf is to download a pre-built release and execute it on your shell (just like any other CLI tool). To do that:
@@ -51,30 +52,24 @@ chmod +x ./zarf && ./zarf help
 # substitute ./zarf-mac-intel or ./zarf-mac-apple above, as appropriate
 ```
 
- 
-
-## I want a demo/example sandbox
-
-If you're looking for an easy & low-risk way to evaluate Zarf, our recommendation is to pop into the `examples` folder.  Because the demos _aren't_ intended to be long-lived and _are_ expected to clean up after themselves they are a perfect way to kick the tires.
+> _**Take note**_
+>
+> Commands run this way _will_ make changes to your current system / environment!
+>
+>This is the expected usage pattern for production but for demonstration / development & test there are better, **virtual machine**-isolated ways to run Zarf. Keep reading to find out how to get setup for those!
 
-There are lots of ways to get a sandbox environment, here's two of them:
+You'll know everything is installed correctly when you see the Zarf axolotl scroll through your terminal!
 
-### Kubernetes-In-Docker (KinD)
-
-1. Install [Docker](https://docs.docker.com/get-docker/). Other container engines will likely work as well but aren't actively tested by the Zarf team.
+ 
 
-1. Install [KinD](https://github.com/kubernetes-sigs/kind). Other Kubernetes distros will work as well, but we'll be using KinD for this example since it is easy and tested frequently and thoroughly.
 
-1. Run
-   ```sh
-   kind create cluster
-   ```
+## I want a demo/example sandbox
 
-That's it! You should now have a Kubernetes cluster running in Docker for use. Run `kind delete cluster` to clean up when you are done.
+If you're looking for an easy & low-risk way to evaluate Zarf, our recommendation is to pop into the `examples` folder.  Because the demos _aren't_ intended to be long-lived and _are_ expected to clean up after themselves they've been wrapped into **virtual-machine (VM)**-isolated environments for easy setup & teardown.
 
-### Vagrant
+### Install
 
-You'll need to install _these_ tools to run the examples if you want to use Vagrant:
+You'll need to install _these_ tools to run the examples:
 
 1. [Virtualbox ](https://www.virtualbox.org/wiki/Downloads) — The [hypervisor](https://www.redhat.com/en/topics/virtualization/what-is-a-hypervisor) we use to run our example VMs.
 
@@ -96,11 +91,12 @@ You'll need to install _these_ tools to run the examples if you want to use Vagr
 
 ### Try it out
 
-Once you've got everything installed you're ready to run some examples! We recommend giving the [Get Started - game](../examples/game/README.md) example a try!
+Once you've got everything installed you're ready to run some examples! We recommend giving the [Get Started - game](../examples/game/) example a try!
 <!-- update link once Get Started page is written! -->
 
 &nbsp;
 
+
 ## I need a dev machine
 
 During dev & test, Zarf gets its exercise the same way the examples do&mdash;inside a VM.  Getting setup for development means that you'll need to install:
@@ -109,7 +105,7 @@ During dev & test, Zarf gets its exercise the same way the examples do&mdash;ins
 
 1. [Go](https://golang.org/doc/install) &mdash; the programming language / build tools we use to create the `zarf` (et al.) binary.
 
-    Currently required version is `1.16.x`.
+    Currently recommended version is `1.16.x`.
 
 &nbsp;
 

examples/game/README.md

@@ -2,7 +2,7 @@
 
 This example demonstrates using Zarf to kill time (and evil).
 
-More specifically, you'll be running a copy of the 1993, mega-hit video game _**Doom**_ in a Zarf-enabled Kubernetes (k8s) cluster—_right on your local machine_.
+More specifically, you'll be running a copy of the 1993, mega-hit video game _**Doom**_ in a Zarf-installed Kubernetes (k8s) cluster—_right on your local machine_.
 
 > _**Note**_
 >
@@ -36,64 +36,47 @@ Here's what you'll do in this example:
 
 Before the magic can happen you have to do a few things:
 
-1. Install [Docker](https://docs.docker.com/get-docker/). Other container engines will likely work as well but aren't actively tested by the Zarf team.
-
-1. Install [KinD](https://github.com/kubernetes-sigs/kind). Other Kubernetes distros will work as well, but we'll be using KinD for this example since it is easy and tested frequently and thoroughly.
+1. Get a "root" shell — `zarf` needs power to install stuff / bind ports / etc.
 
 1. Clone the Zarf project — for the example configuration files.
 
 1. Download a Zarf release — you need a binary _**and**_ an init package, [here](../../docs/workstation.md#just-gimmie-zarf).
 
-1. (Optional) Log `zarf` into Iron Bank if you haven't already — instructions [here](../../docs/ironbank.md#2-configure-zarf-the-use-em). Optional for this specific example since the container comes from GitHub rather than Iron Bank but a good practice and needed for most of the other examples.
+1. Log `zarf` into Iron Bank if you haven't already — instructions [here](../../docs/ironbank.md#2-configure-zarf-the-use-em).
 
-1. (Optional) Put `zarf` on your path — _technically_ optional but makes running commands simpler. Make sure you are picking the right binary that matches your system architecture. `zarf` for x86 Linux, `zarf-mac-intel` for x86 MacOS, `zarf-mac-apple` for M1 MacOS.
+1. Put `zarf` on your path — _technically_ optional but makes running commands simpler.
 
  
 
 
 ## Create a cluster
 
-You can't run software without _somewhere to run it_, so the first thing to do is create a local Kubernetes cluster that Zarf can deploy to. In this example we'll be using KinD to create a lightweight, local K8s cluster running in Docker.
-
-Kick that off by running this command:
 
-```sh
-kind create cluster
-```
+You can't run software without _somewhere to run it_, so the first thing to do is have `zarf` install & run a new, local k8s cluster—the "Zarf cluster".
 
-This will result in a single-node Kubernetes cluster called `kind-kind` on your local machine running in Docker. Your KUBECONFIG should be automatically configured to talk to the new cluster.
+Kick that off by _moving into the directory with your init package_ and running this command:
 
 ```sh
 cd <same dir as zarf-init.tar.zst>
 zarf init
 ```
 
-Follow the prompts, answering "no" to each of the optional components, since we don't need them for this deployment.
+Answer the follow-on prompts as appropriate for your machine configuration & give it a few seconds to run.
 
-Congratulations!  Your machine is now running a single-node Kubernetes cluster powered by Zarf!
+Congratulations!  Your machine is now a single node k8s cluster!
 
  > _**Note**_
  >
- > Zarf supports non-interactive installs too! Give `zarf init --confirm --components logging` a try next time.
-
-**Troubleshooting:**
+ > Zarf supports fire-and-forget installs too! Give `zarf init --help` a call for more details on that.
 
-> _**ERROR:  Unable to find the package on the local system, expected package at zarf-init.tar.zst**_
+> _**Error &mdash; missing or unreadable package**_
 >
 > The zarf binary needs an init package to know how to setup your cluster! So, if `zarf init` returns an error like this:
 > ```sh
-> ERROR:  Unable to find the package on the local system, expected package at zarf-init.tar.zst
+> FATA[0004] The package archive seems to be missing or unreadable.  archive=zarf-init.tar.zst
 > ```
 > It's likely you've either forgotten to download `zarf-init.tar.zst` (as part of [getting ready](#get-ready)) _**OR**_ you are _not_ running `zarf init` from the directory the init package is sitting in.
 
-> _**ERROR: failed to create cluster: node(s) already exist for a cluster with the name "kind"**_
->
-> You already have a KinD cluster running. Either just move on to use the current cluster, or run `kind delete cluster`, then `kind create cluster`.
-
-> _**Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?**_
->
-> Docker isn't running or you're otherwise not able to talk to it. Check your Docker installation, then try again.
-
 &nbsp;
 
 
@@ -108,10 +91,10 @@ Luckily, this is very easy to do&mdash;package contents are defined by simple, d
 
 ```sh
 cd <zarf dir>/examples/game     # directory with zarf.yaml, and
-zarf package create --confirm   # make the package
+zarf package create             # make the package
 ```
 
-Watch the terminal scroll for a while. Once things are downloaded & zipped up and you'll see a file ending in `.tar.zst` drop.  _That's_ your package.
+Answer the questions & watch the terminal scroll for a while. Once things are downloaded & zipped up and you'll see a file ending in `.tar.zst` drop.  _That's_ your package.
 
 &nbsp;
 
@@ -128,23 +111,46 @@ It's time to feed the package you built into your cluster.
 Since you're running a Zarf cluster directly on your local machine&mdash;where the game package & `zarf` binary _already are_&mdash;deploying the game is very simple:
 
 ```sh
-zarf package deploy ./zarf-package-appliance-demo-multi-games.tar.zst --confirm
+zarf package deploy
 ```
 
-In a couple seconds the cluster will have loaded your package.
+Respond as appropriate and in a couple seconds the cluster will have loaded your package.
+
+> _**Important**_
+>
+> It's possible to try a package deploy _before the Zarf cluster is ready to receive it_. If you see an error like `"https://<cluster ip>/v2/": dial tcp ,<cluster ip>:443: connect: connection refused;` then it's very likely that you've beat the Zarf startup routines.
+>
+> The fix is simple: just wait for the cluster to finish starting & try again.
 
 &nbsp;
 
+
 ## Space marine the demon invasion!
 
-After the deploy has completed, a prompt would have displayed the new connect commands you can use to connect automatically bring up the game in your browser. Running the command `zarf connect games` should open your browser to `http://localhost:<SOME_PORT>` and be greeted by a short catalog of games to play. Run `zarf connect doom` to directly open the _**Doom**_ game. We use `zarf connect` here so we can connect to it in a browser without needing a Kubernetes Ingress Controller, which is a more advanced topic and has different configurations depending on which controller and which distribution of Kubernetes you are using.
+After the deploy has completed, a prompt would have displayed the new connect commands you can use to connect automatically bring up the game in your browser. Running the command `zarf connect games` should open your browser to `http://localhost:<SOME_PORT>` and be greeted by a short catalog of games to play. 
+
+If you're running in a vagrant virtual machine you might notice this command does not work, this is because the networking of the Vagrant vm clashes with the networking of the kubernetes cluster. In this case you will have to manually create a tunnel to the game. You can do that by running the following set of commands:
+  - `kubectl get pods -n default`
+    - This will return a pod starting with `game-#####-####`. Copy this name to be used in the next command.
+  - kubectl port-forward -n default --address 0.0.0.0 {COPIED_POD_NAME} 8000:8000
+    - This will enable you to now go to `127.0.0.1:8000` on your host machine to play the games!
+
+
+### It begins!
+
+Give the example a couple of seconds to "boot up".
 
 Once you see the ultra-iconic title screen, you're ready to go (save the world)!
 
-![game](img/game.png)
+&nbsp;
+
+> _**Note**_
+>
+> The images / steps described here are for Chrome but all major, modern browsers will have a similar security mechanism and associated workaround.
 
 &nbsp;
 
+
 ## Cleanup
 
 
@@ -153,10 +159,10 @@ Once you've had your fun it's time to clean up.
 In this case, since the Zarf cluster was installed specifically (and _only_) to serve this example, clean up is really easy&mdash;you just tear down the entire cluster:
 
 ```sh
-kind delete cluster
+zarf destroy
 ```
 
-It only takes a couple moments for the _entire cluster_ to disappear&mdash;long-running system services and all&mdash;leaving your machine ready for the next adventure.
+It only takes a couple moments for the _entire Zarf cluster_ to disappear&mdash;long-running system services and all&mdash;leaving your machine ready for the next adventure.
 
 &nbsp;
 

examples/game/add-logging.md

@@ -1,13 +1,18 @@
 # Zarf Components - Add Logging
 
-This example demonstrates using a Zarf component to inject zero-config, centralized logging into your Zarf cluster.
+This example demonstrates using a [Zarf component](./components.md) to inject zero-config, centralized logging into your Zarf cluster.
 
 More specifically, you'll be adding a [Promtail / Loki / Grafana (PLG)](https://github.com/grafana/loki) stack to the example game cluster by installing Zarf's "logging" component.
 
  
 
+
 ## The Flow
 
+<a href="https://asciinema.org/a/446956?x-scenario=examples-game-logging&autoplay=1">
+<img align="right" alt="asciicast" src="https://asciinema.org/a/446956.svg?x-scenario=examples-game-logging" height="320" />
+</a>
+
 Here's what you'll do in this example:
 
 1. [Get ready](#get-ready)
@@ -27,18 +32,27 @@ Here's what you'll do in this example:
 
 ## Get ready
 
+<a href="https://asciinema.org/a/446956?x-scenario=examples-game-logging&t=1">
+<img align="right" alt="asciicast" src="https://asciinema.org/a/446956.svg?x-scenario=examples-game-logging" height="256" />
+</a>
+
 This scenario builds upon the previous one, so:
 
-1. Run through the [Zarf game example](./README.md) but stop when you're told to run `zarf init`
+1. Run through the [Zarf game example](./README.md) again but _**don't** do the cleanup step_ &mdash; you're setup correctly once you can pull the game up in your browser.
 
-1. Take a deep breath&mdash;because it's good for your body&mdash;and read on!
+1. Take a deep breath&mdash;because it's good for your body&mdash;and  read on!
 
 &nbsp;
 
 &nbsp;
 
+
 ## Install the logging component
 
+<a href="https://asciinema.org/a/446956?x-scenario=examples-game-logging&t=19">
+<img align="right" alt="asciicast" src="https://asciinema.org/a/446956.svg?x-scenario=examples-game-logging" height="256" />
+</a>
+
 Installing a Zarf component is _really_ easy&mdash;you just have to let `zarf init` know that you want use it.  That's it!
 
 Exactly like when you first created the game example cluster, you _move into the directory holding your init package_ and run:
@@ -52,12 +66,17 @@ You can answer the follow-on prompts in almost the exact same way as during your
 
 Give it some time for the new logging pods to come up and you're ready to go!
 
+ > _**Note**_
+ >
+ > You can install components as part of new cluster installs too (obviously)&mdash;there's no need to update afterward if you already know you need a component.
+
  > _**Note**_
  >
  > Zarf supports non-interactive installs too! See `zarf init --help` for how to make that work.
 
 &nbsp;
 
+
 ## Note the credentials
 
 Go back to your terminal and review the `zarf init` command output&mdash;the very last thing printed should be a set of credentials Zarf has generated for you.
@@ -66,22 +85,29 @@ Pay attention to these because you're going to need them to log into your shiny,
 
 The line you want will look something like this:
 
-![logging-creds](./img/logging-creds.png)
+```sh
+WARN[0026] Credentials stored in ~/.git-credentials      Gitea Username (if installed)=zarf-git-user Grafana Username=zarf-admin Password (all)="AbCDe0fGH12IJklMnOPQRSt~uVWx"
+```
 
-The ones under "Logging" are what you'll need.
+Pull out the `Grafana Username` and `Password (all)` values & save them for later.
 
 &nbsp;
 
 
 ## Check the logs
 
+<a href="https://asciinema.org/a/446956?x-scenario=examples-game-logging&t=55">
+<img align="right" alt="asciicast" src="https://asciinema.org/a/446956.svg?x-scenario=examples-game-logging" height="256" />
+</a>
+
 We've only _just_ installed the logging utilities so we (likely) haven't had time to record anything interesting. Since log aggregation & monitoring aren't worth much without something to collect, let's get some data in there.
 
 &nbsp;
 
+
 ### Generate some traffic
 
-Deploy the Game example again, then pull up the game in your brower&mdash;_[instructions here](./README.md#space-marine-the-demon-invasion), in case you forgot how_&mdash;and then reload the browser window a few times.
+Pull up the game in your brower&mdash;_[instructions here](./README.md#space-marine-the-demon-invasion), in case you forgot how_&mdash;and then reload the browser window a few times.
 
 Doing that sends a bunch of HTTP traffic into the cluster & should give you something worth looking at in Grafana.
 
@@ -90,15 +116,19 @@ Doing that sends a bunch of HTTP traffic into the cluster & should give you some
 
 ### Get into Grafana
 
+<a href="../../.images/get-started/plg.png">
+<img align="right" alt="dosbox" src="../../.images/get-started/plg.png" height="160" />
+</a>
+
 Now that you've got some logs worth looking at, you're ready to log into your brand new Grafana instance.
 
-Get started by opening Grafana using `zarf connect logging`
+Get started by navigating your browser to: `https://localhost/monitor/explore`.
 
 You'll be redirected the `/login` page where you have to sign in with the Grafana credentials you saved [in a previous step](#note-the-credentials).
 
-Once you've successfully logged in go to:
+Once you've successfully logged in you will be redirected back to:
 
-1. The "Explore" page (Button on the left that looks like a compass)
+1. the `monitor/explore` page, where
 
 1. you can select `Loki` in the dropdown, and then
 
@@ -111,12 +141,16 @@ Submit that query and you'll get back a dump of all the game pod logs that Loki
 
 ## Cleanup
 
+<a href="https://asciinema.org/a/446956?x-scenario=examples-game-logging&t=88">
+<img align="right" alt="asciicast" src="https://asciinema.org/a/446956.svg?x-scenario=examples-game-logging" height="256" />
+</a>
+
 Once you've had your fun it's time to clean up.
 
 In this case, since the Zarf cluster was installed specifically (and _only_) to serve this example, clean up is really easy&mdash;you just tear down the entire cluster:
 
 ```sh
-kind delete cluster
+zarf destroy --confirm
 ```
 
-It takes just a couple moments for the _entire cluster_ to disappear&mdash;long-running system services and all&mdash;leaving your machine squeaky clean.
+It takes just a couple moments for the _entire Zarf cluster_ to disappear&mdash;long-running system services and all&mdash;leaving your machine squeaky clean.