prerequisites
Check a cluster against the prerequisites a Zarf package declares.
Include it as colonel_byte.zarf.prerequisites.
Added in colonel_byte.zarf 0.33.0.
Reads a colonel-byte.dev/v1alpha1 PackagePrerequisites document out of a package’s documentation layer, reads the cluster with colonel_byte.zarf.zarf_cluster_info, and fails the play when the cluster does not satisfy the document.
This is the check that belongs in front of colonel_byte.zarf.zarf_package_deploy. A workload package deployed onto a cluster whose GitOps engine is absent is accepted, reported as a success, and never reconciled; the point of the document is to turn that into a refusal.
Supply the package in zarf_package and the role extracts its document, or supply the document directly in zarf_prerequisites for a package that carries none.
Sets the zarf_prerequisites_document, zarf_prerequisites_checked, zarf_prerequisites_unmet, and zarf_prerequisites_skipped facts. A package carrying no document is not a failure: nothing is checked and zarf_prerequisites_checked is empty.
requires.storage.accessModes is reported in zarf_prerequisites_skipped rather than checked. What a provisioner will bind is not discoverable without creating a PersistentVolumeClaim, and a check that cannot be made is better named than quietly passed.
Every task carries run_once: true and delegates to zarf_delegate_to.
Variables
| Variable | Type | Default | Description |
|---|---|---|---|
zarf_package | str | "" | The package whose prerequisites are checked: a path to a staged tarball, an oci:// reference, or a deployed package name. Not required when zarf_prerequisites supplies the document directly. |
zarf_prerequisites | dict | {} | A prerequisites document supplied directly, instead of being read out of a package. For a bundle whose requirements are known to the playbook rather than to the packages in it, or a package built before the format existed. When set, zarf_package is not inspected. |
zarf_public_key | str | "" | Path to the public key the package’s signature is verified against. |
zarf_verify | str | "" | When to verify the package signature. Left empty, the role requires a signature when zarf_public_key names a key, and leaves zarf’s own if-possible default alone when it does not. Set it explicitly to override. One of ``, never, if-possible, always. |
zarf_kubeconfig | str | "" | Path to the kubeconfig file the cluster is read through. |
zarf_binary | str | zarf | Path to the zarf binary on the delegated host. |
zarf_check_packages | bool | true | Whether to check requires.packages against the cluster’s deployed packages. It is the one check that needs a second query, and zarf package list needs an initialised cluster, so it can be turned off for a run that has not initialised one yet. |
zarf_prerequisites_enforce | bool | true | Whether an unsatisfied prerequisite fails the play. Set it false to report rather than enforce: every check still runs and zarf_prerequisites_unmet still lists what failed, and the play continues. That is what a survey across a fleet of clusters wants, and what a deployment does not. |
zarf_quiet | bool | true | Whether to suppress verbose assert output when asserting inputs. |
zarf_delegate_to | str | localhost | The node on which to run zarf. |
zarf_engine_namespaces | dict | argocd: argocd<br>fluxcd: flux-system | Where each GitOps engine installs itself, as a mapping of the engine key under requires to a namespace. It is the namespace a requires.controllers entry that names none is checked in. A mapping rather than two literals because the defaults are conventions: Flux can be installed outside flux-system and Argo CD outside argocd, and a fleet that does so would otherwise repeat the namespace on every controller of every document. An engine not named here is reported in zarf_prerequisites_skipped rather than guessed at, so a document naming an engine this role does not know never reports a check it did not make. |