​
Provisioner System

The provisioner automates the installation of infrastructure components required by Uncloud. Access it through the Admin Setup page in the dashboard or via the API.

​
How It Works

Each infrastructure component has a provisioner that can:
  • Check — Verify if the component is installed and running
  • Install — Download and configure the component
The provisioner uses kubectl to apply manifests and verify resource status.

​
Components

​
K3s

Lightweight Kubernetes distribution. The foundation for all other components.
  • What it installs: K3s server and agent
  • Check: Verifies kubectl cluster-info succeeds
  • Notes: If using an existing cluster, skip this step

​
KubeVirt

Virtual machine management via CRDs. Required for Droplets.
  • What it installs: KubeVirt operator and CR
  • Check: Verifies KubeVirt pods are running
  • Prerequisites: K3s or existing Kubernetes cluster
  • Resources created:
    • kubevirt namespace
    • KubeVirt operator Deployment
    • KubeVirt CR

​
Storage Class

Persistent volume provisioner. Required for volumes, databases, and VM disks.
  • What it installs: Default StorageClass (Longhorn or Rook/Ceph)
  • Check: Verifies a StorageClass exists with default annotation
  • Notes: Configure storage.block_class in config.yaml

​
Metrics Server

Kubernetes Metrics Server for CPU and memory usage data.
  • What it installs: metrics-server Deployment
  • Check: Verifies kubectl top nodes works
  • Resources created:
    • metrics-server Deployment in kube-system

​
Prometheus

Monitoring and metrics collection.
  • What it installs: Prometheus server via Helm or manifests
  • Check: Verifies Prometheus pods are running
  • Endpoint: Accessible at PROMETHEUS_URL (default: http://localhost:30090)

​
CloudNativePG

PostgreSQL operator for managed database instances.
  • What it installs: CloudNativePG operator
  • Check: Verifies operator pod is running
  • Resources created:
    • cnpg-system namespace
    • CloudNativePG operator Deployment
    • CRDs for Cluster, Backup, ScheduledBackup

​
Container Registry

Private Docker registry for storing built application images.
  • What it installs: Docker Registry Deployment + Service
  • Check: Verifies registry pod is running
  • Notes: Used by the App Platform for git-based deployments

​
CoreDNS

DNS resolution for service discovery within the cluster.
  • What it installs: CoreDNS configuration updates
  • Check: Verifies DNS resolution works

​
Object Storage

S3-compatible object storage (MinIO or Rook/Ceph RGW).
  • What it installs: MinIO Deployment or Ceph RGW
  • Check: Verifies S3 endpoint is accessible
  • Configuration: Update storage.object in config.yaml

​
Running the Provisioner

​
Via Dashboard

  1. Navigate to Admin → Setup
  2. Each component shows its current status
  3. Click Install on individual components or Run All

​
Via API

# Check all component status
curl -X POST http://localhost:8080/api/v1/admin/setup/check

# Install all components
curl -X POST http://localhost:8080/api/v1/admin/setup/run-all

# Install a specific component
curl -X POST http://localhost:8080/api/v1/admin/setup/kubevirt/run

​
Installation Order

Components should be installed in this order (the provisioner handles dependencies automatically): 
1. K3s (or existing cluster)
   ↓
2. Storage Class
   ↓
3. Metrics Server ─── CoreDNS ─── Container Registry
   ↓
4. KubeVirt ─── CloudNativePG ─── Prometheus
   ↓
5. Object Storage

​
Troubleshooting

​
Component shows “not installed” after installing

  • Check if the component pods are running: kubectl get pods -A
  • Wait 30-60 seconds for pods to start, then re-check
  • Review pod logs: kubectl logs -n <namespace> <pod-name>

​
KubeVirt installation fails

  • Ensure hardware virtualization is enabled: egrep -c '(vmx|svm)' /proc/cpuinfo
  • Check if nested virtualization is supported (for VMs-on-VMs)
  • Review KubeVirt operator logs: kubectl logs -n kubevirt -l kubevirt.io=virt-operator

​
Storage provisioning fails

  • Verify the StorageClass exists: kubectl get storageclass
  • Check if the storage backend (Longhorn/Ceph) is healthy
  • Ensure nodes have sufficient disk space