Deployment Overview

Rūsternetes supports three deployment modes: a full compose cluster with etcd, a lighter compose cluster with SQLite (via Rhino), and a single all-in-one binary that embeds every component in one process. Choose the mode that matches your needs.

Deployment Modes at a Glance

Architecture: Full Cluster (etcd)

The standard deployment runs each Kubernetes component as a separate container, communicating over an internal bridge network. etcd provides distributed, consistent state storage with support for watches and transactions.

        

          
          
          
          full cluster architecture
        
        
# Compose: Full Cluster with etcd

  +-----------------------------------------------------+
  |                rusternetes-net (bridge)              |
  |                                                     |
  |  +-----------+   +-----------+   +---------------+  |
  |  |   etcd    |   |api-server |   | controller-   |  |
  |  |  :2379    |   |  :6443    |   | manager       |  |
  |  +-----------+   +-----------+   +---------------+  |
  |                        |                            |
  |              +---------+---------+                  |
  |              |                   |                  |
  |  +-----------+---+   +----------+----+              |
  |  | scheduler     |   | kube-proxy   |              |
  |  +---------------+   | (host net)   |              |
  |                       +--------------+              |
  |  +---------------+   +---------------+              |
  |  | kubelet       |   | kubelet       |              |
  |  | (node-1)      |   | (node-2)      |              |
  |  +---------------+   +---------------+              |
  +-----------------------------------------------------+

      

Architecture: SQLite Cluster (Rhino)

Replaces etcd with Rhino, an etcd-compatible gRPC server backed by SQLite. The API server and all other components connect to Rhino exactly as they would to etcd. The entire cluster state lives in a single SQLite file.

        

          
          
          
          sqlite cluster architecture
        
        
# Compose: SQLite Cluster with Rhino

  +-----------------------------------------------------+
  |                rusternetes-net (bridge)              |
  |                                                     |
  |  +-----------+   +-----------+   +---------------+  |
  |  |  rhino    |   |api-server |   | controller-   |  |
  |  |  :2379    |   |  :6443    |   | manager       |  |
  |  | (sqlite)  |   +-----------+   +---------------+  |
  |  +-----------+         |                            |
  |              +---------+---------+                  |
  |              |                   |                  |
  |  +-----------+---+   +----------+----+              |
  |  | scheduler     |   | kube-proxy   |              |
  |  +---------------+   | (host net)   |              |
  |                       +--------------+              |
  |  +---------------+   +---------------+              |
  |  | kubelet       |   | kubelet       |              |
  |  | (node-1)      |   | (node-2)      |              |
  |  +---------------+   +---------------+              |
  +-----------------------------------------------------+

      

Architecture: All-in-One Binary

Every component runs as a concurrent tokio task inside a single Rust process. Storage is an embedded SQLite database (no network hop). The binary still requires a container runtime (Podman or Docker) for running pod containers, but the Kubernetes control plane itself is entirely self-contained.

        

          
          
          
          all-in-one architecture
        
        
# Single Process: All-in-One Binary

  +---------------------------------------------------+
  |              rusternetes (single binary)           |
  |                                                   |
  |  +-------------+  +-----------+  +--------------+ |
  |  | api-server  |  | scheduler |  | controller-  | |
  |  | (axum)      |  | (task)    |  | manager      | |
  |  +------+------+  +-----------+  | (31 ctrl)    | |
  |         |                        +--------------+ |
  |  +------+------+  +-----------+                   |
  |  | kubelet     |  | kube-proxy|                   |
  |  | (task)      |  | (task)    |                   |
  |  +-------------+  +-----------+                   |
  |         |                                         |
  |  +------+------+                                  |
  |  | SQLite      |  # embedded, no network hop       |
  |  | (rhino)     |                                  |
  |  +-------------+                                  |
  +---------------------------------------------------+
         |
  +------+------+
  | Container   |  # Podman/Docker API for pod containers
  +-------------+

      

Decision Guide

Use this flowchart to pick the right deployment mode for your use case.

Choose the Full Cluster (etcd) when:

• You need high availability with leader election and etcd replication
• You are running a multi-node cluster with 2 or more kubelets
• You need production-grade state storage with proven durability
• You want the architecture closest to upstream Kubernetes
• You are running conformance tests against the full K8s e2e suite

Choose the SQLite Cluster (Rhino) when:

• You want a multi-node cluster without the overhead of etcd
• You want simpler operations — state is a single file you can backup with cp
• You are running in resource-constrained environments where etcd's memory footprint is too large
• You don't need high availability (single point of failure is acceptable)
• You want to inspect state directly with sqlite3

Choose the All-in-One Binary when:

• You want the simplest possible setup — one binary, one command
• You are running on edge devices, IoT hardware, or air-gapped environments
• You need a Kubernetes API for CI/CD pipelines or integration testing
• You are building a sandbox environment (like OpenShell) that embeds Kubernetes
• You want the smallest resource footprint (~200 MB RAM)
• You are a developer who wants to hack on the codebase without compose

Quick Comparison