zarf_package_pull
Fetch a zarf package to disk.
Write it as colonel_byte.zarf.zarf_package_pull. 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.88.0.
Runs zarf package pull to fetch a package from an oci:// registry or an https:// URL and write it to a directory as a tarball.
The module is a compiled binary with zarf linked into it. It renders the zarf package pull command line from these parameters, executes zarf’s own command in its own process, and reports one JSON result. It needs no zarf on the node.
It is the staging half of an air-gapped workflow: a connected node fetches the package, something carries the file through the airlock, and colonel_byte.zarf.zarf_package_deploy reads it from the path it landed at. Nothing it does reaches a cluster.
Parameters
| Parameter | Type | Required | Flag | Description |
|---|---|---|---|---|
package | str | yes | None | The package to fetch: an oci:// reference or an https:// URL. The positional argument of the command, so it renders no flag. |
output_directory | str | no | --output-directory | The directory the tarball is written to. Zarf defaults it to the working directory, which under Ansible is whichever directory the module was invoked from, so a playbook that cares where the package lands says so. |
shasum | str | no | --shasum | The SHA256 checksum of the package. Zarf requires it for a package fetched over https:// rather than merely accepting it. |
zarf_config | str | no | None | A zarf config file, passed as ZARF_CONFIG. It is how a playbook keeps registry 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. |
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. |
oci_concurrency | int | no | --oci-concurrency | How many OCI operations zarf runs at once. |
architecture | str | no | --architecture | The architecture of the package to fetch, for a reference that publishes more than one. |
cache | str | no | --cache | Zarf’s cache directory. |
tmpdir | str | no | --tmpdir | The directory zarf unpacks into while it works. |
plain_http | bool | no | --plain-http | Whether zarf talks to OCI registries over plain HTTP. |
insecure_skip_tls_verify | bool | no | --insecure-skip-tls-verify | Whether zarf skips verifying TLS certificates it connects to. |
log_level | str | no | --log-level | Zarf’s log level. |
log_format | str | no | --log-format | Zarf’s log format. Defaults to json. |
Notes
- Set
run_once: trueanddelegate_toon the task. The package is fetched once, to the node holding the staging directory. changedis an observation here rather than a convention: the task reports changed only when the pull left a package file the output directory did not already hold, withzarf.changedSignalset tocompleteand the filenames inzarf.packagesPulled. Zarf derives the filename from the package’s own metadata, so that list is how a playbook learns what to deploy.- Check mode reports the task as skipped.
zarf package pullhas no dry run. - A
packagethat is a local path is refused: there is nothing to fetch. Use the path directly withcolonel_byte.zarf.zarf_package_deploy. - A parameter left unset renders no flag, so whatever zarf’s own config file sets still applies.
Example
- name: Stage a package for the airlock
colonel_byte.zarf.zarf_package_pull:
package: oci://ghcr.io/colonel-byte/zarf/csi-local-path-provider:0.0.37-upstream
output_directory: /srv/staging
delegate_to: localhost
run_once: true
register: pull_result
- name: Deploy what was staged
colonel_byte.zarf.zarf_package_deploy:
package: "/srv/staging/{{ pull_result.zarf.packagesPulled | first }}"
kubeconfig: /etc/rancher/rke2/rke2.yaml
delegate_to: localhost
run_once: true
when: pull_result.zarf.packagesPulled | length > 0