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.
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.
Here's what you'll do in this example:
Before the magic can happen you have to do a few things:
-
Install Docker. Other container engines will likely work as well but aren't actively tested by the Zarf team.
-
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.
-
Clone the Zarf project — for the example configuration files.
-
Download a Zarf release — you need a binary and an init package, here.
-
(Optional) Log
zarfinto 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. -
(Optional) Put
zarfon your path — technically optional but makes running commands simpler. Make sure you are picking the right binary that matches your system architecture.zarffor x86 Linux,zarf-mac-intelfor x86 MacOS,zarf-mac-applefor M1 MacOS.
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 clusterThis 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 initFollow 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 logginga 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 initreturns an error like this:ERROR: Unable to find the package on the local system, expected package at zarf-init-<arch>.tar.zstIt's likely you've either forgotten to download
zarf-init-<arch>.tar.zst(as part of getting ready) OR you are not runningzarf initfrom 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, thenkind 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.
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/game # directory with zarf.yaml, and
zarf package create --confirm # make the packageWatch 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.
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 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—where the game package & zarf binary already are—deploying the game is very simple:
zarf package deploy ./zarf-package-appliance-demo-multi-games-<arch>.tar.zst --confirmIn a couple seconds the cluster will have loaded your package.
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)!
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 clusterIt 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.
✨ Special thanks to these fine references! ✨