nathan/homelab
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Releases Wiki Activity
homelab/ansible/playbooks/OPENAPPLY-VAULT-REFERENCE.md
Nathan ac6e68e301 docs(ansible): add comprehensive documentation for openapply_app role 
Complete role documentation suite per Ansible Galaxy and homelab standards:
- Add role README.md with variable tables, usage examples, and deployment notes
- Add meta/main.yml for Galaxy metadata and collection dependencies
- Add OPENAPPLY-VAULT-REFERENCE.md with vault setup and Proxmox token guide
- Add OPENAPPLY-IMPLEMENTATION-REPORT.md with architecture, validation, and handoff details

Context: Completes the OpenApply LXC deployment implementation from session plan.
This documentation enables users to configure vault secrets, understand role variables,
and execute the two-tier Proxmox provisioning workflow.

Ref: Session plan at /memories/session/plan.md (Phases 1-6 complete)
2026-04-17 19:29:13 -04:00

2.8 KiB
Raw Blame History

OpenApply Deployment - Vault Variables Reference

This document lists the encrypted variables that must be configured in ansible/group_vars/all/vault.yml before deploying OpenApply.

Required Vault Variables

Proxmox API Authentication

# Proxmox API endpoint
vault_proxmox_api_host: "10.0.0.201"

# Proxmox API user (typically root@pam)
vault_proxmox_api_user: "root@pam"

# Proxmox API token ID
vault_proxmox_api_token_id: "automation"

# Proxmox API token secret (encrypted)
vault_proxmox_api_token_secret: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  [encrypted token here]

LXC Container Credentials

# Root password for the OpenApply LXC container (encrypted)
vault_openapply_lxc_root_password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  [encrypted password here]

Application Secrets (Optional)

# Firebase deployment token (optional, encrypted)
vault_openapply_firebase_token: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  [encrypted token here]

Creating/Editing Vault Variables

First-time Setup

# Navigate to ansible directory
cd /home/chester/homelab/ansible

# Edit the encrypted vault file
ansible-vault edit group_vars/all/vault.yml

# Add the variables listed above

Generating a Proxmox API Token

  1. Log into Proxmox web UI (https://pve01:8006)
  2. Navigate to: Datacenter → Permissions → API Tokens
  3. Click "Add" button
  4. User: root@pam
  5. Token ID: automation (or custom name)
  6. Privilege Separation: Unchecked (for full root@pam permissions)
  7. Click "Add"
  8. Copy the secret immediately (only shown once)
  9. Add to vault file as shown above

Required Permissions

If using privilege separation, the token needs:

  • VM.Allocate - Create new containers
  • VM.Config.Network - Configure networking
  • VM.PowerMgmt - Start/stop containers
  • Datastore.AllocateSpace - Allocate storage

Security Best Practices

  1. Never commit unencrypted secrets to Git
  2. Rotate API tokens quarterly
  3. Use separate tokens for different automation workflows
  4. Audit Proxmox API access logs regularly
  5. Verify vault encryption: ansible-vault view group_vars/all/vault.yml

Validation

Test that vault variables are correctly configured:

# Verify vault can be decrypted
ansible-vault view group_vars/all/vault.yml

# Test variable resolution (without execution)
ansible-playbook playbooks/deploy-openapply.yml --check --diff

Troubleshooting

"vault_proxmox_api_token_secret is undefined"

Ensure the variable is present in group_vars/all/vault.yml and the file is properly encrypted.

"Authentication failed"

  1. Verify token ID matches Proxmox configuration
  2. Confirm token is not expired
  3. Check privilege separation settings
  4. Regenerate token if necessary

"Cannot decrypt vault"

Ensure ansible/vault/.vault_pass contains the correct vault password.