FAQ

Who is behind this project?

Zarf was built by the developers at Defense Unicorns and an amazing community of contributors.

Defense Unicorns’ mission is to advance freedom and independence globally through Free and Open Source software.

What license is Zarf under?

Zarf is under the Apache License 2.0. This is one of the most commonly used licenses for open-source software.

Is Zarf free to use?

Yes! Zarf is Free and Open-Source Software (FOSS). And will remain free forever. We believe Free and Open Source software changes the world and promotes freedom and security. Anyone who sees the value in our tool should be free to use it without fear of vendor locking or licensing fees.

Do I have to use Homebrew to install Zarf?

No, the Zarf binary and init package can be downloaded from the Releases Page. Zarf does not need to be installed or available to all users on the system, but it does need to be executable for the current user (i.e. chmod +x zarf for Linux/Mac).

What dependencies does Zarf have?

Zarf is statically compiled and written in Go and Rust, so it has no external dependencies. For Linux, Zarf can bring a Kubernetes cluster using K3s. For Mac and Windows, Zarf can leverage any available local or remote cluster the user has access to. Currently, the K3s installation Zarf performs does require a Systemd based system and root (not just sudo) access.

How can I improve the speed of loading large images from Docker on zarf package create?

Due to some limitations with how Docker provides access to local image layers, zarf package create has to rely on docker save under the hood which is very slow overall and also takes a long time to report progress. We experimented with many ways to improve this, but for now recommend leveraging a local docker registry to speed up the process.

This can be done by running a local registry and pushing the images to it before running zarf package create. This will allow zarf package create to pull the images from the local registry instead of Docker. This can also be combined with component actions and --registry-override to make the process automatic. Given an example image of registry.enterprise.corp/my-giant-image:v2 you could do something like this:

# Create a local registry
docker run -d -p 5000:5000 --restart=always --name registry registry:2

# Run the package create with a tag variable
zarf package create --registry-override registry.enterprise.corp=localhost:5000 --set IMG=my-giant-image:v2

kind: ZarfPackageConfig
metadata:
  name: giant-image-example

components:
  - name: main
    actions:
      # runs during "zarf package create"
      onCreate:
        # runs before the component is created
        before:
          - cmd: "docker tag registry.enterprise.corp/###ZARF_PKG_TMPL_IMG### localhost:5000/###ZARF_PKG_TMPL_IMG###"
          - cmd: "docker push localhost:5000/###ZARF_PKG_TMPL_IMG###"

    images:
      - "registry.enterprise.corp/###ZARF_PKG_TMPL_IMG###"

Can I pull in more than http(s) git repos on zarf package create?

Under the hood, Zarf uses go-git to perform git operations, but it can fallback to git located on the host and thus supports any of the git protocols available. All you need to use a different protocol is to specify the full URL for that particular repo:

Note

In order for the fallback to work correctly you must have git version 2.14 or later in your path.

kind: ZarfPackageConfig
metadata:
  name: repo-schemes-example

components:
  repos:
    - https://github.com/zarf-dev/zarf.git
    - ssh://git@github.com/zarf-dev/zarf.git
    - file:///home/zarf/workspace/zarf
    - git://somegithost.com/zarf.git

In the airgap, Zarf with rewrite these URLs to match the scheme and host of the provided airgap git server.

Note

When specifying other schemes in Zarf you must change the consuming side as well since Zarf will add a CRC hash of the URL to the repo name on the airgap side. This is to reduce the chance for collisions between repos with similar names. This means an example Flux GitRepository specification would look like this for the file:// based pull:

---
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 30s
  ref:
    tag: 6.1.6
  url: file:///home/zarf/workspace/podinfo

What is YOLO Mode and why would I use it?

YOLO Mode is a special package metadata designation that be added to a package prior to zarf package create to allow the package to be installed without the need for a zarf init operation. In most cases this will not be used, but it can be useful for testing or for environments that manage their own registries and Git servers completely outside of Zarf. This can also be used as a way to transition slowly to using Zarf without having to do a full migration.

Note

Typically you should not deploy a Zarf package in YOLO mode if the cluster has already been initialized with Zarf. This could lead to an ImagePullBackOff if the resources in the package do not include the zarf.dev/agent: ignore label and are not already available in the Zarf Registry.

What is a skeleton Zarf Package?

A skeleton package is a bare-bones Zarf package definition alongside its associated local files and manifests that has been published to an OCI registry. These packages are intended for use with component composability to provide versioned imports for components that you wish to mix and match or modify with merge-overrides across multiple separate packages.

Skeleton packages have not been run through the zarf package create process yet, and thus do not have any remote resources included (no images, repos, or remote manifests and files) thereby retaining any create-time package configuration templates as they were defined in the original zarf.yaml (i.e. untemplated).

Skeleton packages are published by pointing the publish command to a directory rather than a tarball, e.g. zarf package publish my-package/