Sankofa/docs/proxmox/TLS_CONFIGURATION.md

# TLS Configuration Guide

## Overview

This document describes the TLS configuration for Proxmox API connections in the Crossplane provider. Proper TLS configuration is critical for security and compliance.

## Current Configuration

### ProviderConfig Settings

The `ProviderConfig` resource supports TLS configuration per site:

```yaml
apiVersion: proxmox.sankofa.nexus/v1alpha1
kind: ProviderConfig
metadata:
  name: proxmox-provider-config
spec:
  sites:
    - name: us-sfvalley
      endpoint: https://ml110-01.sankofa.nexus:8006
      insecureSkipTLSVerify: false  # ✅ TLS verification enabled
    - name: eu-west-1
      endpoint: https://r630-01.sankofa.nexus:8006
      insecureSkipTLSVerify: false  # ✅ TLS verification enabled
      insecureSkipTLSVerify: false  # ✅ TLS verification enabled
```

## TLS Verification

### Current Status

- **Default**: `insecureSkipTLSVerify: false` (TLS verification enabled)
- **Location**: `crossplane-provider-proxmox/examples/provider-config.yaml`
- **Implementation**: `pkg/proxmox/http_client.go`

### Implementation Details

The HTTP client uses Go's `crypto/tls` package:

```go
transport := &http.Transport{
    TLSClientConfig: &tls.Config{
        InsecureSkipVerify: insecureSkipTLSVerify,
    },
}
```

## Security Best Practices

### ✅ Recommended: Enable TLS Verification

```yaml
insecureSkipTLSVerify: false
```

**Benefits**:
- Prevents man-in-the-middle attacks
- Validates certificate authenticity
- Ensures connection to intended server
- Required for compliance (SOC 2, ISO 27001)

### ⚠️ Development Only: Disable TLS Verification

```yaml
insecureSkipTLSVerify: true
```

**Use Cases**:
- Development environments with self-signed certificates
- Testing with local Proxmox instances
- Temporary workarounds (should be fixed)

**Risks**:
- Vulnerable to MITM attacks
- No certificate validation
- Not suitable for production

## Certificate Management

### Proxmox Certificate Setup

1. **Obtain Valid Certificates**
   - Use Let's Encrypt (recommended)
   - Use internal CA for private networks
   - Purchase commercial certificates

2. **Install Certificates on Proxmox**
   ```bash
   # On Proxmox node
   pvecm updatecerts -f
   # Or manually install certificates
   ```

3. **Verify Certificate**
   ```bash
   openssl s_client -connect ml110-01.sankofa.nexus:8006 -showcerts
   ```

### Certificate Validation

The provider validates:
- Certificate chain
- Certificate expiration
- Hostname matching
- Certificate authority trust

## Troubleshooting

### Error: "x509: certificate signed by unknown authority"

**Cause**: Certificate not trusted by system CA bundle

**Solutions**:
1. **Add CA certificate to system trust store**
   ```bash
   # On Kubernetes node
   cp ca-cert.pem /usr/local/share/ca-certificates/
   update-ca-certificates
   ```

2. **Use custom CA bundle in provider**
   - Mount CA certificate as secret
   - Configure provider to use custom CA bundle
   - Update HTTP client to use custom CA

3. **Temporary**: Set `insecureSkipTLSVerify: true` (development only)

### Error: "x509: certificate is valid for X, not Y"

**Cause**: Certificate hostname mismatch

**Solutions**:
1. **Update certificate to include correct hostname**
2. **Use correct hostname in endpoint configuration**
3. **Request new certificate with correct SANs**

### Error: "x509: certificate has expired"

**Cause**: Certificate expired

**Solutions**:
1. **Renew certificate**
2. **Install new certificate on Proxmox**
3. **Update certificate rotation procedures**

## Certificate Rotation

### Automated Rotation

1. **Use Let's Encrypt with auto-renewal**
   ```bash
   certbot renew --dry-run
   ```

2. **Monitor certificate expiration**
   - Set up alerts for certificates expiring in < 30 days
   - Automate renewal process

3. **Update Proxmox certificates**
   ```bash
   # After renewal
   systemctl reload pveproxy
   ```

### Manual Rotation

1. **Obtain new certificate**
2. **Install on Proxmox node**
3. **Verify certificate works**
4. **Update provider configuration if needed**
5. **Restart provider pods**

## Compliance Considerations

### SOC 2 Requirements

- ✅ TLS 1.2+ required
- ✅ Certificate validation enabled
- ✅ Certificate rotation procedures documented
- ✅ Certificate expiration monitoring

### ISO 27001 Requirements

- ✅ Encryption in transit
- ✅ Certificate management procedures
- ✅ Access control for certificate management
- ✅ Audit logging of certificate changes

## Configuration Examples

### Production Configuration

```yaml
sites:
  - name: us-east-1
    endpoint: https://pve1.sankofa.nexus:8006
    insecureSkipTLSVerify: false  # Production: always false
```

### Development Configuration

```yaml
sites:
  - name: dev
    endpoint: https://pve-dev.local:8006
    insecureSkipTLSVerify: true  # Dev only: self-signed certs
```

### Staging Configuration

```yaml
sites:
  - name: staging
    endpoint: https://pve-staging.sankofa.nexus:8006
    insecureSkipTLSVerify: false  # Staging: use real certs
```

## Monitoring

### Certificate Expiration Alerts

Set up Prometheus alerts:

```yaml
groups:
  - name: tls_certificates
    rules:
      - alert: ProxmoxCertificateExpiring
        expr: probe_ssl_earliest_cert_expiry - time() < 86400 * 30
        for: 1h
        annotations:
          summary: "Proxmox certificate expiring soon"
```

### TLS Connection Monitoring

Monitor TLS handshake failures:
- Failed TLS connections
- Certificate validation errors
- Connection timeouts

## Related Documentation

- [Provider Configuration](./PROVIDER_CONFIG.md)
- [Security Audit](./SECURITY_AUDIT.md)
- [API Token Management](./API_TOKENS.md)

## Last Updated

- **Date**: 2024-12-19
- **Status**: TLS verification enabled by default
- **Next Review**: 2025-01-19