Configuration - Uncloud

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

App Platform Configuration

Base Domain

The base_domain setting controls how apps get their default URLs:

<app-slug>.<base_domain>

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

For custom domains, configure a cert-manager ClusterIssuer:

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

​Environment Variables

​Frontend

​config.yaml

​App Platform Configuration

​Base Domain

​TLS Setup

​Storage Configuration

​Block Storage

​Object Storage

​Kubernetes Auto-Detection

​Database

​Sync Loop

Environment Variables

Frontend

config.yaml

App Platform Configuration

Base Domain

TLS Setup

Storage Configuration

Block Storage

Object Storage

Kubernetes Auto-Detection

Database

Sync Loop