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:

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

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

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

### Test API Access

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

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

### In Kubernetes

Create Kubernetes secret:

```bash
# 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**
   ```bash
   echo $PROXMOX_TOKEN
   # Should be: user@realm!token-id=token-secret
   ```

2. **Test API Access**
   ```bash
   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**
   ```bash
   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**
   ```bash
   # 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](./ENVIRONMENT_VARIABLES.md)
- [Deployment Readiness](./DEPLOYMENT_READINESS.md)
- [Quick Start Guide](./QUICK_START.md)