From faf2010dd4c32b840607fb6bc848695d97bcf36f Mon Sep 17 00:00:00 2001
From: Marian Koreniuk <moriarti@cp.if.ua>
Date: Thu, 13 Mar 2025 18:13:56 +0100
Subject: [PATCH] add docs for Cluster API integration to Proxmox

---
 packages/system/capi-providers/README.md      | 166 ++++++++++++++++++
 .../scripts/create-proxmox-cluster.sh         | 107 +++++++++++
 .../scripts/debug-proxmox-cluster.sh          | 128 ++++++++++++++
 .../templates/proxmox-examples.yaml           | 121 +++++++++++++
 4 files changed, 522 insertions(+)
 create mode 100644 packages/system/capi-providers/README.md
 create mode 100755 packages/system/capi-providers/scripts/create-proxmox-cluster.sh
 create mode 100755 packages/system/capi-providers/scripts/debug-proxmox-cluster.sh
 create mode 100644 packages/system/capi-providers/templates/proxmox-examples.yaml

diff --git a/packages/system/capi-providers/README.md b/packages/system/capi-providers/README.md
new file mode 100644
index 00000000..a841a04a
--- /dev/null
+++ b/packages/system/capi-providers/README.md
@@ -0,0 +1,166 @@
+# Cluster API Providers
+
+This directory contains configurations for various Cluster API providers.
+
+## Proxmox Integration
+
+### Requirements
+- Kubernetes cluster
+- Proxmox VE server
+- Access to Proxmox API
+- Installed Cluster API
+
+### Configuration
+
+1. Enable Proxmox provider in your configuration:
+
+```yaml
+providers:
+  proxmox: true
+```
+
+2. Ensure you have the necessary secrets for Proxmox access:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: proxmox-credentials
+  namespace: default
+type: Opaque
+stringData:
+  username: your-proxmox-username
+  password: your-proxmox-password
+  url: https://your-proxmox-server:8006/api2/json
+```
+
+### Usage
+
+1. Create a cluster:
+
+```yaml
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: Cluster
+metadata:
+  name: my-proxmox-cluster
+spec:
+  infrastructureRef:
+    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+    kind: ProxmoxCluster
+    name: my-proxmox-cluster
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+kind: ProxmoxCluster
+metadata:
+  name: my-proxmox-cluster
+spec:
+  server: your-proxmox-server
+  insecure: false
+  controlPlaneEndpoint:
+    host: your-load-balancer-host
+    port: 6443
+```
+
+2. Create a machine:
+
+```yaml
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: Machine
+metadata:
+  name: my-proxmox-machine
+spec:
+  bootstrap:
+    configRef:
+      apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
+      kind: KubeadmConfig
+      name: my-proxmox-machine
+  infrastructureRef:
+    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+    kind: ProxmoxMachine
+    name: my-proxmox-machine
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+kind: ProxmoxMachine
+metadata:
+  name: my-proxmox-machine
+spec:
+  nodeName: your-proxmox-node
+  template: ubuntu-2004-template
+  cores: 2
+  memory: 4096
+  diskSize: 20
+```
+
+### Debugging
+
+The project includes two scripts for debugging Proxmox integration:
+
+1. `create-proxmox-cluster.sh`:
+   - Creates a cluster with built-in debugging capabilities
+   - Checks provider status
+   - Monitors cluster creation progress
+   - Provides detailed logs on failure
+
+2. `debug-proxmox-cluster.sh`:
+   - Interactive debugging menu
+   - Color-coded output
+   - Comprehensive checks for:
+     - Cluster API providers status
+     - Cluster resources
+     - Provider logs
+     - Machine logs
+     - Proxmox connection
+     - Cluster events
+
+#### Debugging Commands
+
+1. Check provider status:
+```bash
+kubectl get pods -n capi-proxmox-system
+```
+
+2. Check provider logs:
+```bash
+kubectl logs -n capi-proxmox-system -l control-plane=controller-manager
+```
+
+3. Check machine status:
+```bash
+kubectl get machines -A
+```
+
+4. Check events:
+```bash
+kubectl get events --field-selector involvedObject.kind=ProxmoxMachine
+```
+
+5. Check Proxmox connection:
+```bash
+kubectl get secret proxmox-credentials
+```
+
+#### Common Issues and Solutions
+
+1. Provider Pod Issues:
+   - Check if the pod is running: `kubectl get pods -n capi-proxmox-system`
+   - Check pod logs: `kubectl logs -n capi-proxmox-system <pod-name>`
+   - Verify Proxmox credentials in the secret
+
+2. Machine Creation Issues:
+   - Check machine status: `kubectl get machines -A`
+   - Check Proxmox machine status: `kubectl get proxmoxmachines -A`
+   - Verify VM template exists in Proxmox
+
+3. Connection Issues:
+   - Verify Proxmox URL is accessible
+   - Check credentials in the secret
+   - Ensure Proxmox API is enabled and accessible
+
+### Known Limitations
+- Only Linux systems are supported
+- A pre-created VM template is required
+- Only qemu/kvm virtual machines are supported
+
+### Additional Information
+- [Official cluster-api-provider-proxmox documentation](https://github.com/ionos-cloud/cluster-api-provider-proxmox)
+- [Cluster API documentation](https://cluster-api.sigs.k8s.io/) 
\ No newline at end of file
diff --git a/packages/system/capi-providers/scripts/create-proxmox-cluster.sh b/packages/system/capi-providers/scripts/create-proxmox-cluster.sh
new file mode 100755
index 00000000..99b0210f
--- /dev/null
+++ b/packages/system/capi-providers/scripts/create-proxmox-cluster.sh
@@ -0,0 +1,107 @@
+#!/bin/bash
+
+# Debug functions
+debug_log() {
+    echo "[DEBUG] $(date '+%Y-%m-%d %H:%M:%S') - $1"
+}
+
+check_provider_status() {
+    debug_log "Checking Cluster API provider status..."
+    kubectl get pods -n capi-system
+    kubectl get pods -n capi-kubeadm-bootstrap-system
+    kubectl get pods -n capi-kubeadm-control-plane-system
+    kubectl get pods -n capi-proxmox-system
+}
+
+check_cluster_status() {
+    debug_log "Checking cluster status..."
+    kubectl get clusters -A
+    kubectl get machines -A
+    kubectl get proxmoxclusters -A
+    kubectl get proxmoxmachines -A
+}
+
+check_provider_logs() {
+    debug_log "Checking provider logs..."
+    for namespace in capi-system capi-kubeadm-bootstrap-system capi-kubeadm-control-plane-system capi-proxmox-system; do
+        echo "=== Logs from $namespace ==="
+        kubectl logs -n $namespace -l control-plane=controller-manager --tail=100
+    done
+}
+
+check_machine_logs() {
+    debug_log "Checking machine logs..."
+    kubectl get machines -A -o wide
+    for machine in $(kubectl get machines -A -o jsonpath='{.items[*].metadata.name}'); do
+        echo "=== Logs for machine $machine ==="
+        kubectl logs -n default -l cluster.x-k8s.io/machine-name=$machine --tail=100
+    done
+}
+
+# Check if required environment variables are set
+required_vars=(
+  "PROXMOX_USERNAME"
+  "PROXMOX_PASSWORD"
+  "PROXMOX_URL"
+  "PROXMOX_SERVER"
+  "PROXMOX_NODE"
+  "VM_TEMPLATE"
+  "KUBERNETES_VERSION"
+  "LOAD_BALANCER_HOST"
+)
+
+for var in "${required_vars[@]}"; do
+  if [ -z "${!var}" ]; then
+    echo "Error: Required environment variable $var is not set"
+    exit 1
+  fi
+done
+
+# Create a temporary directory for processed manifests
+TEMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TEMP_DIR"' EXIT
+
+# Process the manifests with environment variables
+debug_log "Processing manifests..."
+envsubst < templates/proxmox-examples.yaml > "$TEMP_DIR/processed-manifests.yaml"
+
+# Apply the manifests
+debug_log "Applying Cluster API manifests..."
+kubectl apply -f "$TEMP_DIR/processed-manifests.yaml"
+
+# Initial status check
+debug_log "Performing initial status check..."
+check_provider_status
+check_cluster_status
+
+echo "Waiting for cluster to be ready..."
+kubectl wait --for=condition=ready cluster/proxmox-cluster --timeout=300s || {
+    debug_log "Cluster failed to become ready. Checking logs..."
+    check_provider_logs
+    check_machine_logs
+    check_cluster_status
+    exit 1
+}
+
+debug_log "Cluster is ready. Final status check..."
+check_provider_status
+check_cluster_status
+
+echo "Cluster creation completed. You can monitor the progress with:"
+echo "kubectl get clusters"
+echo "kubectl get machines"
+echo "kubectl get proxmoxclusters"
+echo "kubectl get proxmoxmachines"
+
+# Add debug commands
+echo -e "\nDebug commands:"
+echo "1. Check provider logs:"
+echo "   kubectl logs -n capi-proxmox-system -l control-plane=controller-manager"
+echo "2. Check machine status:"
+echo "   kubectl get machines -A -o wide"
+echo "3. Check cluster status:"
+echo "   kubectl get clusters -A"
+echo "4. Check Proxmox provider status:"
+echo "   kubectl get proxmoxclusters -A"
+echo "5. Check Proxmox machines:"
+echo "   kubectl get proxmoxmachines -A" 
\ No newline at end of file
diff --git a/packages/system/capi-providers/scripts/debug-proxmox-cluster.sh b/packages/system/capi-providers/scripts/debug-proxmox-cluster.sh
new file mode 100755
index 00000000..02c3ec0b
--- /dev/null
+++ b/packages/system/capi-providers/scripts/debug-proxmox-cluster.sh
@@ -0,0 +1,128 @@
+#!/bin/bash
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+# Debug functions
+debug_log() {
+    echo -e "${YELLOW}[DEBUG] $(date '+%Y-%m-%d %H:%M:%S') - $1${NC}"
+}
+
+error_log() {
+    echo -e "${RED}[ERROR] $(date '+%Y-%m-%d %H:%M:%S') - $1${NC}"
+}
+
+success_log() {
+    echo -e "${GREEN}[SUCCESS] $(date '+%Y-%m-%d %H:%M:%S') - $1${NC}"
+}
+
+# Check Cluster API providers
+check_providers() {
+    debug_log "Checking Cluster API providers..."
+    echo "=== Core Provider ==="
+    kubectl get pods -n capi-system -l control-plane=controller-manager
+    
+    echo -e "\n=== Bootstrap Provider ==="
+    kubectl get pods -n capi-kubeadm-bootstrap-system -l control-plane=controller-manager
+    
+    echo -e "\n=== Control Plane Provider ==="
+    kubectl get pods -n capi-kubeadm-control-plane-system -l control-plane=controller-manager
+    
+    echo -e "\n=== Proxmox Provider ==="
+    kubectl get pods -n capi-proxmox-system -l control-plane=controller-manager
+}
+
+# Check cluster resources
+check_resources() {
+    debug_log "Checking cluster resources..."
+    echo "=== Clusters ==="
+    kubectl get clusters -A -o wide
+    
+    echo -e "\n=== Machines ==="
+    kubectl get machines -A -o wide
+    
+    echo -e "\n=== Proxmox Clusters ==="
+    kubectl get proxmoxclusters -A -o wide
+    
+    echo -e "\n=== Proxmox Machines ==="
+    kubectl get proxmoxmachines -A -o wide
+}
+
+# Check provider logs
+check_provider_logs() {
+    debug_log "Checking provider logs..."
+    for namespace in capi-system capi-kubeadm-bootstrap-system capi-kubeadm-control-plane-system capi-proxmox-system; do
+        echo "=== Logs from $namespace ==="
+        kubectl logs -n $namespace -l control-plane=controller-manager --tail=100
+    done
+}
+
+# Check machine logs
+check_machine_logs() {
+    debug_log "Checking machine logs..."
+    for machine in $(kubectl get machines -A -o jsonpath='{.items[*].metadata.name}'); do
+        echo "=== Logs for machine $machine ==="
+        kubectl logs -n default -l cluster.x-k8s.io/machine-name=$machine --tail=100
+    done
+}
+
+# Check Proxmox connection
+check_proxmox_connection() {
+    debug_log "Checking Proxmox connection..."
+    kubectl get secret proxmox-credentials -o jsonpath='{.data.url}' | base64 -d
+    echo -e "\nChecking Proxmox provider pods..."
+    kubectl get pods -n capi-proxmox-system -o wide
+}
+
+# Check events
+check_events() {
+    debug_log "Checking events..."
+    echo "=== Cluster Events ==="
+    kubectl get events --field-selector involvedObject.kind=Cluster
+    
+    echo -e "\n=== Machine Events ==="
+    kubectl get events --field-selector involvedObject.kind=Machine
+    
+    echo -e "\n=== ProxmoxCluster Events ==="
+    kubectl get events --field-selector involvedObject.kind=ProxmoxCluster
+    
+    echo -e "\n=== ProxmoxMachine Events ==="
+    kubectl get events --field-selector involvedObject.kind=ProxmoxMachine
+}
+
+# Main menu
+while true; do
+    echo -e "\n${YELLOW}Proxmox Cluster API Debug Menu${NC}"
+    echo "1. Check Cluster API providers"
+    echo "2. Check cluster resources"
+    echo "3. Check provider logs"
+    echo "4. Check machine logs"
+    echo "5. Check Proxmox connection"
+    echo "6. Check events"
+    echo "7. Run all checks"
+    echo "8. Exit"
+    
+    read -p "Select an option (1-8): " option
+    
+    case $option in
+        1) check_providers ;;
+        2) check_resources ;;
+        3) check_provider_logs ;;
+        4) check_machine_logs ;;
+        5) check_proxmox_connection ;;
+        6) check_events ;;
+        7)
+            check_providers
+            check_resources
+            check_provider_logs
+            check_machine_logs
+            check_proxmox_connection
+            check_events
+            ;;
+        8) exit 0 ;;
+        *) echo "Invalid option" ;;
+    esac
+done 
\ No newline at end of file
diff --git a/packages/system/capi-providers/templates/proxmox-examples.yaml b/packages/system/capi-providers/templates/proxmox-examples.yaml
new file mode 100644
index 00000000..b206b5b7
--- /dev/null
+++ b/packages/system/capi-providers/templates/proxmox-examples.yaml
@@ -0,0 +1,121 @@
+---
+# 1. Create a secret for Proxmox credentials
+apiVersion: v1
+kind: Secret
+metadata:
+  name: proxmox-credentials
+  namespace: default
+type: Opaque
+stringData:
+  username: ${PROXMOX_USERNAME}
+  password: ${PROXMOX_PASSWORD}
+  url: ${PROXMOX_URL}
+---
+# 2. Create a cluster
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: Cluster
+metadata:
+  name: proxmox-cluster
+spec:
+  infrastructureRef:
+    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+    kind: ProxmoxCluster
+    name: proxmox-cluster
+---
+# 3. Define Proxmox cluster infrastructure
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+kind: ProxmoxCluster
+metadata:
+  name: proxmox-cluster
+spec:
+  server: ${PROXMOX_SERVER}
+  insecure: false
+  controlPlaneEndpoint:
+    host: ${LOAD_BALANCER_HOST}
+    port: 6443
+---
+# 4. Create a control plane machine
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: Machine
+metadata:
+  name: proxmox-control-plane
+  labels:
+    cluster.x-k8s.io/control-plane: "true"
+spec:
+  version: ${KUBERNETES_VERSION}
+  bootstrap:
+    configRef:
+      apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
+      kind: KubeadmConfig
+      name: proxmox-control-plane
+  infrastructureRef:
+    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+    kind: ProxmoxMachine
+    name: proxmox-control-plane
+---
+# 5. Define Proxmox machine infrastructure for control plane
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+kind: ProxmoxMachine
+metadata:
+  name: proxmox-control-plane
+spec:
+  nodeName: ${PROXMOX_NODE}
+  template: ${VM_TEMPLATE}
+  cores: 2
+  memory: 4096
+  diskSize: 20
+---
+# 6. Create a worker machine
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: Machine
+metadata:
+  name: proxmox-worker
+spec:
+  version: ${KUBERNETES_VERSION}
+  bootstrap:
+    configRef:
+      apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
+      kind: KubeadmConfig
+      name: proxmox-worker
+  infrastructureRef:
+    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+    kind: ProxmoxMachine
+    name: proxmox-worker
+---
+# 7. Define Proxmox machine infrastructure for worker
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+kind: ProxmoxMachine
+metadata:
+  name: proxmox-worker
+spec:
+  nodeName: ${PROXMOX_NODE}
+  template: ${VM_TEMPLATE}
+  cores: 2
+  memory: 4096
+  diskSize: 20
+---
+# 8. Define Kubeadm configuration for control plane
+apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
+kind: KubeadmConfig
+metadata:
+  name: proxmox-control-plane
+spec:
+  clusterConfiguration:
+    apiServer:
+      extraArgs:
+        cloud-provider: external
+  initConfiguration:
+    nodeRegistration:
+      kubeletExtraArgs:
+        cloud-provider: external
+---
+# 9. Define Kubeadm configuration for worker
+apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
+kind: KubeadmConfig
+metadata:
+  name: proxmox-worker
+spec:
+  joinConfiguration:
+    nodeRegistration:
+      kubeletExtraArgs:
+        cloud-provider: external 
\ No newline at end of file