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 three used everywhere; a couple more get installed ad hoc for Kubernetes 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.

azure.azcollection (>=2.0.0)

Pinned to a specific version (azure.azcollection:2.7.0 in install_dev_tools.sh) more deliberately than the other two collections here — its Python deps (azure-mgmt-resource, azure-mgmt-storage, etc.) are version-sensitive enough that install_dev_tools.sh installs the collection's own bundled requirements.txt as a corrective second pass, not a fresh fetch from upstream, to avoid drifting out of sync with whatever collection version is actually installed.

  • azure.azcollection.azure_rm_storageblob — backup-playbook.yml's final play uploads that day's config exports to the offsite backup storage account in batch_upload_src/batch_upload_dst mode, authenticating as the same ARM service principal Terraform uses (auth_mode: key, which calls ARM's list_keys under the hood — no separate storage key or connection string stored anywhere). See Azure → Offsite backup storage account for the storage account itself.

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.

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 into one local directory (backup_config_root), then hands off to azure.azcollection.azure_rm_storageblob (see above) to sync that directory to the offsite backup storage account; 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 SSL playbook (backup-playbook.yml dropped this — its local landing directory is now a plain Vault-sourced group var, backup_config_root, same pattern as the rest of group_vars/all.yml), 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).