Backends

kobe supports multiple backends for provisioning virtual clusters. The backend is selected per pool via spec.backend.type. All backends expose the same lease API; the difference is how each ClusterInstance is provisioned and what runtime it uses. For guidance on which runtime to pick — and which are retired — see Runtime strategy.

k3s (default)

k3s clusters are managed as Kubernetes StatefulSets in the host cluster. Each cluster is a k3s server pod with an embedded SQLite datastore by default.

spec:
  backend:
    type: k3s
  cluster:
    version: v1.32.0+k3s1
    servers: 1

When to use: The default choice for most use cases. Fast to provision, low overhead, and well-tested.

Shared PostgreSQL datastore

For golden image workflows, k3s can use a shared PostgreSQL datastore instead of embedded SQLite. This enables CREATE DATABASE ... TEMPLATE to clone a pre-seeded database into new cluster pods, reducing addon setup time.

spec:
  backend:
    type: k3s
    datastore:
      secretRef: kobe-postgres-secret    # Secret with key "connection-url"
      goldenTemplates: true

The referenced Secret must contain a connection-url key with a valid PostgreSQL DSN.

k0s

k0s clusters follow the same pattern as k3s but use the k0s distribution. Use this if your workloads require k0s-specific features or you're standardizing on k0s in production.

spec:
  backend:
    type: k0s
  cluster:
    version: v1.32.0+k0s.0

CAPI (Cluster API)

The CAPI backend delegates cluster provisioning to any Cluster API infrastructure provider. kobe creates the necessary CAPI Cluster and infrastructure CRDs, then waits for the cluster to reach Ready state before adding it to the warm pool.

spec:
  backend:
    type: capi
    capi:
      infrastructureApiVersion: infrastructure.cluster.x-k8s.io/v1beta1
      infrastructureKind: DockerCluster
      infrastructureSpec:
        # Provider-specific spec, passed through as-is
        controlPlaneEndpoint:
          host: ""
          port: 6443

When to use: When you need to use an existing CAPI infrastructure provider, or when kobe's built-in backends don't support your target environment.

vcluster

The vcluster backend deploys one vcluster (loft-sh, Apache 2.0) instance per ClusterInstance via the upstream Helm chart, into a dedicated per-instance host namespace — isolating projection scope per instance and making teardown trivially correct (helm uninstall + namespace delete).

spec:
  backend:
    type: vcluster
    vcluster:
      chartVersion: ""        # optional; operator's pinned default applies when unset
      values: |               # optional; free-form vcluster chart values (YAML),
        sync:                 # merged on top of the operator's defaults
          toHost:
            ingresses:
              enabled: true

When to use: High density and low per-cluster overhead without maintaining an in-house syncer. Note that fidelity boundaries (cloud identity such as IRSA, syncer coverage, version skew) are inherited from vcluster — route tenants who need full cluster semantics to a real-cluster backend.

vkobe (on hold)

On hold. Development of vkobe and its kobe-sync runtime is paused — see Runtime strategy. Existing pools keep working; prefer vcluster for new density pools.

vkobe is kobe's in-house virtual cluster runtime. Each virtual cluster runs as a single pod containing a proxy-based kube-apiserver, an optional kube-controller-manager, and kobe-sync. It does not depend on any third-party virtual cluster runtime.

spec:
  backend:
    type: vkobe
    vkobe:
      dataStoreRef:
        name: kobe-etcd             # name of a KobeStore CRD in the same namespace
      version: "1.32"               # Kubernetes API version to expose
      syncers:
        - pods
        - services
        - configmaps
        - secrets
        - endpoints
        - ingresses
      kcm:
        controllers:
          - deployment
          - replicaset
          - statefulset
          - job
          - namespace
          - serviceaccount
          - garbagecollector

vkobe clusters share the host cluster's node pool. Pods scheduled in the virtual cluster are translated and created as host pods, making them subject to the host's resource constraints and scheduling.

When to use: When you want the lowest possible overhead per cluster, don't need full node isolation, and are comfortable with a proxy-based architecture.

KobeStore CRD

The vkobe backend requires a KobeStore CRD that points to an external etcd or kine instance:

apiVersion: kobe.kunobi.ninja/v1alpha1
kind: KobeStore
metadata:
  name: kobe-etcd
  namespace: kobe
spec:
  driver: etcd
  endpoints:
    - https://etcd.kobe.svc:2379
  tls:
    secretRef: etcd-client-certs
  capacity:
    maxClusters: 100

Comparison

	k3s	k0s	CAPI	vcluster	vkobe (on hold)
Isolation	Full	Full	Full	Namespace	Namespace
Overhead per cluster	Low	Low	Provider-dependent	Very low	Very low
Provision time	~30s	~30s	~60s+	~15s	~5s
Golden images (Velero)	Yes	Yes	Varies	No	No
Shared etcd	Via PostgreSQL	Via PostgreSQL	No	No	Yes (required)
Custom addons	Yes	Yes	Yes	Yes	Yes