Skip to content
Zarf

Deploy a Package

Zarf CLI + Zarf Init + Zarf Package

A typical Zarf deployment is made up of three parts:

  1. 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).
  2. 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.
  3. 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.

Zarf Packages are designed to be easily deployable on a variety of systems, including air-gapped systems. All of the necessary dependencies are included within the package, eliminating the need for outbound internet connectivity. When deploying the package onto a cluster, the dependencies contained in each component are automatically pushed into a Docker registry and/or Git server created by or known to Zarf on the air-gapped system.

Once the Zarf package has arrived in your target environment, run the zarf package deploy command to deploy the package onto your Zarf initialized cluster. This command deploys the package’s capabilities into the target environment, including all external resources required for the package. The zarf.yaml file included in the package will be used to orchestrate the deployment of the application according to the instructions provided.

The following diagram shows the order of operations for the zarf package deploy command and the hook locations for actions.

Lifecycle Diagram
graph TD B1(load package archive)-->B2 B2(handle multipart package)-->B3 B3(extract archive to temp dir)-->B4 B4(validate package checksums and signature)-->B5 B5(filter components by architecture & OS)-->B6 B6(save SBOM files to current dir)-->B7 B7(handle deprecations and breaking changes)-->B9 B9(confirm package deploy):::prompt-->B10 B10(process deploy-time variables)-->B11 B11(prompt for missing variables)-->B12 B12(prompt to confirm components)-->B13 B13(prompt to choose components in '.group')-->B14 subgraph "" B14(deploy each component)-->B14 B14 --> B15(run each '.actions.onDeploy.before'):::action-->B15 B15 --> B16(copy '.files')-->B17 B17(load Zarf State)-->B18 B18(push '.images')-->B19 B19(push '.repos')-->B20 B20(process '.dataInjections')-->B21 B21(install '.charts')-->B22 B22(apply '.manifests')-->B23 B23(run each '.actions.onDeploy.after'):::action-->B23 B23-->B24{Success?} B24-->|Yes|B25(run each '.actions.onDeploy.success'):::action-->B25 B24-->|No|B26(run each '.actions.onDeploy.failure'):::action-->B26-->B999 B999[Abort]:::fail end B25-->B27(print Zarf connect table) B27-->B28(save package data to cluster) classDef prompt fill:#4adede,color:#000000 classDef action fill:#bd93f9,color:#000000 classDef fail fill:#aa0000

Zarf provides a few options that can provide control over how a deployment of a Zarf Package proceeds in a given environment. These are baked into a Zarf Package by a package creator and include:

  • Package Variables - Templates resources with environment specific values such as domain names or secrets.
  • Optional Components - Allows for components to be optionally chosen when they are needed for a subset of environments.
  • Components Groups - Provides a choice of one component from a defined set of components in the same component group.

Zarf normally expects to operate against a Kubernetes cluster that has been Zarf initialized, but there are additional modes that can be configured by package creators including:

  • YOLO Mode - Yaml-OnLy Online mode allows for a faster deployment without requiring the zarf init command to be run beforehand. It can be useful for testing or for environments that manage their own registries and Git servers completely outside of Zarf. Given this mode does not use the Zarf Agent any resources specified will need to be manually modified for the environment.

  • Cluster-less - Zarf normally interacts with clusters and kubernetes resources, but it is possible to have Zarf perform actions before a cluster exists (including deploying the cluster itself). These packages generally have more dependencies on the host or environment that they run within.

The general flow of a Zarf package deployment on an existing initialized cluster is as follows:

Terminal window
# To deploy a package run the following:
$ zarf package deploy
# - Find and select the package using tab (shows packages from the local system)
# - Review Supply Chain and other pre-deploy information (clicking on the link to view SBOMs)
# - Type "y" to confirm package deployment or "N" to cancel
# - Enter any variables that have not yet been defined
# - Select any optional components that you want to add to the deployment
# - Select any component groups for this deployment


# Once the deployment finishes you can interact with the package
$ zarf connect [service name]
# - Your browser window should open to the service you selected
# - Not all packages define `zarf connect` services
# - You can list those that are available with `zarf connect list`