Skip to content

Plugins & Collections

The playbooks in ansible/ (plus one embedded in terraform/compute/pfsense-bgp-playbook.yml) lean on a small set of collections rather than plain command/shell wherever a real module exists. ansible/requirements.yml declares the two used everywhere; a couple more get installed ad hoc for Kubernetes/Azure work — see install_dev_tools.sh.

Declared in requirements.yml

community.hashi_vault (>=6.0.0)

Pulls every credential the playbooks need straight from Vault at run time instead of group_vars literals — see Vault Overview.

  • community.hashi_vault.vault_kv2_get — used via lookup(...) in ansible/group_vars/all.yml to fetch the vmware and dir_path KV2 secrets (vCenter/ESXi credentials, TrueNAS directory paths) once, at the top of every play.

community.vmware (>=4.0.0)

Talks to ESXi/vCenter directly over the VMware API rather than SSHing into hosts — what powers the cluster start/stop tooling.

  • community.vmware.vmware_guest_powerstate — start-cluster.yml, stop-cluster.yml, start-stop-esxi.yml, supervisor-cluster-shutdown.yml, vcsa-esxi-simple-ssh.yml — powers VMs on/off (control-plane nodes, worker/system nodes, HAProxy, Supervisor VMs).
  • community.vmware.vmware_host_powerstate — stop-cluster.yml, start-stop-esxi.yml, supervisor-cluster-shutdown.yml, vcsa-esxi-simple-ssh.yml — shuts down the ESXi hosts themselves once their guests are down.
  • community.vmware.vmware_vm_info — start-stop-esxi.yml, supervisor-cluster-shutdown.yml, vcsa-esxi-simple-ssh.yml — lists/polls VM inventory and power state to decide what still needs shutting down before proceeding.

Installed ad hoc (not in requirements.yml)

install_dev_tools.sh also runs ansible-galaxy collection install for collections only needed on the machine actually running certain playbooks, rather than bloating every clone's requirements:

  • kubernetes.core — kubernetes.core.k8s_info is used in start-cluster.yml to poll Node objects and confirm the cluster is actually ready after power-on, not just that the VMs are running.
  • community.kubernetes — installed alongside kubernetes.core for backward-compatible module names where older playbook logic still references them.
  • azure.azcollection — installed via a separate requirements-azure.txt for any Azure-side day-2 tasks, kept out of the default collection set since most playbooks never touch Azure.

ansible.builtin modules worth calling out

Most playbooks otherwise lean on plain ansible.builtin modules — file, set_fact, find, debug, fetch, command, shell, wait_for, pause, copy, service — but a few uses are worth knowing about before touching those playbooks:

  • raw — used heavily in supervisor-cluster-shutdown.yml for SSH-based iptables/etcd/HAProxy fixes directly on the VCSA and Supervisor VMs, and in terraform/compute/pfsense-bgp-playbook.yml for vtysh/php -r calls against pfSense's FRR BGP config (see Supervisor Operations) — raw bypasses the normal module/Python-interpreter path entirely, which is why it shows up specifically on appliance-like targets (pfSense, VCSA) that don't have a full Python environment.
  • find + fetch + copy — backup-playbook.yml uses this trio to pull TrueNAS/UniFi/pfSense config exports off their hosts and redistribute renewed certs; ssl-renew-playbook.yml follows the same copy+service pattern to push a renewed cert and restart the consuming service.
  • command with find ... -delete — recording_cleanup.yml's entire job is this one line; no need for a dedicated module for pruning old camera recordings.
  • lookup('env', ...) — used repeatedly for run-time parameters rather than hardcoded values: DEVHOME_REPO_DEFAULT in the backup/SSL playbooks, and BGP_ASN/BGP_ACTION/NODE_IPS/CLUSTER_NAME in pfsense-bgp-playbook.yml (see Supervisor Operations for how Terraform invokes that playbook per-cluster with different env values).