Documentation

Overview

Kubaros turns your existing Proxmox VE infrastructure into a managed Kubernetes-as-a-Service platform. You install Kubaros on a VM in your network; it provisions Talos Linux clusters on Proxmox, manages public IP pools, and exposes every action through a REST API so you can wire it into your portal and billing.

Architecture

Kubaros is the control plane: a FastAPI backend (MongoDB) and a React console, fronted by Caddy for automatic HTTPS. It talks to the Proxmox VE API to create VMs and to talosctl to bootstrap Kubernetes. It governs itself locally from a signed license and only phones home to validate that license and report installation telemetry.

API-first by design: everything in the console is a documented REST endpoint, so providers can fully automate provisioning, tenant management and billing.

Reaching Talos

Kubaros supports two ways to reach the internal Talos nodes of a Proxmox site (set per site):

1) Local Appliance mode — Kubaros runs on-site and reaches the Talos node IPs directly over a management network (SDN or an existing bridge).

2) Remote Connector mode — for a centrally-hosted Kubaros, it provisions a tiny WireGuard connector VM on the Proxmox site. The connector holds one public IP (the WireGuard endpoint) and securely tunnels Kubaros into the internal, per-tenant Talos subnets. No manual setup — Kubaros generates the keys and cloud-init.

Tenant isolation: each tenant gets a dedicated VLAN and node subnet, carved from a provider supernet. Cluster pod/service CIDRs default to /16 (10.244.0.0/16 pod, 10.96.0.0/12 service) so Kubernetes never runs out of pod IPs — a /24 pod CIDR is far too small. Sizes are configurable globally and per cluster.

Installation

Install on a fresh Debian/Ubuntu VM (2 vCPU / 4 GB RAM is enough to start). The installer sets up Docker, pulls the Kubaros images and starts the stack behind Caddy.

curl -fsSL https://install.kubaros.io | sudo bash

For a production domain with a real Let's Encrypt certificate, pass your domain and ACME email:

KUBAROS_DOMAIN=console.example.com KUBAROS_ACME_EMAIL=admin@example.com \
  curl -fsSL https://install.kubaros.io | sudo -E bash

Manage Kubaros afterwards with the kubaros CLI:

kubaros status   # show containers
kubaros update   # pull the latest release
kubaros logs     # follow logs
kubaros url      # print the console URL

Prefer Kubernetes? A Helm chart is included (deploy/charts/kubaros) to run the appliance (backend + frontend + MongoDB + Redis) on your own cluster. Images are multi-arch (amd64 + arm64).

helm install kubaros ./deploy/charts/kubaros \
  --namespace kubaros --create-namespace \
  --set baseUrl=https://kubaros.example.com \
  --set ingress.host=kubaros.example.com

First steps

Open the console URL the installer prints and follow the first-run wizard:

1. 1Create your admin account in the Setup Wizard.
2. 2Connect Proxmox: paste your PVE API token — Kubaros validates the version, single-server-vs-cluster, SDN and Ceph.
3. 3Register your public IP pools per Proxmox site.
4. 4Create your first Talos cluster and download its kubeconfig.

Authentication

All API calls require a bearer token. Use the admin JWT for interactive use, or create a scoped API token (Settings → API Tokens) for automation and billing integrations.

# 1) Get a JWT
TOKEN=$(curl -s -X POST https://console.example.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"••••••"}' \
  | jq -r .access_token)

# 2) Call the API
curl -s https://console.example.com/api/clusters \
  -H "Authorization: Bearer $TOKEN"

Scoped tokens carry only the permissions you grant (e.g. usage:read, clusters:write). List available scopes via GET /api/api-tokens/scopes.

Billing modes

Kubaros supports two billing models, switchable in Settings → Billing & limits:

1. 1Fixed limits (quota): per-tenant quotas for clusters, nodes and storage are enforced; provisioning is blocked once a quota is reached.
2. 2Usage-based (pay-as-you-go): tenant limits are advisory only and never block — bill your customers from GET /api/usage/clusters.

Operations

Observability: open any cluster and switch to the Metrics tab for live per-cluster and per-node CPU, memory and pod usage. The same data is available at GET /api/clusters/{id}/metrics for your own dashboards.

etcd backups: the Backups tab takes point-in-time etcd snapshots of the control plane and restores them after a failure. Set an automatic schedule (off / daily / weekly), or trigger a manual snapshot before risky changes. Restores are disruptive and ask for confirmation.

White-label: under Settings → White-label & branding you can set the product name, a logo URL, an accent color and optionally hide the "Powered by Kubaros" line. Branding applies to the appliance console your customers log into; the public Kubaros website is unaffected.

Multiple Proxmox sites: connect as many Proxmox clusters as you like under Proxmox, then pick the default site for new clusters under Settings → Provisioning defaults.

API reference

Base URL: https://<your-console>/api · interactive Swagger UI lives in your Kubaros console at /api/docs · all responses are JSON.