Skip to content

Commit

Permalink
Multi-Distro Support - Update Docs (#289)
Browse files Browse the repository at this point in the history
  • Loading branch information
@RothAndrew @jeff-mccoy
RothAndrew authored and jeff-mccoy committed Feb 8, 2022
1 parent f668e0e commit a378468
Show file tree
Hide file tree
Showing 5 changed files with 67 additions and 103 deletions.
36 changes: 20 additions & 16 deletions docs/workstation.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
# Workstation Setup

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

 


## 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:
Expand Down Expand Up @@ -52,24 +51,30 @@ chmod +x ./zarf && ./zarf help
# substitute ./zarf-mac-intel or ./zarf-mac-apple above, as appropriate
```

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

You'll know everything is installed correctly when you see the Zarf axolotl scroll through your terminal!
## 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.

There are lots of ways to get a sandbox environment, here's two of them:
## I want a demo/example sandbox
### Kubernetes-In-Docker (KinD)
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.
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.

### Install
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
```
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.

You'll need to install _these_ tools to run the examples:
### Vagrant

You'll need to install _these_ tools to run the examples if you want to use Vagrant:
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.
Expand All @@ -91,12 +96,11 @@ You'll need to install _these_ tools to run the examples:
### 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/) 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/README.md) 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:
Expand All @@ -105,7 +109,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 recommended version is `1.16.x`.
Currently required version is `1.16.x`.

&nbsp;

Expand Down
78 changes: 36 additions & 42 deletions examples/game/README.md
View file
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 (k8s) cluster&mdash;_right on your local machine_.
More specifically, you'll be running a copy of the 1993, mega-hit video game _**Doom**_ in a Zarf-enabled Kubernetes (k8s) cluster&mdash;_right on your local machine_.

> _**Note**_
>
Expand Down Expand Up @@ -36,47 +36,64 @@ Here's what you'll do in this example:

Before the magic can happen you have to do a few things:

1. Get a "root" shell &mdash; `zarf` needs power to install stuff / bind ports / etc.
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. Clone the Zarf project &mdash; for the example configuration files.

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

1. Log `zarf` into Iron Bank if you haven't already &mdash; instructions [here](../../docs/ironbank.md#2-configure-zarf-the-use-em).
1. (Optional) Log `zarf` into Iron Bank if you haven't already &mdash; 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. Put `zarf` on your path &mdash; _technically_ optional but makes running commands simpler.
1. (Optional) Put `zarf` on your path &mdash; _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.

&nbsp;


## 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:

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".
```sh
kind create cluster
```

Kick that off by _moving into the directory with your init package_ and running this command:
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.

```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.
Follow the prompts, answering "no" to each of the optional components, since we don't need them for this deployment.

Congratulations! Your machine is now a single node k8s cluster!
Congratulations! Your machine is now running a single-node Kubernetes cluster powered by Zarf!

> _**Note**_
>
> Zarf supports fire-and-forget installs too! Give `zarf init --help` a call for more details on that.
> Zarf supports non-interactive installs too! Give `zarf init --confirm --components logging` a try next time.
**Troubleshooting:**

> _**Error &mdash; missing or unreadable package**_
> _**ERROR: Unable to find the package on the local system, expected package at zarf-init.tar.zst**_
>
> 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
> ERROR: Unable to find the package on the local system, expected package at 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;
Expand All @@ -91,10 +108,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 # make the package
zarf package create --confirm # make the 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.
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;
Expand All @@ -111,46 +128,23 @@ 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 deploy ./zarf-package-appliance-demo-multi-games.tar.zst --confirm
```
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.
In a couple seconds the cluster will have loaded your package.
&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.
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".
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.
Once you see the ultra-iconic title screen, you're ready to go (save the world)!
&nbsp;
> _**Note**_
>
> The images / steps described here are for Chrome but all major, modern browsers will have a similar security mechanism and associated workaround.
![game](img/game.png)
&nbsp;
## Cleanup
Expand All @@ -159,10 +153,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
zarf destroy
kind delete cluster
```
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.
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.
&nbsp;
Expand Down
56 changes: 11 additions & 45 deletions examples/game/add-logging.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,13 @@
# Zarf Components - Add Logging

This example demonstrates using a [Zarf component](./components.md) to inject zero-config, centralized logging into your Zarf cluster.
This example demonstrates using a Zarf component 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.

&nbsp;


## 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)
Expand All @@ -32,27 +27,18 @@ 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) again but _**don't** do the cleanup step_ &mdash; you're setup correctly once you can pull the game up in your browser.
1. Run through the [Zarf game example](./README.md) but stop when you're told to run `zarf init`

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:
Expand All @@ -66,17 +52,12 @@ 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.
Expand All @@ -85,29 +66,22 @@ 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:

```sh
WARN[0026] Credentials stored in ~/.git-credentials Gitea Username (if installed)=zarf-git-user Grafana Username=zarf-admin Password (all)="AbCDe0fGH12IJklMnOPQRSt~uVWx"
```
![logging-creds](./img/logging-creds.png)

Pull out the `Grafana Username` and `Password (all)` values & save them for later.
The ones under "Logging" are what you'll need.

&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

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

Doing that sends a bunch of HTTP traffic into the cluster & should give you something worth looking at in Grafana.

Expand All @@ -116,19 +90,15 @@ 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 navigating your browser to: `https://localhost/monitor/explore`.
Get started by opening Grafana using `zarf connect logging`

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 you will be redirected back to:
Once you've successfully logged in go to:

1. the `monitor/explore` page, where
1. The "Explore" page (Button on the left that looks like a compass)

1. you can select `Loki` in the dropdown, and then

Expand All @@ -141,16 +111,12 @@ 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
zarf destroy --confirm
kind delete cluster
```

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.
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.
Binary file added examples/game/img/game.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added examples/game/img/logging-creds.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit a378468

Please sign in to comment.