Apply Composer changes: comprehensive API updates, migrations, middleware, and infrastructure improvements
- Add comprehensive database migrations (001-024) for schema evolution - Enhance API schema with expanded type definitions and resolvers - Add new middleware: audit logging, rate limiting, MFA enforcement, security, tenant auth - Implement new services: AI optimization, billing, blockchain, compliance, marketplace - Add adapter layer for cloud integrations (Cloudflare, Kubernetes, Proxmox, storage) - Update Crossplane provider with enhanced VM management capabilities - Add comprehensive test suite for API endpoints and services - Update frontend components with improved GraphQL subscriptions and real-time updates - Enhance security configurations and headers (CSP, CORS, etc.) - Update documentation and configuration files - Add new CI/CD workflows and validation scripts - Implement design system improvements and UI enhancements
This commit is contained in:
defiQUG
235
docs/proxmox/API_TOKEN_MANAGEMENT.md
Normal file
235
docs/proxmox/API_TOKEN_MANAGEMENT.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# 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)
|
||||
|
||||
Reference in New Issue
Block a user