Files

defiQUG a8106e24ee Remove obsolete audit and deployment documentation files

- Deleted outdated files related to repository audit and deployment status, including AUDIT_COMPLETE.md, AUDIT_FIXES_APPLIED.md, FINAL_DEPLOYMENT_STATUS.md, and others.
- Cleaned up documentation to streamline the repository and improve clarity for future maintenance.
- Updated README and other relevant documentation to reflect the removal of these files.

2025-12-12 19:42:31 -08:00

7.1 KiB

Raw Blame History

Proxmox API Token Management

Overview

This document describes the management of Proxmox API tokens for the Crossplane provider. API tokens provide secure, programmatic access to Proxmox clusters without requiring password authentication.

Token Architecture

Token Structure

Proxmox API tokens follow the format:

{username}@{realm}!{token-id}={token-secret}

Example:

root@pam!crossplane-instance-1=abc123-def456-ghi789

Token Components

Username: User account (e.g., root, service-account)
Realm: Authentication realm (e.g., pam, ldap)
Token ID: Unique identifier for the token
Token Secret: Secret value (never log or expose)

Token Creation

Via Proxmox Web UI

Navigate to: Datacenter → Permissions → API Tokens
Click: "Add" → "API Token"
Configure:
- Token ID: crossplane-instance-1
- User: root@pam (or dedicated service account)
- Comment: "Crossplane provider for Instance 1"
- Expiration: Set expiration date (recommended)
- Privilege Separation: Enable if using dedicated user
Save and copy the token secret immediately

Via Proxmox CLI

# Create token via pvesh
pvesh create /access/users/{user}/token/{token-id} \
  --privsep 1 \
  --expire {timestamp} \
  --comment "Crossplane provider token"

Via Proxmox API

curl -X POST "https://ml110-01.sankofa.nexus:8006/api2/json/access/users/root@pam/token/crossplane-instance-1" \
  -H "Authorization: PVEAPIToken root@pam!existing-token=secret" \
  -d 'privsep=1&expire=1735689600&comment=Crossplane provider'

Token Permissions

Principle of Least Privilege

Tokens should have minimum required permissions:

Recommended Permissions

For VM Management:

VM.Allocate - Create VMs
VM.Clone - Clone VMs
VM.Config.Disk - Manage VM disks
VM.Config.Network - Manage VM networks
VM.Monitor - Monitor VM status
VM.PowerMgmt - Start/stop VMs
VM.Snapshot - Create snapshots

For Storage Management:

Datastore.Allocate - Allocate storage
Datastore.Audit - Audit storage

For Node Management:

Sys.Audit - System audit
Sys.Modify - System modification (if needed)

Full Administrator (Not Recommended)

# ⚠️ Only for development/testing
Permissions: Administrator

Risks:

Full cluster access
Can delete critical resources
Security risk if compromised

Permission Configuration

# Set token permissions via pvesh
pvesh set /access/acl \
  --path / \
  --roles Administrator \
  --users root@pam!crossplane-instance-1

Token Storage

Kubernetes Secrets

Never store tokens in code or config files!

Store tokens in Kubernetes secrets:

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

Secret Structure

{
  "username": "root@pam",
  "token": "root@pam!crossplane-instance-1=abc123-def456-ghi789"
}

ProviderConfig Reference

apiVersion: proxmox.sankofa.nexus/v1alpha1
kind: ProviderConfig
metadata:
  name: proxmox-provider-config
spec:
  credentials:
    source: Secret
    secretRef:
      name: proxmox-credentials
      namespace: crossplane-system
      key: credentials.json

Token Rotation

Rotation Schedule

Production: Rotate every 90 days
Staging: Rotate every 180 days
Development: Rotate as needed

Rotation Procedure

Create New Token

# Create new token with new ID
pvesh create /access/users/root@pam/token/crossplane-instance-1-v2

Update Kubernetes Secret

kubectl create secret generic proxmox-credentials \
  --from-literal=credentials.json='{"token":"new-token"}' \
  -n crossplane-system \
  --dry-run=client -o yaml | kubectl apply -f -

Verify Provider Works
- Check provider logs
- Test VM operations
- Verify no authentication errors

Revoke Old Token

pvesh delete /access/users/root@pam/token/crossplane-instance-1

Update Documentation
- Update token inventory
- Record rotation date
- Update expiration dates

Automated Rotation

Consider implementing automated token rotation:

Kubernetes CronJob
External secret manager (e.g., HashiCorp Vault)
Proxmox API integration

Token Inventory

Current Tokens

Token ID	User	Realm	Expiration	Purpose	Status
crossplane-instance-1	root	pam	TBD	Instance 1 provider	Active
crossplane-instance-2	root	pam	TBD	Instance 2 provider	Active

Token Tracking

Maintain a token inventory with:

Token ID
Associated user
Creation date
Expiration date
Purpose/comment
Last rotation date
Status (active/revoked)

Security Best Practices

✅ Do

Use dedicated service accounts for tokens
Set token expiration dates
Rotate tokens regularly
Store tokens in Kubernetes secrets
Use principle of least privilege
Monitor token usage
Audit token access logs
Revoke unused tokens immediately

❌ Don't

Store tokens in code or config files
Commit tokens to git
Share tokens between environments
Use administrator tokens unnecessarily
Set tokens to never expire
Log token secrets
Expose tokens in error messages

Token Monitoring

Usage Monitoring

Monitor token usage via Proxmox audit logs:

# View API token usage
pvesh get /api2/json/access/token/{token-id}

Audit Logs

Review Proxmox audit logs for:

Token creation/deletion
Token usage patterns
Failed authentication attempts
Unusual access patterns

Alerting

Set up alerts for:

Token expiration (30 days before)
Failed authentication attempts
Unusual API usage patterns
Token rotation due dates

Troubleshooting

Error: "authentication failed"

Causes:

Token expired
Token revoked
Incorrect token format
Token secret mismatch

Solutions:

Verify token is active: pvesh get /access/users/{user}/token/{token-id}
Check token expiration date
Verify token secret in Kubernetes secret
Recreate token if needed

Error: "permission denied"