zarf_package_deploy
Deploy a zarf package onto an initialised cluster.
Write it as colonel_byte.zarf.zarf_package_deploy. It runs zarf on the node the task is delegated to; nothing is installed on the cluster’s nodes.
Added in colonel_byte.zarf 0.0.1.
Runs zarf package deploy against the cluster a kubeconfig names, and follows the deployment component by component.
The module is a compiled binary with zarf linked into it. It renders the zarf package deploy command line from these parameters, executes zarf’s own command in its own process, reads the component boundaries back out of zarf’s log stream, and reports one JSON result. It needs no zarf on the node.
It is the companion of colonel_byte.zarf.zarf_init. A cluster whose init package has no StorageClass to claim cannot finish initialising until a storage provider is deployed, and the provider cannot be deployed until the cluster is initialised far enough to hold it, so a playbook alternates between the two.
Parameters
| Parameter | Type | Required | Flag | Description |
|---|---|---|---|---|
package | str | yes | None | The package to deploy: a path to a tarball, an oci:// reference, or an https:// URL. A relative path is resolved against the working directory the module was invoked from unless directory names one, because that directory belongs to Ansible rather than to the operator. The positional argument of the command, so it renders no flag. |
directory | str | no | None | The working directory to run zarf in. A relative package is resolved against it. |
kubeconfig | str | no | None | The kubeconfig of the cluster to deploy onto. Zarf has no --kubeconfig flag, so it is passed as KUBECONFIG in zarf’s environment. |
zarf_config | str | no | None | A zarf config file, passed as ZARF_CONFIG. It is how a playbook keeps credentials out of the argument vector. |
wrapper_binary | str | no | None | The module wrapper to run, resolved on the path when it holds no separator. The action plugin consumes this parameter; the wrapper never sees it. |
status_file | str | no | None | Where the wrapper writes live component progress. The action plugin creates a private temporary file and overrides this. |
parameters | dict | no | None | Further module parameters, merged into the ones given directly. A parameter given both directly and inside parameters is an error naming it. The action plugin consumes this key; the wrapper never sees it. |
components | str | no | --components | Which components to deploy, as a comma-separated list. It is also what lets the progress display report component 2/4 rather than component 2: the wrapper cannot otherwise know how many components the package holds. |
namespace | str | no | --namespace | Deploy into this namespace instead of the one the package names. Alpha in zarf. |
shasum | str | no | --shasum | The SHA256 checksum of a package fetched over https://. |
connected | bool | no | --connected | Whether to deploy without pushing the package’s images and repositories, for a cluster that can already reach them. |
take_ownership | bool | no | --take-ownership | Whether zarf adopts Kubernetes resources that already exist. |
force_conflicts | bool | no | --force-conflicts | Whether zarf forces Helm ownership during server-side apply. |
skip_values_schema_validation | bool | no | --skip-values-schema-validation | Whether zarf skips validating values files against their schema. |
insecure_skip_tls_verify | bool | no | --insecure-skip-tls-verify | Whether zarf skips verifying TLS certificates it connects to. |
plain_http | bool | no | --plain-http | Whether zarf talks to OCI registries over plain HTTP. |
retries | int | no | --retries | How many times zarf retries a failed operation. |
oci_concurrency | int | no | --oci-concurrency | How many OCI operations zarf runs at once. |
architecture | str | no | --architecture | The architecture of the package being deployed. |
cache | str | no | --cache | Zarf’s cache directory. |
tmpdir | str | no | --tmpdir | The directory zarf unpacks the package into. |
timeout | str | no | --timeout | How long zarf waits for a Helm operation or health check, as a Go duration such as 15m. |
public_key | str | no | --key | The public key the package signature is verified against. |
verify | str | no | --verify | When to verify the package signature. One of never, if-possible, always. |
values | list of str | no | --values | Values files to apply, one flag per entry. |
set_values | dict | no | --set-values | Values to set, as a mapping. Rendered one flag per entry, sorted, so the same parameters always render the same command line. |
set_variables | dict | no | --set-variables | Zarf variables to set, as a mapping. |
log_level | str | no | --log-level | Zarf’s log level. |
log_format | str | no | --log-format | Zarf’s log format. Defaults to json, which is the format the component progress is read out of. |
Notes
- Set
run_once: trueanddelegate_toon the task. One deploy puts the package on the whole cluster, so a play over the cluster’s own inventory would otherwise deploy it once per host. - Set
no_log: trueon the task when any parameter carries a credential. A binary module has no per-parameterno_log. - Check mode reports the task as skipped.
zarf package deployhas no dry run, so there is nothing honest to report instead. - A parameter left unset renders no flag, so whatever zarf’s own config file sets still applies.
- The zarf that does the work is the one linked into the module, and its version is reported as
zarf.version, so a failed run says which zarf produced it. There is no installed version to be too old.
Example
- name: Deploy a storage provider so the registry has a StorageClass to claim
colonel_byte.zarf.zarf_package_deploy:
package: oci://ghcr.io/colonel-byte/zarf/csi-local-path-provider:0.0.37-upstream
components: local-path-images,local-path-chart
kubeconfig: /etc/rancher/rke2/rke2.yaml
public_key: /etc/zarf/colonel-byte-zarf-packages.pub
verify: always
delegate_to: localhost
run_once: true
- name: Deploy a staged package
colonel_byte.zarf.zarf_package_deploy:
package: /srv/staging/zarf-package-monitoring-amd64.tar.zst
kubeconfig: /etc/rancher/rke2/rke2.yaml
set_variables:
DOMAIN: bubbles.test
delegate_to: localhost
run_once: true
no_log: true
register: deploy_result
- name: Report which components the package deployed
ansible.builtin.debug:
var: deploy_result.zarf.componentsRan