Skip to content

Latest commit

 

History

History
167 lines (92 loc) · 6.52 KB

README.md

File metadata and controls

167 lines (92 loc) · 6.52 KB
Raw

Zarf Composable Packages Example

This example demonstrates using Zarf to compose existing zarf packages into another package.

More specifically, you'll be running the zarf game example by simply adding an import and path in the new zarf.yaml.

Note

In this example there is no "GitOps" service—Zarf is only showing off it's ability to act as a standard means of packaging, distribution, and runtime.

 

The Flow

Here's what you'll do in this example:

  1. Get ready

  2. Create a cluster

  3. Package the game

  4. Deploy it

  5. Space marine the demon invasion!

  6. Cleanup

 

Get ready

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

  1. Install Docker. Other container engines will likely work as well but aren't actively tested by the Zarf team.

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

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

  4. Download a Zarf release — you need a binary and an init package, here.

  5. (Optional) Log zarf into Iron Bank if you haven't already — instructions here. 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.

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

 

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:

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

cd <same dir as zarf-init-<arch>.tar.zst>
zarf init

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 running a single-node Kubernetes cluster powered by Zarf!

Note

Zarf supports non-interactive installs too! Give zarf init --confirm --components logging a try next time.

Troubleshooting:

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:

ERROR:  Unable to find the package on the local system, expected package at zarf-init-<arch>.tar.zst

It's likely you've either forgotten to download zarf-init-<arch>.tar.zst (as part of getting 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.

 

Package the Composed Example

Zarf is (at heart) a tool for making it easy to get software from where you have it to where you need it—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—the package.

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

Luckily, this is very easy to do—package contents are defined by simple, declarative yaml files and we've already made one for you. To build the game package you simply:

cd <zarf dir>/examples/composable-packages    # directory with zarf.yaml, and
zarf package create --confirm   # 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.

 

Deploy it

It's time to feed the package you built into your cluster.

zarf package deploy ./zarf-package-compose-example-<arch>.tar.zst --confirm

In a couple seconds the cluster will have loaded your package.

 

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.

Once you see the ultra-iconic title screen, you're ready to go (save the world)!

game

 

Cleanup

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—you just tear down the entire cluster:

kind delete cluster

It only takes a couple moments for the entire cluster to disappear—long-running system services and all—leaving your machine ready for the next adventure.

 

 

Credits

✨ Special thanks to these fine references! ✨