zarf_package_documentation
Extract and parse the documentation a Zarf package carries.
Write it as colonel_byte.zarf.zarf_package_documentation. 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.33.0.
Runs zarf package inspect documentation against a local package tarball, an oci:// reference, or a deployed package name, and returns the extracted files.
Zarf packages every file named in its zarf.yaml’s top-level documentation: mapping into a documentation layer, which this module extracts without deploying anything.
Each extracted file is returned as text in documents, keyed by its documentation key, and parsed into parsed when it is YAML or JSON. A file that is neither is returned as text only, rather than failing the task.
The prerequisites key is the one this collection has a format for. When the package carries one and it declares apiVersion: colonel-byte.dev/v1alpha1 and kind: PackagePrerequisites, it is also returned as prerequisites; see the prerequisites role, which checks a cluster against it.
Signature verification is zarf’s if-possible unless verify says otherwise, so an unsigned package extracts cleanly even when public_key is given.
Runs on the node the task is delegated to (typically localhost).
Parameters
| Parameter | Type | Required | Flag | Description |
|---|---|---|---|---|
package | str | yes | None | Path to a local package tarball, an oci:// reference, an https:// URL, or a deployed package name. |
keys | list of str | no | --keys | The documentation keys to extract. Left unset, every key the package carries is extracted. Naming a key the package does not carry is not an error: zarf extracts what it has, and the key is simply absent from documents. |
destination | path | no | --output | Directory to extract into. Zarf creates a <package-name>-documentation subdirectory of it, and directory reports the subdirectory it created. Left unset, a temporary directory is used and removed before the task returns. |
public_key | path | no | --key | Path to the public key a package signature is verified against. Supplying it does not by itself require a signature: zarf verifies when it can and passes an unsigned package otherwise. Set verify: always to reject one. |
verify | str | no | --verify | When to verify the package signature. Left unset, zarf’s own default applies, which is if-possible. One of never, if-possible, always. |
kubeconfig | path | no | None | Path to the kubeconfig file, used when extracting from a package already deployed to a cluster. |
zarf_binary | path | no | None | Path to the zarf CLI binary on the delegated host. When omitted, zarf on PATH is used. |
Notes
- Set
run_once: trueanddelegate_to: localhoston the task. - The module runs in check mode and reports
changed: false. It writes files, but only the ones it extracts, and only underdestinationor a temporary directory of its own - nothing on the cluster or in the package changes. - Left unset,
destinationis a temporary directory that is removed before the task returns, sofilesnames paths that no longer exist. Set it when a later task has to read a file rather than its contents.
Example
- name: Read the prerequisites a package declares
colonel_byte.zarf.zarf_package_documentation:
package: /srv/staging/zarf-package-operator-external-secrets-amd64-2.12.0.tar.zst
keys:
- prerequisites
public_key: /etc/zarf/colonel-byte-zarf-packages.pub
verify: always
delegate_to: localhost
run_once: true
register: pkg_docs
- name: Report the Flux version the package requires
ansible.builtin.debug:
msg: "{{ pkg_docs.prerequisites.metadata.package }} requires Flux {{ pkg_docs.prerequisites.requires.fluxcd.version }}"
when: pkg_docs.prerequisites.requires.fluxcd is defined
- name: Keep the extracted documentation for a later task to read
colonel_byte.zarf.zarf_package_documentation:
package: oci://ghcr.io/colonel-byte/packages/app-fluxcd:2.9.5
destination: /srv/staging/documentation
delegate_to: localhost
run_once: true
register: pkg_docs
- name: Show where it landed
ansible.builtin.debug:
msg: "{{ pkg_docs.directory }} holds {{ pkg_docs.files | dict2items | map(attribute='value') | list | join(', ') }}"