# Rusternetes: a Kubernetes reimplementation written in Rust

> Rusternetes is a ground-up Rust reimplementation of the Kubernetes control plane and node components, spanning 10 crates and 31 controllers, with an embedded web console. It is aimed at small and edge deployments where a full cluster is more than you need, and it reports 94 percent conformance against the official Kubernetes e2e suite.

**calfonso/rusternetes** — kubernetes, reimplemented in Rust

- Repository: https://github.com/calfonso/rusternetes
- Website: https://calfonso.github.io/rusternetes/
- Stars: 774 · Forks: 58
- Language: Rust
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/calfonso-rusternetes

## What Rusternetes reimplements rather than wraps

The project describes itself as a ground-up reimplementation of Kubernetes in Rust, and it goes out of its way to rule out the cheaper options. The README states that it is not a wrapper around the Go codebase and not a partial mock, and that every component, naming the API server, scheduler, controller manager, kubelet and kube-proxy, is written from scratch in Rust while implementing the actual Kubernetes API surface, wire format and behavioural semantics.

The scale claim is specific: 216,000+ lines of Rust across 10 crates, 31 controllers and 3,100+ tests. The conformance claim is more useful for an adopter, since the README says the project is actively conformance-tested against the official Kubernetes e2e test suite and currently passes 94 percent of conformance tests, which it puts at 415 of 441 across 160 rounds of testing. That figure comes from the project's own README, so it is a self-reported number rather than an independent measurement.

The workspace in Cargo.toml confirms the structure. Ten members are listed: api-server, scheduler, controller-manager, kubelet, kube-proxy, kubectl, common, storage, cloud-providers and rusternetes itself, with a workspace version of 0.1.0 and edition 2021. The dependency set shows the shape of the implementation: axum and tower-http for HTTP, tonic and prost for gRPC, bollard as the Docker API client, rustls with the aws-lc-rs provider for TLS, jsonwebtoken for token handling, and Prometheus plus OpenTelemetry instrumentation.

## The embedded web console shipped inside the API server

A built-in web console is one of the more unusual choices here, because it deploys with the cluster rather than as a separate install. The README states that it is embedded in the API server and that no separate installation is needed, and that it offers real-time cluster topology visualisation, live metrics, pod log streaming and full resource management.

The console panels are broken out in the README: an Overview with health rings, sparkline charts, deployment rollout progress and an event feed; a Topology view with an animated node, pod and service map, traffic particles, a CPU heatmap and protocol badges; Workloads with a pod phase chart and deployment cards showing scale and restart state; Networking covering the service CIDR, DNS, kube-proxy configuration and service routing diagrams; Storage for capabilities, StorageClass provisioning and PVC and PV management; Nodes with CPU and memory gauges taken from real Docker stats plus cordon and uncordon controls; Config for ConfigMaps, Secrets and Service Accounts; Events with a frequency histogram and type and reason filtering; and RBAC with subject to role mapping, binding visualisation and rule badges.

Node metrics are described as coming from real Docker stats, which is worth noting because it means the console is reading the container runtime rather than only the API objects. The README points to a Console User Guide at docs/CONSOLE_USER_GUIDE.md for the full documentation, and the repository includes a console/ directory alongside the docs.

## Three deployment shapes from one codebase

The architecture diagram in the README splits the system into a control plane of API server, scheduler and controller manager over a storage layer, plus node components comprising the kubelet and kube-proxy. From that the README derives three supported deployment modes.

A full cluster with etcd is described as the standard production deployment, with separate containers per component backed by an etcd cluster using Raft consensus and leader election. The compose file shows the shape: an etcd service running quay.io/coreos/etcd:v3.5.17 with client and peer ports 2379 and 2380, auto compaction set to periodic at 10m retention, and an api-server service that depends on etcd reaching a healthy state before starting, exposing port 6443 with TLS certificates mounted read-only from ./.rusternetes/certs and the Docker socket mounted so the API server can exec and attach into pods through bollard.

The second mode swaps the database. Rhino, described as an etcd-compatible gRPC server written in Rust that stores everything in SQLite, Redis, PostgreSQL or MySQL, can replace etcd, with the README noting that the same Kubernetes API and same binaries are used and only the compose file changes.

The third is a single binary in a single process, with all five components running as concurrent tokio tasks over an embedded SQLite or Redis backend and no external infrastructure. The all-in-one mode is aimed at environments where a full cluster is overkill: edge devices, CI and CD pipelines, local development, IoT gateways, embedded systems and air-gapped environments. The repository carries matching files for these paths, including Dockerfile.all-in-one, compose.all-in-one.yml, compose.all-in-one-redis.yml, compose.sqlite.yml, compose.redis.yml and docker-compose.ha.yml.

## Bringing up a full cluster with Podman and etcd

The quick start for a full cluster with Podman and etcd runs through clone, certificate generation, compose, bootstrap and then a plain kubectl check. The first block does the setup and starts a cluster.

```bash
git clone https://github.com/calfonso/rusternetes.git
cd rusternetes
bash scripts/generate-certs.sh
cp kubeconfig.example.yaml ~/.kube/rusternetes-config
export KUBELET_VOLUMES_PATH=$(pwd)/.rusternetes/volumes
podman compose build
podman compose up -d
bash scripts/bootstrap-cluster.sh
```

After that the kubeconfig is pointed at the cluster and the node list is checked before anything else is created.

```bash
export KUBECONFIG=~/.kube/rusternetes-config
kubectl get nodes
kubectl create deployment nginx --image=nginx
```

The expected result of the last two commands is a node list showing the joined node and a deployment object named nginx.

The equivalent Docker Compose path swaps the runtime commands for docker compose build and docker compose -f docker-compose.yml up -d, and the README notes that the SQLite variant needs no recompilation because the same binaries are reused.

```bash
podman compose -f compose.sqlite.yml build
podman compose -f compose.sqlite.yml up -d
```

Prerequisites are Rust on latest stable installed through rustup, a Protocol Buffers compiler described as required for building the API server, and a container runtime of Docker or Podman. The protobuf install is given per platform, for example sudo apt install -y protobuf-compiler on Debian and Ubuntu, brew install protobuf on macOS, and sudo dnf install -y protobuf-compiler protobuf-devel on Fedora and RHEL.

## Where Rusternetes is the wrong choice

The obvious boundary is upstream Kubernetes itself, and the conformance number marks it: 415 of 441 official e2e conformance tests pass, so 26 tests do not. A production cluster that depends on those behaviours, or on a managed control plane, on cloud provider integrations beyond the crate named cloud-providers, or on admission webhooks with a specific upstream implementation, should stay on upstream Kubernetes.

The second limitation is maturity versus velocity. The repository's last push was on 2026-10-20, and the Cargo workspace version is 0.1.0, so the project moves fast and is explicitly pre-1.0. Fast movement is fine for a CI runner that gets rebuilt weekly and awkward for a fleet whose clusters must behave identically for years.

The third limitation is the dependency on a container runtime on the node side. The kubelet talks to Docker through bollard and the kube-proxy does iptables routing for ClusterIP, NodePort and load balancer services, which means the node needs a working runtime and the right kernel networking primitives. The compose file also grants the api-server privileged mode in compose.yml, a broad permission that deserves scrutiny before it goes anywhere sensitive.

Finally, the single-binary mode is a genuine convenience, not a full cluster. It has no etcd, so no Raft consensus and no leader election, and a single SQLite file holds the entire cluster state.

## Licence, tooling and the ongoing upgrade cost

The project is under the Apache-2.0 licence, which the Cargo.toml workspace package fields confirm, where license is set to Apache-2.0 and the authors are listed as Rusternetes Contributors. Apache-2.0 permits commercial use and modification, and it requires preservation of licence and copyright notices in redistribution.

The workspace dependencies also shape what an upgrade costs. The toolchain is pinned by a rust-toolchain.toml file and the Cargo.lock is committed, so builds are reproducible. Rust, the Protocol Buffers compiler and a container runtime are all required before anything runs, and a version bump of axum, tonic, bollard or rustls can ripple into the API server and the kubelet at the same time, because these crates are shared across the workspace rather than isolated per component.

The build system wraps this in a Makefile, with a separate Dockerfile for each component (api-server, scheduler, controller-manager, kubelet, kube-proxy, kubectl, rhino) plus Dockerfile.all-in-one. Continuous integration lives in .github/, and a .env.example file documents the environment variables the compose setup expects. The repository publishes no GitHub releases, so there is no tagged artefact to pin: you build from a commit, and the compose file determines which image version ends up on your nodes.

## Conclusion

Rusternetes fits CI runners, edge devices, air-gapped sites and local development where the all-in-one binary plus embedded SQLite is enough and upstream Kubernetes is too heavy. It does not fit a production cluster that needs upstream feature parity, since the README reports 415 of 441 conformance tests passing. Before adopting it, run the SQLite compose path and check the console against the workloads you intend to run, because that path is the one with no etcd to fall back on.

## FAQ

### Is Rusternetes a wrapper around the real Kubernetes codebase?

No. The README states that it is not a wrapper around the Go codebase and not a partial mock, and that every component, including the API server, scheduler, controller manager, kubelet and kube-proxy, is written from scratch in Rust while implementing the actual Kubernetes API surface, wire format and behavioural semantics.

### How well does Rusternetes pass the Kubernetes conformance tests?

The README reports that the project is actively conformance-tested against the official Kubernetes e2e suite and currently passes 94 percent of conformance tests, which it gives as 415 of 441 across 160 rounds of testing. This is a figure reported by the project itself.

### Can Rusternetes run without etcd?

Yes. The single binary mode runs all five components as concurrent tokio tasks over an embedded SQLite or Redis backend, and the SQLite compose path replaces etcd with Rhino, an etcd-compatible gRPC server written in Rust. The README says the same binaries and Kubernetes API are used, and only the compose file changes.

### What do I need installed to build Rusternetes?

The README lists Rust on latest stable installed via rustup, a Protocol Buffers compiler because it is required for building the API server, and a container runtime, either Docker or Podman. The quick start then clones the repository, runs scripts/generate-certs.sh and bootstraps the cluster with scripts/bootstrap-cluster.sh.

## Sources

- [calfonso/rusternetes on GitHub](https://github.com/calfonso/rusternetes)
- [Issues](https://github.com/calfonso/rusternetes/issues)
- [License: Apache-2.0](https://github.com/calfonso/rusternetes/blob/main/LICENSE)
- [Project website](https://calfonso.github.io/rusternetes/)
- [README](https://github.com/calfonso/rusternetes/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/calfonso-rusternetes