Sankofa/docs/proxmox/ENVIRONMENT_VARIABLES.md

# Environment Variables Reference

**Last Updated**: 2024-12-19

## Overview

This document describes all environment variables used in the Proxmox deployment scripts and configuration.

## Quick Start

### Using .env File

1. Copy the example file:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` with your actual credentials:
   ```bash
   nano .env
   ```

3. Scripts will automatically load variables from `.env` if present.

### Manual Export

Alternatively, export variables manually:
```bash
export CLOUDFLARE_API_KEY="your-key"
export CLOUDFLARE_EMAIL="your-email@example.com"
```

## Cloudflare Variables

### CLOUDFLARE_API_KEY
**Type**: String  
**Required**: Yes (if not using API Token)  
**Description**: Cloudflare Global API Key  
**Location**: [Cloudflare Dashboard](https://dash.cloudflare.com/profile/api-tokens)  
**Example**: `e5153f7f2dcf64fec7f25ede78c15482bc950`

### CLOUDFLARE_EMAIL
**Type**: String  
**Required**: Yes (if using Global API Key)  
**Description**: Cloudflare account email address  
**Example**: `pandoramannli@gmail.com`

### CLOUDFLARE_API_TOKEN
**Type**: String  
**Required**: No (alternative to Global API Key)  
**Description**: Cloudflare API Token (recommended for scripts)  
**Location**: [Create API Token](https://dash.cloudflare.com/profile/api-tokens)  
**Note**: More secure than Global API Key, recommended for production

### CLOUDFLARE_ORIGIN_CA_KEY
**Type**: String  
**Required**: No  
**Description**: Cloudflare Origin CA Key for certificate management  
**Location**: [Cloudflare Dashboard](https://dash.cloudflare.com/profile/api-tokens)  
**Example**: `v1.0-40220c19a24f6e2980fb37b0-...`

### CLOUDFLARE_ZONE_ID
**Type**: String  
**Required**: No (can be auto-detected)  
**Description**: Cloudflare Zone ID for your domain  
**How to get**: 
```bash
curl -X GET "https://api.cloudflare.com/client/v4/zones?name=sankofa.nexus" \
  -H "X-Auth-Email: your-email@example.com" \
  -H "X-Auth-Key: your-api-key" | jq -r '.result[0].id'
```

### CLOUDFLARE_ACCOUNT_ID
**Type**: String  
**Required**: No (for tunnel creation)  
**Description**: Cloudflare Account ID  
**Location**: Cloudflare Dashboard (right sidebar)

## Domain Variables

### DOMAIN
**Type**: String  
**Required**: No  
**Default**: `sankofa.nexus`  
**Description**: Primary domain name for DNS records

## Proxmox Variables

### PROXMOX_USERNAME
**Type**: String  
**Required**: No  
**Description**: Proxmox username (e.g., `root@pam`)

### PROXMOX_PASSWORD
**Type**: String  
**Required**: No  
**Description**: Proxmox password

### PROXMOX_TOKEN
**Type**: String  
**Required**: No  
**Description**: Proxmox API token (format: `user@realm!token-id=token-secret`)

### PROXMOX_ENDPOINT
**Type**: String  
**Required**: No  
**Description**: Proxmox API endpoint URL

## Kubernetes Variables

### NAMESPACE
**Type**: String  
**Required**: No  
**Default**: `crossplane-system`  
**Description**: Kubernetes namespace for provider deployment

### KUBECONFIG
**Type**: String  
**Required**: No  
**Description**: Path to kubeconfig file

## Script-Specific Variables

### SITE
**Type**: String  
**Required**: Yes (for setup-proxmox-agents.sh)  
**Description**: Proxmox site name (e.g., `us-sfvalley`)

### NODE
**Type**: String  
**Required**: Yes (for setup-proxmox-agents.sh)  
**Description**: Proxmox node name (e.g., `ML110-01`)

### CLOUDFLARE_TUNNEL_TOKEN
**Type**: String  
**Required**: No  
**Description**: Cloudflare tunnel token for specific site

### BUILD_PROVIDER
**Type**: Boolean  
**Required**: No  
**Default**: `true`  
**Description**: Whether to build provider before deployment

### WAIT_TIMEOUT
**Type**: Integer  
**Required**: No  
**Default**: `300`  
**Description**: Timeout in seconds for VM deployment

### PROMETHEUS_ENABLED
**Type**: Boolean  
**Required**: No  
**Default**: `true`  
**Description**: Whether to install Prometheus exporter

## Authentication Methods

### Method 1: Global API Key + Email (Current)
```bash
export CLOUDFLARE_API_KEY="your-key"
export CLOUDFLARE_EMAIL="your-email@example.com"
```

### Method 2: API Token (Recommended)
```bash
export CLOUDFLARE_API_TOKEN="your-token"
```

## Security Best Practices

1. **Never commit `.env` file** - It's already in `.gitignore`
2. **Use API Tokens** - More secure than Global API Key
3. **Rotate credentials regularly** - Especially API keys
4. **Use least privilege** - Grant only necessary permissions
5. **Store secrets securely** - Use secret management tools in production

## Loading Environment Variables

### Automatic (Recommended)
Scripts automatically load from `.env` if present in project root.

### Manual
```bash
# Source .env file
source .env

# Or use helper script
source scripts/load-env.sh
```

### In Scripts
```bash
# At the top of your script
if [ -f .env ]; then
    source .env
fi
```

## Troubleshooting

### Variables Not Loading
```bash
# Check if .env exists
ls -la .env

# Check if variables are set
echo $CLOUDFLARE_API_KEY

# Manually source
source .env
```

### Authentication Errors
```bash
# Verify credentials
curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

# Or with Global API Key
curl -X GET "https://api.cloudflare.com/client/v4/user" \
  -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
  -H "X-Auth-Key: $CLOUDFLARE_API_KEY"
```

## Related Documentation

- [Quick Start Guide](./QUICK_START.md)
- [Script Reference](./SCRIPT_REFERENCE.md)
- [Deployment Guide](./DEPLOYMENT_GUIDE.md)