ilia/ansible
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ansible/docs/guides/ansible-vault-secrets.md
ilia de49b34cdc
Some checks failed
CI / skip-ci-check (pull_request) Successful in 6s
Details
CI / lint-and-test (pull_request) Failing after 9s
Details
CI / ansible-validation (pull_request) Failing after 6s
Details
CI / secret-scanning (pull_request) Successful in 5s
Details
CI / dependency-scan (pull_request) Successful in 8s
Details
CI / sast-scan (pull_request) Failing after 5s
Details
CI / license-check (pull_request) Successful in 11s
Details
CI / vault-check (pull_request) Failing after 6s
Details
CI / playbook-test (pull_request) Failing after 6s
Details
CI / container-scan (pull_request) Failing after 6s
Details
CI / sonar-analysis (pull_request) Failing after 2s
Details
CI / workflow-summary (pull_request) Successful in 4s
Details
Add homelab monitoring, portfolio site, and vault tooling. 
Document pve10 static IPs, monitoring stack, and site LXCs; add portfolio
to inventory; Mailcow mailbox automation; vault import/export scripts;
security audit guides and UniFi DHCP reference.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-22 16:25:07 -04:00

2.4 KiB
Raw Blame History

Encrypted secrets in this project

Ansible Vault is the standard way to store and share secrets with this repo. Plain .env files are gitignored and meant only as a temporary import path on your machine.

Recommended workflow

  1. Never commit .env, API keys, or passwords.
  2. Store secrets in inventories/production/group_vars/all/vault.yml (encrypted).
  3. Edit with make edit-group-vault (uses ~/.ansible-vault-pass on your workstation).
  4. Teammates need the same vault password file out-of-band (password manager, not git).

One-time import from .env

cp .env.example .env
# fill MAILCOW_API_KEY, ALERTS_PASSWORD, etc.
make vault-import-env
rm .env   # optional after import

make vault-import-env merges supported keys into the vault and re-encrypts the file.

Mailcow mailboxes (dynamic)

File Purpose
group_vars/all/mailcow.yml Mailbox names, local parts, quotas (no secrets)
vault.yml vault_mailcow_api_key, vault_mailcow_mailbox_passwords 
make mailcow-mailbox MAILBOX=alerts

Add a new mailbox:

  1. In mailcow.yml under mailcow_mailboxes: add e.g. notify: { local_part: notify, name: Notify, quota: 512, vault_password_key: notify }
  2. In vault: vault_mailcow_mailbox_passwords.notify: "..." (via make edit-group-vault)
  3. make mailcow-mailbox MAILBOX=notify

Can .env itself be encrypted?

Yes, but Ansible projects usually skip that pattern:

Approach Use when
Ansible Vault (vault.yml) Default for this repo — works with playbooks and make targets
ansible-vault encrypt .env Produces .env vault blob; you must ansible-vault view .env or decrypt to a temp file before tools read it — awkward for shell scripts
Password manager / 1Password CLI Personal machine only, not for CI/ansible runs
SOPS / Mozilla SOPS Teams that want encrypted YAML/JSON in git with KMS/PGP — heavier setup

Sharing encrypted secrets with others: share the vault password (or per-host vault pass) securely once; they clone the repo and use the same encrypted vault.yml. Do not email .env files.

Encrypting a single value (without opening the whole file)

ansible-vault encrypt_string 'secret-value' --name 'vault_my_secret' \
  --vault-password-file ~/.ansible-vault-pass

Paste the output into vault.yml inside the encrypted file, or into a vars file that is entirely vault-encrypted.