Sankofa/docs/proxmox/PROXMOX_CREDENTIALS.md

Proxmox API Credentials Setup

Last Updated: 2024-12-19

Overview

This guide explains how to create and configure Proxmox API tokens for use with the Crossplane provider.

Current Status

Proxmox credentials are not yet configured in .env. You need to:

1. Create API tokens in each Proxmox instance
2. Add them to the .env file

Creating API Tokens

For Each Proxmox Instance

1. Log in to Proxmox Web UI

   • Instance 1: https://ml110-01.sankofa.nexus:8006
   • Instance 2: https://r630-01.sankofa.nexus:8006

2. Navigate to API Tokens

   • Go to: Datacenter → Permissions → API Tokens
   • Click Add or Create Token

3. Configure Token

   • Token ID: crossplane-<site-name>
     • Instance 1: crossplane-us-sfvalley
     • Instance 2: crossplane-us-sfvalley-2
   • User: root@pam (or dedicated service account)
   • Expiration: Set appropriate expiration (or leave blank for no expiration)
   • Privilege Separation: Enable if using dedicated user
   • Permissions:
     • Administrator (full access) - Recommended for initial setup
     • Or specific permissions: VM.Allocate, VM.Audit, Datastore.Audit, etc.

4. Save Token Secret

   • Important: Copy the token secret immediately
   • Format: user@realm!token-id=token-secret
   • Example: root@pam!crossplane-us-sfvalley=abc123def456...
   • You cannot view the secret again after creation

Adding Credentials to .env

Option 1: Instance-Specific Credentials (Recommended)

Edit .env and uncomment/fill in:

# Instance 1 (ML110-01) - us-sfvalley
PROXMOX_USERNAME_ML110_01=root@pam
PROXMOX_TOKEN_ML110_01=root@pam!crossplane-us-sfvalley=your-token-secret-here

# Instance 2 (R630-01) - us-sfvalley-2
PROXMOX_USERNAME_R630_01=root@pam
PROXMOX_TOKEN_R630_01=root@pam!crossplane-us-sfvalley-2=your-token-secret-here

Option 2: Generic Credentials (Same Token for Both)

If using the same token for both instances:

PROXMOX_USERNAME=root@pam
PROXMOX_TOKEN=root@pam!crossplane-token=your-token-secret-here

Token Format

Proxmox API tokens use the format:

user@realm!token-id=token-secret

Where:

• user@realm: The Proxmox user (e.g., root@pam)
• token-id: The token identifier (e.g., crossplane-us-sfvalley)
• token-secret: The secret part of the token

Testing Credentials

Test Connectivity

# Test with token
export PROXMOX_TOKEN='root@pam!crossplane-us-sfvalley=your-secret'
./scripts/test-proxmox-connectivity.sh

Test API Access

# Test API call
curl -k -H "Authorization: PVEAPIToken ${PROXMOX_TOKEN}" \
  https://ml110-01.sankofa.nexus:8006/api2/json/version

Security Best Practices

1. Use Dedicated Service Accounts

   • Create a dedicated user for Crossplane (e.g., crossplane@pam)
   • Grant only necessary permissions
   • Use privilege separation

2. Rotate Tokens Regularly

   • Set expiration dates
   • Rotate tokens quarterly or as per security policy
   • Revoke old tokens immediately

3. Limit Permissions

   • Don't use Administrator role if not needed
   • Grant only specific permissions required
   • Use least privilege principle

4. Secure Storage

   • Never commit .env to git (already in .gitignore)
   • Use Kubernetes secrets for production
   • Rotate credentials if exposed

Using Credentials

In Scripts

Scripts automatically load from .env:

# Scripts will use PROXMOX_TOKEN or instance-specific tokens
./scripts/test-proxmox-connectivity.sh
./scripts/create-proxmox-secret.sh

In Kubernetes

Create Kubernetes secret:

# Interactive creation
./scripts/create-proxmox-secret.sh

# Or manually
kubectl create secret generic proxmox-credentials \
  --from-literal=username=root@pam \
  --from-literal=token='root@pam!token-id=token-secret' \
  -n crossplane-system

Troubleshooting

Token Not Working

1. Verify Token Format

   echo $PROXMOX_TOKEN
   # Should be: user@realm!token-id=token-secret
   

2. Test API Access

   curl -k -H "Authorization: PVEAPIToken ${PROXMOX_TOKEN}" \
     https://ml110-01.sankofa.nexus:8006/api2/json/version
   

3. Check Token Permissions

   • Verify token has required permissions
   • Check if token is expired
   • Verify user account is active

Authentication Errors

1. Verify .env is Loaded

   source .env
   echo $PROXMOX_TOKEN
   

2. Check Token Secret

   • Ensure token secret is correct
   • No extra spaces or quotes
   • Full token format included

3. Test Each Instance

   # Test Instance 1
   export PROXMOX_TOKEN='root@pam!crossplane-us-sfvalley=secret'
   curl -k -H "Authorization: PVEAPIToken ${PROXMOX_TOKEN}" \
     https://ml110-01.sankofa.nexus:8006/api2/json/version
   
   # Test Instance 2
   export PROXMOX_TOKEN='root@pam!crossplane-us-sfvalley-2=secret'
   curl -k -H "Authorization: PVEAPIToken ${PROXMOX_TOKEN}" \
     https://r630-01.sankofa.nexus:8006/api2/json/version
   

Related Documentation

• Environment Variables
• Deployment Readiness
• Quick Start Guide