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:

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:

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

Security Best Practices

✅ Recommended: Enable TLS Verification

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

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

   # On Proxmox node
   pvecm updatecerts -f
   # Or manually install certificates
   

3. Verify Certificate

   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

   # 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

   certbot renew --dry-run
   

2. Monitor certificate expiration

   • Set up alerts for certificates expiring in < 30 days
   • Automate renewal process

3. Update Proxmox certificates

   # 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

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

Development Configuration

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

Staging Configuration

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

Monitoring

Certificate Expiration Alerts

Set up Prometheus alerts:

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
• Security Audit
• API Token Management

Last Updated

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