Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update "Get Started" docs to be clearer about requirement for zarf-init.tar.zst #127

Merged
merged 5 commits into from
Oct 27, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/workstation.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,17 +17,17 @@ The simplest path to Zarf is to download a pre-built release and execute it on y

1. Download:

1. The appropriate zarf binary for your system (choose _one_):
- The zarf cluster initialization package: `zarf-init.tar.zst`.

- The appropriate zarf binary for your system (choose _one_):

| system | binary |
| --- | --- |
| Linux (64bit) | `zarf` |
| Intel-based Mac | `zarf-mac-intel` |
| [Apple-based Mac](https://support.apple.com/en-us/HT211814) | `zarf-mac-apple` |

1. The zarf cluster initialization package: `zarf-init.tar.zst`.

1. (optional) The checksum file: `zarf.sha256`.
- (optional) The checksum file: `zarf.sha256`.

1. (optional) Verify integrity of the downloaded files by validating their hashes—more about that ( [here](https://en.wikipedia.org/wiki/Checksum) / [here](https://help.ubuntu.com/community/HowToSHA256SUM) ) if you're interested. From _the directory holding your files_, run:

Expand Down
25 changes: 18 additions & 7 deletions examples/game/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-installed Kubernetes 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**_
>
Expand Down Expand Up @@ -46,9 +46,9 @@ Before the magic can happen you have to do a few things:

1. Clone the Zarf project — for the example configuration files.

1. Download a Zarf release — link & instructions [here](../../docs/workstation.md#just-gimmie-zarf).
1. Download a Zarf release — you need a binary _**and**_ an init package, [here](../../docs/workstation.md#just-gimmie-zarf).

1. Log `zarf` into [Iron Bank](../../docs/ironbank.md#2-configure-zarf-the-use-em)—if you haven't already.
1. Log `zarf` into Iron Bank if you haven't already — instructions [here](../../docs/ironbank.md#2-configure-zarf-the-use-em).

1. Put `zarf` on your path — _technically_ optional but makes running commands simpler.

Expand All @@ -61,20 +61,31 @@ Before the magic can happen you have to do a few things:
<img align="right" alt="asciicast" src="https://asciinema.org/a/444679.svg?x-scenario=examples-game-scripted" height="256" />
</a>

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&mdash;the "Zarf cluster". Kick that off by running this command:
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&mdash;the "Zarf 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
```

Answer the follow-on prompts as appropriate for your machine configuration & give it a few seconds to run.

Congratulations! Your machine is now "a cluster".
Congratulations! Your machine is now a single node k8s cluster!

> _**Note**_
>
> Zarf supports fire-and-forget installs too! Give `zarf init --help` a call for more details on that.

> _**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
> 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.

&nbsp;


Expand All @@ -84,7 +95,7 @@ Congratulations! Your machine is now "a cluster".
<img align="right" alt="asciicast" src="https://asciinema.org/a/444679.svg?x-scenario=examples-game-scripted" height="256" />
</a>

Zarf is (at heart) a tool for making it easy to get software from _where you have it_ to _**where you need it**_&mdash;specifically, across an airgap. Since moving bits is so core to Zarf, this idea of a "ready-to-move group of software" has a specific name: the _package_.
Zarf is (at heart) a tool for making it easy to get software from _where you have it_ to _**where you need it**_&mdash;specifically, across an airgap. Since moving bits is so core to Zarf the idea of a "ready-to-move group of software" has a specific name&mdash;the _package_.

All of the software a Zarf cluster runs is installed via package&mdash;for many reasons like versioning, auditability, etc&mdash;which means that if you want to run _**Doom**_ in your cluster you're going to have to build a package for it.

Expand All @@ -110,7 +121,7 @@ It's time to feed the package you built into your cluster.

> _**Note**_
>
> If you were an evil genius trying to get _**Doom**_ to run in your internet-isolated, evil underground super-base _this_ is where you would burn the zarf binary + game package to removable media for shipment "across the airgap"... probably via evil FedEx.
> If you were an evil genius trying to get _**Doom**_ to run in your internet-isolated, evil underground super-base _this_ is where you would burn the zarf release + game package to removable media for shipment "across the airgap"... probably via evil FedEx.

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:

Expand Down