deploy_packages
Deploy a list of Zarf packages to a cluster with component-level drift detection.
Include it as colonel_byte.zarf.deploy_packages.
Added in colonel_byte.zarf 0.31.0.
Iterates over a list of Zarf packages to deploy, inspecting each package definition and checking installed cluster components before deploying.
An item that names components is skipped when every one of them is already deployed on the cluster at the same package version, and no excluded component is. An item that names none is always deployed: the role compares component names, and with none to compare it has nothing to go on.
Skipping settles for a package that one item deploys. It does not settle for a package that several items deploy in phases, because zarf package list reports only the most recent deploy’s components – so each phase sees the other’s and both re-deploy every run. That reconciles rather than fails; see the choice-deploy-packages-drift-scope page in the book.
When deployment is executed, invokes zarf_init for packages of type init, or zarf_package_deploy for standard packages. Both verify the package against zarf_public_key when one is named.
Optionally writes deployment results as JSON files to zarf_result_dir, refreshes the zarf_packages fact once the stack is deployed, and sets zarf_deploy_packages_changed to whether any item reached zarf.
Every task carries run_once: true and delegates to zarf_delegate_to.
Variables
| Variable | Type | Default | Description |
|---|---|---|---|
zarf_packages_to_deploy | list of dict | [] | The list of packages to deploy. Each item is a dictionary specifying package deployment parameters. path: (required) Path to the Zarf package tarball or OCI source. package_type: Type of deployment. Set to init to invoke zarf_init, or package / deploy (default: package) to invoke zarf_package_deploy. components: List of component names to deploy. Prefix with - to exclude (e.g. -git-server). Naming them is also what lets the item be skipped. Left unset, zarf chooses the components itself – every non-optional one, plus any optional one marked default, resolved per package API version – and the role does not work out what that set would be, so the item is deployed every run. set_variables: Dictionary of template variable overrides passed as --set key=val. kubeconfig: Kubeconfig path override for this package. public_key: Public key path override for signature verification. verify: Verification mode override (never, if-possible, always). timeout: Timeout override for this package deployment. wrapper_binary: Wrapper binary override for this package. registry_mode: Registry mode override for init packages (nodeport, proxy, external). connected: Whether the cluster pulls the package’s images itself rather than zarf pushing them. Overrides zarf_connected, and applies to non-init packages only. take_ownership: Whether zarf adopts cluster resources it did not create. Overrides zarf_take_ownership. force_conflicts: Whether zarf overrides a server-side-apply conflict. Overrides zarf_force_conflicts. log_level: Zarf log level for this package (e.g. warn, info, debug, trace). Overrides zarf_log_level. log_dest: Destination file path to write deployment result JSON. Overrides the name the role would build under zarf_result_dir. delegate_to: Host override on which this package operation runs. zarf_binary: Path to zarf binary override for this package. |
zarf_kubeconfig | str | "" | Default path to the kubeconfig file used to reach the cluster. Can be overridden per package item. |
zarf_public_key | str | "" | Default path to the public key used to verify package signatures. Can be overridden per package item. |
zarf_verify | str | "" | When to verify package signatures. Left empty, requires a signature if zarf_public_key is specified. One of ``, never, if-possible, always. |
zarf_timeout | str | "" | Default timeout duration for package deployment tasks (e.g. 15m, 1h). Can be overridden per package item. |
zarf_init_wrapper | str | "" | Default wrapper binary path for zarf_init tasks. |
zarf_deploy_wrapper | str | "" | Default wrapper binary path for zarf_package_deploy tasks. |
zarf_result_dir | str | "" | Directory where deployment result logs are written as JSON. If empty, result files are not written unless log_dest is set on the package item. The name inside it is the item’s position in the stack, then the package’s file name without its extension – 1-zarf-init-amd64-v0.88.0.json. The position leads it because the package does not identify the item: a bundle names the same init package twice, and a name built from the package alone would have the second step overwrite the first step’s result. |
zarf_log_level | str | "" | Default Zarf log level (e.g. warn, info, debug, trace). Left empty, zarf’s own default applies. Can be overridden per package item. |
zarf_take_ownership | str | "" | Whether zarf adopts cluster resources it did not create, which Helm otherwise refuses to do. Can be overridden per package item. Left empty, zarf’s own default applies. Empty is the third state a boolean does not have: it is what distinguishes a stack that said nothing from one that said false. One of ``, true, false. |
zarf_force_conflicts | str | "" | Whether zarf overrides a server-side-apply conflict rather than failing on it. Can be overridden per package item. Left empty, zarf’s own default applies. Turning it on means the deploy takes fields another controller owns, so it is stated by whoever is deploying rather than assumed by this role. One of ``, true, false. |
zarf_registry_mode | str | "" | How zarf reaches the registry an init package stands up. Can be overridden per package item, and applies to init packages only. Left empty, zarf’s own default applies. One of ``, nodeport, proxy, external. |
zarf_connected | str | "" | Whether the cluster pulls a package’s images itself rather than zarf pushing them to the registry. Can be overridden per package item, and applies to non-init packages only. A connected deploy needs no registry, so it is the one deploy that works on a cluster nothing has initialised – which is what lets a storage provider be deployed before the initialisation that claims a volume from it. Left empty, zarf’s own default applies. One of ``, true, false. |
zarf_binary | str | zarf | Path to the zarf binary on the delegated host. |
zarf_delegate_to | str | localhost | The node on which to execute inspection and deployment tasks. |