Nathan
ac6e68e301
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)
113 lines
2.8 KiB
Markdown
113 lines
2.8 KiB
Markdown
# 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
|
|
|
|
```yaml
|
|
# 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
|
|
|
|
```yaml
|
|
# 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)
|
|
|
|
```yaml
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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.
|