Uncloud follows a hybrid intent/runtime architecture where SQLite stores what the user requested (intent) and Kubernetes holds the actual running state (runtime truth). A sync loop reconciles the two every 15 seconds.
System Overview
Core Design Principles
Hybrid DB/K8s Model
Intent Layer
SQLite stores what the user requested — resource names, configs, and relationships.
Runtime Layer
Kubernetes holds what’s actually running — IPs, pod phases, and ready replicas.
Sync Layer
Go goroutine reconciles every 15 seconds between intent and runtime.
- The API is fast — reads from SQLite, not the K8s API
- Kubernetes is the source of truth for running state
- If K8s is temporarily unreachable, the API still serves data
- New resources are created in SQLite first, then provisioned to K8s
Resource Lifecycle
Tech Stack
Backend
| Component | Technology |
|---|---|
| Language | Go 1.21 |
| HTTP Router | Chi v5 |
| Database | SQLite (modernc.org) |
| K8s Client | client-go v0.28 |
| VM Engine | KubeVirt |
| Storage | Rook/Ceph |
| Networking | Cilium |
| DB Operator | CloudNativePG |
| Metrics | Prometheus |
Frontend
| Component | Technology |
|---|---|
| Framework | React 19 + TypeScript |
| Build Tool | Vite 7 |
| Styling | Tailwind CSS |
| Components | shadcn/ui + Radix |
| Charts | Recharts |
| Routing | React Router v7 |
Backend Architecture
Layer Structure
| Directory | Purpose |
|---|---|
cmd/api/ | Entrypoint |
internal/api/ | HTTP handlers + router |
internal/services/ | Business logic |
internal/repository/ | SQLite data access |
internal/k8s/ | Kubernetes operations |
internal/sync/ | DB/K8s reconciliation |
internal/domain/ | Domain models |
internal/provisioner/ | Infra installers |
Domain Models
Resources use prefixed IDs for clarity:| Resource | Prefix | Example |
|---|---|---|
| Project | proj_ | proj_default |
| Droplet | dpl_ | dpl_a1b2c3d4 |
| Volume | vol_ | vol_e5f6g7h8 |
| App | app_ | app_i9j0k1l2 |
| Database | db_ | db_m3n4o5p6 |
| SSH Key | sk_ | sk_q7r8s9t0 |
Multi-Tenancy
Projects are the isolation boundary. Each project maps to a Kubernetes namespace. All resources are scoped to a project viaproject_id.
Project: production
- Droplet
web-server - App
api-service - Database
main-pg - Volume
data-vol
productionProject: staging
- Droplet
test-vm - App
api-staging - Database
staging-pg
stagingKubernetes Integration
Resource Mapping
| Uncloud | Kubernetes |
|---|---|
| Droplet (VM) | KubeVirt VirtualMachine |
| Volume | PersistentVolumeClaim |
| App | Deployment + Service + Ingress |
| Database | StatefulSet or operator CR |
| Project | Namespace |
| Firewall | Cilium NetworkPolicy |
| Quota | ResourceQuota |
Provisioner System
Infrastructure components installed via admin setup:| Component | What It Does |
|---|---|
| K3s | Lightweight Kubernetes |
| KubeVirt | VM management via CRDs |
| Storage Class | PV provisioner (Ceph/Longhorn) |
| Metrics Server | CPU and memory metrics |
| Prometheus | Monitoring and alerting |
| CloudNativePG | PostgreSQL operator |
| Registry | Private image storage |
| CoreDNS | DNS resolution |
| Object Storage | S3-compatible buckets |