package_mirror_resources

zarf_package_mirror_resources

Push a package’s images and repositories into a registry and git server.

Write it as colonel_byte.zarf.zarf_package_mirror_resources. 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 mirror-resources, which pushes the images and git repositories a package carries into a registry and a git server without deploying anything.

The module is a compiled binary with zarf linked into it. It renders the zarf package mirror-resources 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 air-gap seeding step. A cluster that deploys with connected: true pulls the images itself, which means its registry has to hold them first, and before this module a playbook had no way to say so.

Parameters

Parameter	Type	Required	Flag	Description
`package`	`str`	yes	None	The package whose resources are mirrored: a path to a tarball, an `oci://` reference, or an `https://` URL. The positional argument of the command, so it renders no flag.
`kubeconfig`	`str`	no	None	The kubeconfig of the cluster whose registry and git server are the destination, for a mirror that reads them out of the cluster’s zarf state rather than being given them below. 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 the push 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.
`images`	`bool`	no	`--images`	Mirror only the images. Mutually exclusive with `repos`.
`repos`	`bool`	no	`--repos`	Mirror only the git repositories. Mutually exclusive with `images`.
`components`	`str`	no	`--components`	Which of the package’s components to mirror, as a comma-separated list.
`registry_url`	`str`	no	`--registry-url`	The registry to push the images to, for a destination that is not the one the cluster’s zarf state names.
`registry_push_username`	`str`	no	`--registry-push-username`	The registry’s push username.
`registry_push_password`	`str`	no	`--registry-push-password`	The registry’s push password.
`git_url`	`str`	no	`--git-url`	The git server to push the repositories to.
`git_push_username`	`str`	no	`--git-push-username`	The git server’s push username.
`git_push_password`	`str`	no	`--git-push-password`	The git server’s push password.
`shasum`	`str`	no	`--shasum`	The SHA256 checksum of a package fetched over `https://`.
`no_img_checksum`	`bool`	no	`--no-img-checksum`	Whether to push the images without their checksum tags.
`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`.
`skip_signature_validation`	`bool`	no	`--skip-signature-validation`	Whether zarf skips validating the package’s signature altogether.
`retries`	`int`	no	`--retries`	How many times zarf retries a failed push.
`oci_concurrency`	`int`	no	`--oci-concurrency`	How many OCI operations zarf runs at once.
`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: true and delegate_to on the task. One mirror fills the registry the whole cluster pulls from.
Set no_log: true on the task when any push credential is given as a parameter, or name a zarf config file with zarf_config and keep them out of the argument vector.
The task reports changed: true with zarf.changedSignal set to unknown, and names no components. Unlike a deploy, a mirror announces the resources it pushes rather than the component they came from – mirroring images, pushing image – so there is no component list to report and nothing that says whether the registry already held what was pushed.
Check mode reports the task as skipped. The command has no dry run.
images and repos are mutually exclusive, as they are in zarf. Setting both is an error naming them; leaving both unset mirrors everything.
A parameter left unset renders no flag, so whatever zarf’s own config file sets still applies.

Example

- name: Seed the cluster's registry so a connected deploy can find the images
  colonel_byte.zarf.zarf_package_mirror_resources:
    package: /srv/staging/zarf-package-monitoring-amd64.tar.zst
    kubeconfig: /etc/rancher/rke2/rke2.yaml
    public_key: /etc/zarf/colonel-byte-zarf-packages.pub
    verify: always
  delegate_to: localhost
  run_once: true
  register: mirror_result

- name: Deploy without pushing the images again
  colonel_byte.zarf.zarf_package_deploy:
    package: /srv/staging/zarf-package-monitoring-amd64.tar.zst
    connected: true
    kubeconfig: /etc/rancher/rke2/rke2.yaml
  delegate_to: localhost
  run_once: true

- name: Push only the images, to a registry outside the cluster
  colonel_byte.zarf.zarf_package_mirror_resources:
    package: oci://ghcr.io/colonel-byte/zarf/monitoring:1.0.0
    images: true
    registry_url: registry.bubbles.test
    registry_push_username: zarf-push
    registry_push_password: "{{ registry_password }}"
  delegate_to: localhost
  run_once: true
  no_log: true

- name: Report the command the mirror ran
  ansible.builtin.debug:
    var: mirror_result.zarf.command

Keyboard shortcuts

zarf_package_mirror_resources

Parameters

Notes

Example