Configuration
Uncloud is configured through environment variables and a config.yaml file.
Environment Variables
| Variable | Default | Description |
|---|
HTTP_PORT | 8080 | Port for the API server |
DB_PATH | data/nebula.db | SQLite database file path |
KUBECONFIG | Auto-detected | Kubernetes configuration file |
PROMETHEUS_URL | http://localhost:30090 | Prometheus server endpoint |
BUILD_CONTEXT_PATH | — | Shared PVC path for build contexts |
REGISTRY_URL | — | Docker registry for built images |
REGISTRY_SECRET_NAME | — | K8s secret for registry auth |
VULTR_KEY | — | Vultr API key (for cloud provider integration) |
ENV | development | Environment (development or production) |
Frontend
| Variable | Default | Description |
|---|
VITE_API_URL | http://localhost:8080 | Backend API endpoint |
config.yaml
The main configuration file lives at the project root:
apps:
# Base domain for app subdomains
# Apps are accessible at <slug>.<base_domain>
base_domain: go4.site
# Kubernetes Secret containing the wildcard TLS certificate
default_tls_secret_name: wildcard-cert
# cert-manager ClusterIssuer for custom domain certificates
cert_manager_cluster_issuer: letsencrypt-prod
storage:
# StorageClass for block volumes (PVCs)
block_class: ceph-rbd
# S3-compatible object storage configuration
object:
endpoint: http://127.0.0.1:9000
region: us-east-1
access_key: minioadmin
secret_key: minioadmin
bucket_prefix: nebula
Base Domain
The base_domain setting controls how apps get their default URLs:
Example with base_domain: go4.site:
- App “my-api” →
my-api.go4.site
- App “dashboard” →
dashboard.go4.site
TLS Setup
For HTTPS on the default domain, you need a wildcard TLS certificate:
# Create a wildcard cert Secret (if using cert-manager)
kubectl create secret tls wildcard-cert \
--cert=fullchain.pem \
--key=privkey.pem \
-n default
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: admin@example.com
privateKeySecretRef:
name: letsencrypt-prod
solvers:
- http01:
ingress:
class: traefik
Storage Configuration
Block Storage
Set the block_class to match your cluster’s StorageClass:
# Check available StorageClasses
kubectl get storageclass
| Provider | StorageClass |
|---|
| Rook/Ceph | ceph-rbd |
| Longhorn | longhorn |
| Local Path | local-path |
Object Storage
Configure S3-compatible storage credentials:
storage:
object:
endpoint: http://minio.storage.svc:9000
region: us-east-1
access_key: YOUR_ACCESS_KEY
secret_key: YOUR_SECRET_KEY
bucket_prefix: dkc
Kubernetes Auto-Detection
Uncloud automatically detects the Kubernetes configuration:
KUBECONFIG environment variable (highest priority)/etc/rancher/k3s/k3s.yaml (K3s default)/var/snap/microk8s/current/credentials/client.config (MicroK8s)~/.kube/config (standard kubectl config)
Database
The SQLite database is created automatically at the DB_PATH location. No configuration needed.
For production, store the database on persistent storage and include it in your backup strategy.
Sync Loop
The reconciliation loop between SQLite and Kubernetes runs every 15 seconds. This interval is not currently configurable but handles:
- Creating K8s resources for new SQLite records
- Pulling runtime status (IPs, phases, ready counts) back to SQLite
- Updating resource statuses across the system
