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 a git server and K3s 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`

Zarf deploys resources in Kubernetes using Helm’s Go SDK, and converts manifests into Helm charts for installation.

If no existing Helm releases match a given chart in the cluster, Zarf executes a helm install.

Should matching releases exist, a helm upgrade is performed.

By default, Zarf waits for all resources to deploy successfully during install, upgrade, and rollback operations.

You can override this behavior during install and upgrade by setting the noWait: true key under the charts and manifests fields.

After the Helm wait completes successfully, Zarf waits for all resources in the applied chart to fully reconcile. To identify when reconciliation is achieved, Zarf uses kstatus. Kstatus assesses whether a resource is reconciled by checking the status field. If a resource does not have a status field, kstatus considers it reconciled once it’s found.

The default timeout for Helm operations in Zarf is 15 minutes.

Use the --timeout flag with zarf init and zarf package deploy to modify the timeout duration.

Zarf retries install and upgrade operations up to three times by default if an error occurs.

Use the --retries flag with zarf init and zarf package deploy to change the number of retry attempts.

If attempts to upgrade a chart fail, Zarf tries to roll the chart back to its last successful release. During this rollback process:

  • Any resources created during the failed upgrade attempt are deleted (helm rollback --cleanup-on-fail)
  • Resource updates are forced through delete and recreate if needed (helm rollback --force)