zarf_package_remove
Remove a deployed zarf package from a cluster.
Write it as colonel_byte.zarf.zarf_package_remove. 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 remove against the cluster a kubeconfig names, taking a deployed package – or some of its components – off it.
The module is a compiled binary with zarf linked into it. It renders the zarf package remove 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 other half of colonel_byte.zarf.zarf_package_deploy. A playbook that can only deploy is not reconciling a cluster, and removing a component of a package while leaving the rest is the one thing a deploy cannot undo.
Parameters
| Parameter | Type | Required | Flag | Description |
|---|---|---|---|---|
package | str | yes | None | What to remove: the deployed package’s name as zarf package list reports it, a path to the tarball it was deployed from, or an oci:// reference. The name is usually what a playbook wants, because the tarball may be long gone by the time the package is removed. The positional argument of the command, so it renders no flag. |
kubeconfig | str | no | None | The kubeconfig of the cluster to remove from. 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. |
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. |
components | str | no | --components | Which of the package’s components to remove, as a comma-separated list. Omitted, the whole package goes. |
namespace | str | no | --namespace | The namespace the package was deployed into, for a package deployed with colonel_byte.zarf.zarf_package_deploy’s namespace. Alpha in zarf. |
values | list of str | no | --values | Values files for the package’s on-remove actions, one flag per entry. |
set_values | dict | no | --set-values | Values for the package’s on-remove actions, as a mapping. Rendered one flag per entry, sorted, so the same parameters always render the same command line. |
oci_concurrency | int | no | --oci-concurrency | How many OCI operations zarf runs at once, for a package named by an oci:// reference. |
architecture | str | no | --architecture | The architecture of the package being removed. |
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. One removal takes the package off the whole cluster, so a play over the cluster’s own inventory would otherwise run it once per host. --confirmis always rendered. There is no terminal on the other end of a playbook task to confirm at, and this is the command where that matters most: the task itself is the confirmation that something should be deleted.- The task reports
changed: truewithzarf.changedSignalset tounknown. Zarf logs a removal as one line and names no component on the way, so there is nothing that distinguishes a package that was there from one that was already gone – a removal that finds nothing fails in zarf, which is the only signal there is. - Check mode reports the task as skipped.
zarf package removehas no dry run, and removing a package during a run an operator asked to be told about is worse than deploying one. - A parameter left unset renders no flag, so whatever zarf’s own config file sets still applies.
Example
- name: Remove a deployed package by name
colonel_byte.zarf.zarf_package_remove:
package: csi-local-path-provider
kubeconfig: /etc/rancher/rke2/rke2.yaml
delegate_to: localhost
run_once: true
- name: Remove one component and leave the rest of the package in place
colonel_byte.zarf.zarf_package_remove:
package: monitoring
components: grafana-dashboards
kubeconfig: /etc/rancher/rke2/rke2.yaml
delegate_to: localhost
run_once: true
register: remove_result
- name: Report the command that ran
ansible.builtin.debug:
var: remove_result.zarf.command