Sankofa/docs/proxmox/reference/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

```bash
# 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:

```bash
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:

```yaml
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**:
   ```bash
   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**:
   ```bash
   kubectl delete pod -n crossplane-system -l app=crossplane-provider-proxmox
   ```

4. **Verify**:
   ```bash
   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**:
   ```bash
   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

```bash
# 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](./DEPLOYMENT_GUIDE.md)
- [Security Audit](./TASK_LIST.md#task-020)
- [Troubleshooting Guide](../runbooks/PROXMOX_TROUBLESHOOTING.md)