Sankofa/docs/proxmox/API_TOKEN_MANAGEMENT.md

Proxmox API Token Management Guide

Overview

This guide covers best practices for managing Proxmox API tokens used by the Crossplane provider.

Token Creation

Via Proxmox Web UI

1. Navigate to API Tokens:

   • Log into Proxmox Web UI
   • Go to Datacenter → Permissions → API Tokens
   • Click "Add"

2. Configure Token:

   • Token ID: crossplane-<site-name> (e.g., crossplane-us-east-1)
   • User: root@pam or dedicated service account
   • Expiration: Set appropriate expiration (recommended: 1 year or less)
   • Privilege Separation: Enable if using dedicated user

3. Set Permissions:

   • Administrator: Full access (for development)
   • VM-specific: Limited to VM operations (for production)
   • Storage-specific: Limited to storage operations (if needed)

4. Generate Token:

   • Click "Generate"
   • IMPORTANT: Copy the token immediately (format: user@realm!token-name=token-secret)
   • Store securely (will not be shown again)

Via Proxmox API

# Create token via API (requires existing authentication)
curl -k -X POST \
  -H "Authorization: PVEAuthCookie=YOUR_TICKET" \
  -H "CSRFPreventionToken: YOUR_CSRF_TOKEN" \
  -d "tokenid=crossplane-us-east-1&userid=root@pam&expire=31536000" \
  https://your-proxmox:8006/api2/json/access/users/root@pam/token

Token Format

Proxmox API tokens use the format:

user@realm!token-name=token-secret

Example:

root@pam!crossplane-us-east-1=abc123def456ghi789

Token Storage

Kubernetes Secret

Store tokens in Kubernetes secrets:

kubectl create secret generic proxmox-credentials \
  --from-literal=credentials.json='{"username":"root@pam","token":"root@pam!crossplane-token=abc123..."}' \
  -n crossplane-system

ProviderConfig Reference

The ProviderConfig references the secret:

spec:
  credentials:
    source: Secret
    secretRef:
      name: proxmox-credentials
      namespace: crossplane-system
      key: credentials.json

Token Permissions

Recommended Permissions

For production use, create tokens with minimal required permissions:

1. VM Operations:

   • VM.Allocate
   • VM.Clone
   • VM.Config
   • VM.Monitor
   • VM.PowerMgmt

2. Storage Operations (if needed):

   • Datastore.Allocate
   • Datastore.Audit

3. Network Operations (if needed):

   • SDN.Use

Development Permissions

For development/testing, Administrator role is acceptable but not recommended for production.

Token Rotation

Rotation Schedule

• Production: Rotate every 90 days
• Development: Rotate every 180 days
• Emergency: Rotate immediately if compromised

Rotation Procedure

1. Create New Token:

   • Create new token with same permissions
   • Test new token

2. Update Kubernetes Secret:

   kubectl delete secret proxmox-credentials -n crossplane-system
   kubectl create secret generic proxmox-credentials \
     --from-literal=credentials.json='{"username":"root@pam","token":"NEW_TOKEN"}' \
     -n crossplane-system
   

3. Restart Provider:

   kubectl delete pod -n crossplane-system -l app=crossplane-provider-proxmox
   

4. Verify:

   kubectl logs -n crossplane-system -l app=crossplane-provider-proxmox --tail=50
   

5. Revoke Old Token:

   • Log into Proxmox Web UI
   • Go to API Tokens
   • Delete old token

Token Security

Best Practices

1. Never Commit Tokens:

   • Never commit tokens to git
   • Use secrets management
   • Rotate if accidentally exposed

2. Use Separate Tokens:

   • Use different tokens per site/environment
   • Use different tokens per application
   • Track token usage

3. Monitor Token Usage:

   • Review Proxmox audit logs
   • Monitor for unusual activity
   • Set up alerts for failures

4. Limit Token Scope:

   • Use principle of least privilege
   • Grant only required permissions
   • Review permissions regularly

5. Set Expiration:

   • Always set token expiration
   • Rotate before expiration
   • Document expiration dates

Token Troubleshooting

Authentication Failures

1. Check Token Format:

   • Verify format: user@realm!token-name=token-secret
   • Check for typos
   • Verify special characters are escaped

2. Verify Token Validity:

   • Check token expiration
   • Verify token not revoked
   • Check user account status

3. Test Token:

   curl -k -H "Authorization: PVEAuthCookie=TOKEN" \
     https://your-proxmox:8006/api2/json/version
   

Permission Errors

1. Check Permissions:

   • Review token permissions in Proxmox
   • Verify required permissions are granted
   • Check user roles

2. Test Operations:

   • Try operation via Proxmox API
   • Check error messages
   • Review Proxmox logs

Token Audit

Regular Audits

1. Monthly Review:

   • List all active tokens
   • Review token usage
   • Check for unused tokens

2. Quarterly Review:

   • Review token permissions
   • Verify token expiration dates
   • Update documentation

3. Annual Review:

   • Complete token audit
   • Rotate all tokens
   • Review security practices

Audit Commands

# List tokens (via Proxmox API)
curl -k -H "Authorization: PVEAuthCookie=TOKEN" \
  https://your-proxmox:8006/api2/json/access/users/root@pam/token

Related Documentation

• Deployment Guide
• Security Audit
• Troubleshooting Guide