ilia
de49b34cdc
Some checks failed
CI / skip-ci-check (pull_request) Successful in 6s
CI / lint-and-test (pull_request) Failing after 9s
CI / ansible-validation (pull_request) Failing after 6s
CI / secret-scanning (pull_request) Successful in 5s
CI / dependency-scan (pull_request) Successful in 8s
CI / sast-scan (pull_request) Failing after 5s
CI / license-check (pull_request) Successful in 11s
CI / vault-check (pull_request) Failing after 6s
CI / playbook-test (pull_request) Failing after 6s
CI / container-scan (pull_request) Failing after 6s
CI / sonar-analysis (pull_request) Failing after 2s
CI / workflow-summary (pull_request) Successful in 4s
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>
61 lines
2.4 KiB
Markdown
61 lines
2.4 KiB
Markdown
# 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`
|
|
|
|
```bash
|
|
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` |
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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.
|