init

zarf_init

Initialise a cluster with a staged zarf init package.

Write it as colonel_byte.zarf.zarf_init. 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 init against the cluster a kubeconfig names, and follows the init package’s deployment component by component.

The module is a compiled binary with zarf linked into it. It renders the zarf init command line from these parameters, executes zarf’s own init 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.

This is a proof of ZEP-0072 (https://github.com/zarf-dev/proposals/pull/73), which proposes putting this dispatch inside the zarf binary itself.

Parameters

Parameter	Type	Required	Flag	Description
`init_package`	`str`	no	None	The init package to deploy, such as `/srv/staging/zarf-init-amd64-v0.85.0.tar.zst`. It is passed as the positional package source of `zarf init`, so the file needs no particular name and need not sit in any particular directory. An `oci://` reference or an `https://` URL may be given instead of a path, for a cluster whose packages come from a registry rather than from disk. A directory may also be given, which leaves zarf to find a package inside it the way it does when given no source at all: a file named after zarf’s own version. One of `init_package` or `directory` is required.
`directory`	`str`	no	None	The working directory to run zarf in. A relative `init_package`, and a relative path inside a zarf config file named by `zarf_config`, are resolved against it. May be given together with `init_package`: the package says what to deploy, and this says where relative paths resolve from.
`kubeconfig`	`str`	no	None	The kubeconfig of the cluster to initialise. 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 registry and git credentials out of the argument vector: zarf reads them from the file, so they never reach the process table.
`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, so a task has no reason to set it. It is here for a run reproduced by hand.
`parameters`	`dict`	no	None	Further module parameters, merged into the ones given directly. It is how a role passes a caller-supplied set without templating a whole task’s arguments. 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 init 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.
`storage_class`	`str`	no	`--storage-class`	The storage class the init package’s persistent volumes are created with.
`registry_url`	`str`	no	`--registry-url`	The URL of an external registry to use instead of the one the init package deploys.
`registry_mode`	`str`	no	`--registry-mode`	How zarf uses the registry.
`registry_port`	`int`	no	`--registry-port`	The node port the internal registry is published on.
`registry_secret`	`str`	no	`--registry-secret`	The secret zarf derives registry credentials from.
`registry_push_username`	`str`	no	`--registry-push-username`	The username zarf pushes images with.
`registry_push_password`	`str`	no	`--registry-push-password`	The password zarf pushes images with.
`registry_pull_username`	`str`	no	`--registry-pull-username`	The username the cluster pulls images with.
`registry_pull_password`	`str`	no	`--registry-pull-password`	The password the cluster pulls images with.
`git_url`	`str`	no	`--git-url`	The URL of an external git server to use instead of the one the init package deploys.
`git_push_username`	`str`	no	`--git-push-username`	The username zarf pushes repositories with.
`git_push_password`	`str`	no	`--git-push-password`	The password zarf pushes repositories with.
`git_pull_username`	`str`	no	`--git-pull-username`	The username the cluster pulls repositories with.
`git_pull_password`	`str`	no	`--git-pull-password`	The password the cluster pulls repositories with.
`injector_image`	`str`	no	`--injector-image`	The image the zarf injector runs.
`injector_port`	`int`	no	`--injector-port`	The port the zarf injector listens on.
`agent_mutation_policy`	`str`	no	`--agent-mutation-policy`	Which resources the zarf agent mutates.
`agent_tls_ca`	`str`	no	`--agent-tls-ca`	The certificate authority the zarf agent’s serving certificate is issued by.
`agent_tls_cert`	`str`	no	`--agent-tls-cert`	The zarf agent’s serving certificate.
`agent_tls_key`	`str`	no	`--agent-tls-key`	The private key of the zarf agent’s serving certificate.
`take_ownership`	`bool`	no	`--take-ownership`	Whether zarf takes ownership of resources an earlier install created.
`force_conflicts`	`bool`	no	`--force-conflicts`	Whether zarf forces apply conflicts.
`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 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 init package into.
`timeout`	`str`	no	`--timeout`	How long zarf waits for a Helm operation, as a Go duration such as `30m`.
`public_key`	`str`	no	`--key`	The public key the init package’s signature is verified against.
`verify`	`str`	no	`--verify`	When to verify the init package’s 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. Overriding it costs the progress display its component names, and changes nothing else about the run.

Notes

Set run_once: true and delegate_to on the task. One zarf init initialises the whole cluster, so a play over the cluster’s own inventory would otherwise initialise it once per host.
Set no_log: true on the task. A binary module has no per-parameter no_log, so the task-level setting is what suppresses the arguments and the result.
Check mode reports the task as skipped. zarf init has 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. That is why plain_http: false and omitting plain_http differ.
Credentials given as parameters are rendered as flags, which puts them in the process table for the life of the run. Put them in a zarf config file and name it with zarf_config to keep them out of it.
The zarf that does the work is linked into the module, so there is no version to check and nothing to install. It is reported as zarf.version in the result.

Example

- name: Initialise the cluster
  colonel_byte.zarf.zarf_init:
    init_package: /srv/staging/zarf-init-amd64-v0.85.0.tar.zst
    kubeconfig: /etc/rancher/rke2/rke2.yaml
    storage_class: local-path
    components: zarf-registry,zarf-agent
    timeout: 30m
  delegate_to: localhost
  run_once: true
  no_log: true
  register: init_result

- name: Report which components the init package deployed
  ansible.builtin.debug:
    var: init_result.zarf.componentsRan

- name: Initialise the cluster with credentials zarf reads from its own config file
  colonel_byte.zarf.zarf_init:
    init_package: /srv/staging/zarf-init-amd64-v0.85.0.tar.zst
    kubeconfig: /etc/rancher/rke2/rke2.yaml
    zarf_config: /etc/zarf/zarf-config.yaml
  delegate_to: localhost
  run_once: true
  no_log: true

- name: Initialise the cluster from a custom init package under a name of its own
  colonel_byte.zarf.zarf_init:
    init_package: /srv/staging/our-init-package.tar.zst
    kubeconfig: /etc/rancher/rke2/rke2.yaml
  delegate_to: localhost
  run_once: true
  no_log: true

- name: Initialise the cluster from an init package held in a registry
  colonel_byte.zarf.zarf_init:
    init_package: oci://registry.bubbles.test/zarf/init:v0.85.0
    kubeconfig: /etc/rancher/rke2/rke2.yaml
  delegate_to: localhost
  run_once: true
  no_log: true

Keyboard shortcuts

zarf_init

Parameters

Notes

Example