Using Zarf to Deploy a Podinfo-Flux Application in a Kubernetes Cluster

In this tutorial, we will use the open-source tool Zarf to deploy a Podinfo with Flux application to a Kubernetes cluster.

Prerequisites:

• Basic Kubernetes knowledge
• kubectl installed
• git installed

Objectives:

• Discuss Zarf and its benefits
• Install Zarf CLI
• Discuss the flow of Zarf in an internet-connected environment
• Clone the Zarf repository
• Install the Zarf ‘init’ package
• Create a Zarf package containing a Podinfo-Flux application
• Deploy the Zarf Podinfo-Flux package to a Kubernetes cluster
• Test connectivity to pods with kubectl port-forward
• Zarf connect to Gitea

What is Zarf?

Zarf is an open-source tool created to support easier deployment of software packages, particularly in air-gap or disconnected environments. Although Zarf was designed to solve the challenge of deploying software with little or no internet connectivity, it can also be used to deploy software in connected environments. The benefits of using Zarf, especially in highly-regulated government and non-government industries, are that it simplifies the creation of a Kubernetes cluster if one does not already exist, enables cluster logging, and automates SBOM creation.

Spin up a Kubernetes Cluster

If you already have a Kubernetes cluster running, skip to the “Install Zarf” section.

Linux OS

Zarf has the ability to create a k3s Kubernetes cluster on a Linux machine. If you look at the source code for the Zarf cluster creation, you will see that the k3s component is specifically for a Linux operating system, and it requires root access. If you are running a Linux machine and run the command zarf init you will be prompted to deploy the k3s component (if you are not on a Linux machine, you will not be prompted). When asked “Deploy the k3s component? (y/N)” type “Yes”.

This will create a k3s Kubernetes cluster for you. For more details on this process, see the official Zarf documentation here.

Non-Linux OS

For a non-Linux machine without a cluster running, use the Kubernetes distribution of your choice to spin up a simple cluster. If you have k3d installed, you can spin up a cluster with the following command:

k3d cluster create <cluster_name>

Confirm your cluster creation using the following command:

kubectl config get-contexts

Install Zarf CLI

If the Zarf CLI is already installed, skip to the next section.

Zarf CLI installation instructions can be found here and if you’re working on a Mac with Homebrew installed, you can use the following commands:

brew tap defenseunicorns/tap
brew install zarf

By installing the Zarf CLI, we can now use zarf commands. Once installation is complete, check the version with:

zarf version

Zarf Flow in Connected Environments

Zarf can be used in internet-connected environments and disconnected environments, and the flow of commands is slightly different for each. This tutorial is deploying a software application in an internet-connected environment, so the steps of deployment will be one less than if we were working with an air-gap environment. In this tutorial, we will use Zarf to deploy the podinfo-flux example found at zarf/examples/podinfo-flux. Our flow will look like this:

Clone the Zarf Repository

To work with Zarf, you need access to the Zarf ‘init’ package, which can be found at the root of the Zarf repository. Use the following command to clone the Zarf repository to your local machine:

git clone https://github.com/defenseunicorns/zarf

Take note of the zarf.yaml file (we’ll look at this closer in the next section).

Install the Zarf Init Package

One of the first steps to using Zarf is installing the Zarf ‘init’ package. For detailed information about the Zarf ‘init’ package, visit the official documentation here. The Zarf ‘init’ package is defined in the zarf.yaml file found at the root of the Zarf repository we cloned in the previous section. Let’s take a look at the zarf.yaml file:

This zarf.yaml file defines the seven core components that make up the Zarf ‘init’ package:

• k3s
• zarf-injector
• zarf-seed-registry
• zarf-registry
• zarf-agent
• logging
• git-server

Note that each component imports from a path of the Zarf GitHub repo. Feel free to explore the repo and the packages directory to see the various zarf.yaml files that define the components. You don’t necessarily need to know exactly what each of these components does to use Zarf. However, if you’re interested to learn more about each component, visit the official Zarf ‘init’ documentation here.

Now that we know a little but about the Zarf ‘init’ package, let’s install it. First, make sure you are in the root of the Zarf repository you cloned:

Then run the following command:

zarf init

You will be given a few prompts. The first will be “Deploy this Zarf package?” Type “Yes”.

The next will be “Deploy the logging component?” This is optional so you can choose “Yes” or “No”, but I’ve selected “No”.

The third will be “Deploy the git-server component?” I’ve selected “Yes” for this, as it adds Gitea into the cluster, allowing for GitOps source control.

Once the Zarf ‘init’ package has completed deployment, you will see something like this:

Save this Username and Password information somewhere like a notepad or temporary file. We may use them later. To check that the Zarf ‘init’ package was successfully installed, run the following command:

zarf package list

Great! The init package is there, so now we can move on to creating our Podinfo-Flux application package.

Create Podinfo-Flux Application Package with Zarf

The overall purpose of this tutorial is to demonstrate how to use Zarf to deploy a package on a Kubernetes cluster. The package can be anything, but the Zarf documentation has an entire folder of example applications to work with. One of those examples is the podinfo-flux application, and this is the one we will be deploying.

Podinfo is a small web application written in Go that is often used for end-to-end testing. Flux is a Cloud Native Computing Foundation (CNCF) graduated project that allows you to incorporate GitOps into your Kubernetes cluster. Basically, Flux reconciles the state of your cluster to the desired state defined in a Git repository. Flux monitors the repository, so when changes are made to the source code in the repo, Flux detects these changes, and reconciles the state of the cluster accordingly. Regardless of what Podinfo and Flux do, the point is we will deploy them with Zarf.

On your local machine, navigate to:

zarf/examples/podinfo-flux

Take a look at the files comprising the application.

The flux-install.yaml file consists of an installation manifest generated by Flux, and should not be edited.

The podinfo-kustomization.yaml file instructs Flux to apply customizations from the ./kustomize directory of the Podinfo Git repository to the Podinfo namespace every 5 minutes.

The podinfo-source.yaml file defines the source of the Git repo for Flux to watch and reconcile against (https://github.com/stefanprodan/podinfo.git).

The zarf.yaml file tells the cluster to first deploy Flux via the flux-install.yaml manifest, then deploy Podinfo via the podinfo-source.yaml and podinfo-kustomization.yaml files.

Now that we’ve reviewed the source code for our package, let’s create it. Use the following command:

zarf package create .

The above command takes all of your source code files in the current working directory (don’t forget the period), and bundles them into a single tarball file, known as the Zarf package.

You will be prompted “Create this Zarf package?” Answer “Yes”.

You will then be asked “Please provide a value for Maximum Package Size”. This prompt is useful in a situation where your tarball package size matters (ex. you have limited disk space). For this tutorial, our package will be small so you can simply press Enter and it will bypass this question. You should see the Flux and Podinfo components loading.

Now if you look at your files in your current directory again, you will see a new tarball file has been created.

Deploy Podinfo-Flux Application Package with Zarf

We’re in the home stretch guys, but first let’s do a quick recap. We cloned the Zarf repo to your local directory. We installed the Zarf ‘init’ package. We then created a Podinfo-Flux application package with Zarf, and we are now ready to deploy our application to our Kubernetes cluster. Use the following command to deploy:

zarf package deploy

Upon running this command, you will be prompted to “Choose or type the package file”. If you only have a single tarball file in the current directory, you can simply hit the Tab button and the file’s name will pop in. Then you can press Enter. Alternatively, you can manually type the name of your Zarf package tarball file.

You will then be prompted “Deploy this Zarf package?” Answer “Yes”.

You know your package is deployed when you see the green “Zarf deployment complete”. If you have K9s installed, you could also open a new terminal window and see your Flux and Podinfo components there. If you don’t have K9s installed, open a new terminal window and run the following command for Zarf to open K9s for you:

zarf tools monitor

In the K9s window, you can see Flux and Podinfo pods running in your cluster. Back in your original terminal, use the following command to see all Zarf packages currently installed on your Kubernetes cluster:

zarf package list

Interact with Podinfo

At this point, we appear to have used Zarf to successfully deploy Podinfo and Flux on our Kubernetes cluster. If you looked at the source code before deployment, you may have noticed that a few namespaces were created when our application was deployed. You are likely in the default namespace currently, so if you were to run kubectl get pods you would not see any pods running:

To see all of the pods in all of the namespaces, use:

kubectl get pods -A

To interact with our Podinfo pods, let’s change to the podinfo namespace:

kubectl config set-context --current --namespace=podinfo

Then run kubectl get pods again.

Now we can see our two Podinfo pods up and running. Let’s see if we can access one of the pods from our local machine using a port-forward. If you’re not familiar with kubectl port-forward , check out this article.

kubectl port-forward pod/<pod_name> <local_port>:9898

Replace <pod_name> with the name of one of your Podinfo pods, and <local_port> with a port of your choosing. I chose 3005.

With the port-forward command, we are mapping our local port 3005 to the default Podinfo port of 9898. We can find the default Podinfo port in the Podinfo source code here:

Now that our port-forward tunnel is running, open a browser of your choosing and go to http://localhost:3005 where you should be met with the Podinfo landing page.

If you are met with an adorable clapping purple sea creature, congratulations! If you’re met with an error, make sure your web browser didn’t automatically reroute you to HTTPS instead of HTTP.

After you’ve had your full share of clapping from the purple guy, go back to your terminal and stop the port-forward with ctrl + c .

Zarf Connect to Gitea

At the beginning of the tutorial, in the “Install the Zarf Init Package” section, we answered “Yes” to the “Deploy the git-server component?” prompt. Zarf uses the Gitea git-server component as a GitOps-compatible source control service. To log into the Gitea server for the Zarf package you created, run the following command:

zarf connect git

This will open a port-forward on your local machine:

As well as a new browser window to the Gitea login screen:

Go find the Usernames and Passwords we saved earlier.

Back on the Gitea website, click the Sign In button in the top right, and use the Username and Password for the “Git” application to log in.

After logging in, you should see a version-control interface, similar to GitHub. We won’t dive further into this, but hopefully you can see how Zarf has some optional built-in tools that make CI/CD easier.

Conclusion and CleanUp

In this tutorial, we used the open-source tool Zarf to deploy a Podinfo-Flux application to a Kubernetes cluster. Although this was done in an internet-connected environment, the beauty of Zarf is that with just a few additional steps, you can use it to deploy application packages in secure air-gap or disconnected environments.

Zarf makes it easy to destroy everything you built with a single command. If you want to watch resources being destroyed, either pull up your K9s terminal or open a new terminal and run zarf tools monitor again to use the K9s component built into Zarf. Then run:

zarf destroy --confirm --remove-components

Now just sit back and watch Zarf tear everything down.

Note that my podinfo and flux-system namespaces have disappeared. If you run kubectl get pods -A you will find that your Podinfo, Flux and Zarf pods have all been destroyed and are no longer running. If you run zarf package list you will see that you no longer have any Zarf packages deployed on your cluster.

Use the following command to delete the k3d cluster you created:

k3d cluster delete <cluster_name>

The last thing to clean up is the tarball file from your local directory.

Run the following command:

rm <tarball_file_name>

That’s all the clean up you should have to do. I hope you found this tutorial useful and easy to follow. Thank you so much for reading and keep watching for more DevOps tutorials!