Overview
What is Zarf?
Zarf was created to support the declarative creation & distribution of software "packages" into remote/constrained/standalone environments.
"Zarf is a tool to help deploy modern stacks into air-gapped environments; it's all about moving the bits." — Jeff
Zarf is a free and open-source tool that simplifies the setup and deployment of applications and supporting resources onto air-gapped or disconnected environments. Zarf equips you with the ability to quickly and securely deploy modern software onto complex systems without relying on internet connectivity.
It also simplifies the installation, update, and maintenance of supporting DevSecOps capabilities like Kubernetes clusters and logging stacks, while providing features that ensure supply chain security, including SBOM compliance. Most importantly though, Zarf keeps applications and systems running even when they are disconnected.
Check out our glossary for an explanation of common terms used in the project.
How Zarf Works
Zarf simplifies and standardizes the delivery of complex software deployments. This gives users the ability to reduce tens/hundreds of individual software updates, data transfers, and manual installations to a few simple terminal commands. This tool equips users with the ability to pull, package, and install all of the resources their applications or clusters need to run without being connected to the internet. It can also deploy any necessary resources needed to stand up infrastructure tooling (such as Open Tofu / Terraform).
A typical Zarf deployment is made up of three parts:
- The
zarf
binary:- Is a statically compiled Go binary that can be run on any machine, server, or operating system with or without connectivity.
- Creates packages combining numerous types of software/updates into a single distributable package (while on a network capable of accessing them).
- Declaratively deploys package contents "into place" for use on production systems (while on an isolated network).
- A Zarf init package:
- A compressed tarball package that contains the configuration needed to instantiate an environment without connectivity.
- Automatically seeds your cluster with a container registry or wires up a pre-existing one
- Provides additional capabilities such as logging, git server support, and/or a K8s cluster.
- A Zarf Package:
- A compressed tarball package that contains all of the files, manifests, source repositories, and images needed to deploy your infrastructure, application, and resources in a disconnected environment.
For more technical information on how Zarf works and to view the Zarf architecture, visit our Nerd Notes page.
Target Use Cases
- Make the delivery of software "across the air gap" an open-source "solved problem".
- Make it trivial to deploy and run Kubernetes apps "at the Edge".
- Make it easy to support GitOps-based K8s cluster updates in isolated environments.
- Make it possible to support GitOps-based K8s cluster updates in internet-connected-but-independent environments (think: dependency caching per availability zone, etc).
What can be Packaged?
The following types of software can be rolled into a Zarf Package:
- Container images + artifacts: to serve images and OCI artifacts for clusters and other consumers to pull.
- Repositories: to serve as the git-based "source of truth" for GitOps application deployments.
- Pre-compiled binaries: to provide the software necessary to start and support a cluster.
- Component actions: to support scripts and commands that run at various stages of the Zarf package create lifecycle, and package deploy lifecycle.
- Helm charts, kustomizations, and other K8s manifests: to apply to a Kubernetes cluster.
- Data injections: to declaratively inject data into running containers in a Kubernetes cluster.
How To Use Zarf
Zarf is intended for use in a software deployment process that looks similar to this:
(0) Connect to the Internet
Zarf doesn't build software—it helps you distribute software that already exists.
Zarf can pull from various places like Docker Hub, Iron Bank, GitHub, private registries and local filesystems. In order to do this, you must ensure that Zarf has a clear path and appropriate access credentials. Be sure you know what you want to pack and how to access it before you begin using Zarf.
(1) Create a Package
This part of the process requires access to the internet (or a network that mirrors your resources). When the zarf
binary is presented with a zarf.yaml
, it then begins downloading, packing, and compressing the software that you requested. It then outputs a single, ready-to-move distributable called "a package".
For additional information, see the Creating a package section.
(2) Ship the Package to the System Location
Zarf enables secure software delivery for various environments, such as remote, constrained, standalone, and air-gapped systems. Considering there are various target environments with their own appropriate transferring mechanisms, Zarf does not determine how packages are moved so long as they can arrive in your downstream environment. See Package Sources for more information on where Zarf packages can be stored / pulled from.
(3) Deploy the Package
Once your package has arrived, you will need to:
- Install the binary onto the system.
- Initialize a cluster with a zarf init package (
zarf init
) - Deploy the package to your cluster (
zarf package deploy
)
Cluster Configuration Options
Zarf allows the package to either deploy to a K3s cluster it creates or an existing K8s cluster. This configuration is available on deployment of the init package.
Initialize k3s
as an Appliance
In the simplest usage scenario, you deploy the Zarf init package's builtin cluster and use it to serve your application(s) directly to end users. This configuration runs Zarf and it's init package components as a self-contained appliance and is intended for use in environments where you want to run K8s-native tooling but need to keep a small footprint (i.e. single-purpose/constrained/"Edge" environments).
Initialize k3s
as a Utility Cluster
In a more complex use case, you deploy the Zarf init package's builtin cluster and use it to serve resources to further downstream clusters. This configuration makes your Zarf deployment a utility cluster in service of a larger system and is intended for use in places where you want to run independent, full-service production environments with their own lifecycles but you want help tracking, caching and disseminating system/dependency updates.
Skip k3s
and Initialize to an Existing Cluster
In this use case, you configure Zarf to initialize a cluster that already exists within your environment, and use that existing cluster to host and serve your applications. This configuration is intended for environments that may already have some supporting infrastructure such as disconnected / highly regulated cloud environments.
Why Use Zarf?
- 💸 Free and Open-Source. Zarf will always be free to use and maintained by the open-source community.
- ⭐️ Zero Dependencies. As a statically compiled binary, the Zarf CLI has zero dependencies to run on any machine.
- 🔓 No Vendor Lock. There is no proprietary software that locks you into using Zarf. If you want to remove it, you still can use your helm charts to deploy your software manually.
- 💻 OS Agnostic. Zarf supports numerous operating systems. A full matrix of supported OSes, architectures and featuresets is coming soon.
- 📦 Highly Distributable. Integrate and deploy software from multiple secure development environments including edge, embedded systems, secure cloud, data centers, and even local environments.
- 🚀 Develop Connected, Deploy Disconnected. Teams can build and configure individual applications or entire DevSecOps environments while connected to the internet. Once created, they can be packaged and shipped to a disconnected environment to be deployed.
- 💿 Single File Deployments. Zarf allows you to package the parts of the internet your app needs into a single compressed file to be installed without connectivity.
- ♻️ Declarative Deployments. Zarf packages define the precise state for your application enabling it to be deployed the same way every time.
- 🦖 Inherit Legacy Code. Zarf packages can wrap legacy code and projects - allowing them to be deployed to modern DevSecOps environments.
Features
📦 Out of the Box Features
- Automate Kubernetes deployments in disconnected environments
- Automate Software Bill of Materials (SBOM) generation
- Build and publish packages as OCI image artifacts
- Provide a web dashboard for viewing SBOM output
- Create and verify package signatures with cosign
- Publish, pull, and deploy packages from an OCI registry
- Powerful component lifecycle actions
- Deploy a new cluster while fully disconnected with K3s or into any existing cluster using a kube config
- Builtin logging stack with Loki
- Builtin Git server with Gitea
- Builtin Docker registry
- Builtin K9s Dashboard for managing a cluster from the terminal
- Mutating Webhook to automatically update Kubernetes pod's image path and pull secrets as well as Flux Git Repository URLs and secret references
- Builtin command to find images and resources from a Helm chart
- Tunneling capability to connect to Kuberenetes resources without network routing, DNS, TLS or Ingress configuration required
🛠️ Configurable Features
- Customizable variables and package templates with defaults and user prompting
- Composable packages to include multiple sub-packages/components
- Component-level OS/architecture filtering
Quick Start
- 💻 Select your system's OS below.
- ❗ Ensure you have the pre-requisite applications running.
$
Enter the commands into your terminal.
- Linux
- macOS
- Windows
This quick start requires you to already have:
For more install options please visit our Getting Started page.
Linux Commands
# To install Zarf
brew tap defenseunicorns/tap && brew install zarf
# Next, you will need a Kubernetes cluster. This example uses KIND.
brew install kind && kind delete cluster && kind create cluster
# Then, you will need to deploy the Zarf Init Package
zarf init
# You are ready to deploy any Zarf Package, try out our Retro Arcade!!
zarf package deploy oci://defenseunicorns/dos-games:1.0.0-$(uname -m) --key=https://zarf.dev/cosign.pub
This example shows how to install Zarf with the official (📜) defenseunicorns
Homebrew tap, however there are many other options to install Zarf on Linux such as:
- 📜 [official] Downloading Zarf directly from GitHub releases
- 🧑🤝🧑 [community]
apk add
on Alpine Linux Edge - 🧑🤝🧑 [community]
asdf install
with the ASDF Version Manager - 🧑🤝🧑 [community]
nix-shell
/nix-env
with Nix Packages
Zarf can deploy it's own k3s
cluster on Linux if you have root
access by selecting the k3s
component on zarf init
.
This quick start requires you to already have:
For more install options please visit our Getting Started page.
MacOS Commands
# To install Zarf
brew tap defenseunicorns/tap && brew install zarf
# Next, you will need a Kubernetes cluster. This example uses KIND.
brew install kind && kind delete cluster && kind create cluster
# Then, you will need to deploy the Zarf Init Package
zarf init
# You are ready to deploy any Zarf Package, try out our Retro Arcade!!
zarf package deploy oci://🦄/dos-games:1.0.0-$(uname -m) --key=https://zarf.dev/cosign.pub
Windows Commands
There is currently no Zarf Quick Start for Windows, though you can learn how to install Zarf from our Github Releases by visiting the Getting Started page
Coming soon!
Zarf is being actively developed by the community. For more information, see our release notes.