Ansible Roles and Vault: Reusable Automation Without Secret Sprawl

A Role Is a Contract, Not a Folder Dump

A role packages one reusable responsibility using conventions such as tasks/, handlers/, templates/, files/, defaults/, vars/, and meta/. The public interface should be a small set of documented variables in defaults/main.yml.

roles/catalog/
  defaults/main.yml
  tasks/main.yml
  handlers/main.yml
  templates/catalog.conf.j2
  meta/main.yml

Put overridable values in defaults. Reserve role vars for values callers should not normally replace. Do not hide environment-specific hostnames or credentials inside task files.

Use import_role when the role structure should be available during parse time and include_role for genuinely dynamic execution. Prefer composition of focused roles over one role with dozens of boolean switches.

---

Vault Protects Stored Text, Not Every Use

Ansible Vault encrypts variables or files at rest so ciphertext can live in Git. It does not prevent a decrypted value from appearing in process arguments, debug output, rendered files, controller caches, or CI logs.

Keep ordinary and secret variables separate:

# group_vars/production/main.yml
catalog_db_user: catalog
catalog_db_password: "{{ vault_catalog_db_password }}"

# group_vars/production/vault.yml (encrypted)
vault_catalog_db_password: replace-me-before-encryption

Encrypt the vault file, commit only ciphertext, and use no_log: true on tasks that may display the secret. Remember that no_log reduces diagnostics; keep non-secret validation separate.

Use Vault IDs and External Secret Delivery

Vault IDs distinguish environments or ownership boundaries:

ansible-vault encrypt --vault-id prod@prompt group_vars/production/vault.yml
ansible-playbook site.yml --vault-id prod@/secure/path/prod-pass

Do not commit password files. In CI, inject them from the platform secret store with restricted permissions and delete temporary material unconditionally. For larger environments, use a secrets-manager lookup and short-lived identity so fewer long-lived values exist in Git, even encrypted.

Rotation means changing the underlying service credential and updating consumers, not merely rekeying the vault ciphertext. Test both old-token revocation and new-token use.

Refactor safely in Build a Reusable Role and repair secret handling in Move Secrets into Ansible Vault.