RustSwarm

A production-grade Rust rewrite of Docker Swarm (SwarmKit), built entirely with modern Rust ecosystem technologies.

What is RustSwarm?

RustSwarm is a distributed container orchestration platform that provides the same functionality as Docker Swarm, reimplemented from the ground up in Rust. It enables you to manage a cluster of Docker engines, deploy services, and orchestrate containerized applications across multiple nodes with fault-tolerant consensus and automatic scheduling.

Key Features

• Distributed Consensus – Multi-node Raft cluster with automatic leader election and fault tolerance
• Service Orchestration – Declarative service management with replicated and global deployment modes
• Automatic Scheduling – Constraint-aware task placement across cluster nodes
• High Availability – Survives node failures with automatic task rescheduling
• Persistent State – Durable storage with automatic recovery across restarts
• gRPC API – Full-featured control plane API compatible with SwarmKit protocols
• Docker Integration – Native Docker container execution via bollard

Architecture

RustSwarm follows a manager-worker architecture:

• Manager Nodes – Form a Raft consensus cluster, maintain cluster state, and make scheduling decisions
• Worker Nodes – Execute tasks (containers) and report status back to managers
• Raft Consensus – Ensures all managers have consistent view of cluster state
• Task Scheduler – Automatically assigns tasks to nodes based on resources and constraints

Technology Stack

Core Technologies

• Rust 1.90+ – Systems programming language with memory safety
• OpenRaft 0.9 – Raft consensus implementation
• Tokio – Async runtime for concurrent operations
• Tonic – gRPC framework for network communication
• Sled – Embedded database for persistent storage
• Bollard – Docker API client for container management

Additional Dependencies

• Bincode – Binary serialization for Raft messages
• Protobuf – API definitions (SwarmKit-compatible)
• Clap – Command-line argument parsing
• Tracing – Structured logging and diagnostics

Project Structure

rustswarm/
├── crates/
│   ├── swarm-core/         # Data model, state management, and scheduler
│   ├── swarm-consensus/    # Raft integration and distributed consensus
│   ├── swarm-manager/      # Control plane (gRPC APIs, orchestration)
│   ├── swarm-agent/        # Worker node agent (task execution)
│   ├── swarm-node/         # Node-specific state view
│   ├── swarm-cli/          # Command-line interface and binaries
│   ├── swarm-proto/        # Protobuf definitions and generated code
│   └── swarm-store/        # Persistent storage layer
├── proto/                  # SwarmKit protobuf files
├── docs/                   # Architecture and deployment documentation
└── docker-swarm-reference/ # Original SwarmKit (Go) for reference

Crate Descriptions

• swarm-core – Core data model (nodes, services, tasks, networks, secrets, configs), state management with change notifications, and constraint-based spread scheduler
• swarm-consensus – Raft consensus layer with OpenRaft integration, sled-backed log/state storage, and command replication
• swarm-manager – Manager node implementation with Control and Dispatcher gRPC services, orchestration loop, and cluster reconciliation
• swarm-agent – Worker node agent with Docker executor, task lifecycle management, status reporting, and persistence
• swarm-node – Lightweight read-only view of node-specific cluster state
• swarm-cli – Binary entry points for demo mode and manager/agent processes
• swarm-proto – Tonic-generated gRPC bindings from SwarmKit protobuf definitions
• swarm-store – Sled-backed snapshot store for cluster state persistence

Requirements

• Rust 1.90 or later (MSRV tracks stable channel)
• Docker (for running containers via the agent)
• No system protoc required – protoc-bin-vendored provides the compiler during build

Getting Started

Quick Start (Demo Mode)

Run an in-memory demo to explore RustSwarm without persistence:

cargo run -p swarm-cli -- demo

This starts an interactive demo that creates services, schedules tasks, and demonstrates the orchestration loop.

Single-Node Manager

Start a manager node with persistence and gRPC API:

cargo run -p swarm-cli -- manager

Default configuration:

• gRPC endpoint: 127.0.0.1:50051
• State directory: ./.rustswarm/state/
• Mode: Single-node Raft cluster

Custom configuration:

cargo run -p swarm-cli -- manager \
  --bind 0.0.0.0:50051 \
  --state-dir /var/lib/rustswarm

Multi-Node Cluster

Bootstrap a new cluster (first manager):

cargo run -p swarm-cli -- manager \
  --cluster-mode \
  --bootstrap \
  --node-id 1 \
  --raft-addr 192.168.1.10:50051 \
  --bind 192.168.1.10:50051 \
  --state-dir /var/lib/rustswarm/node1

Join existing cluster (additional managers):

# Manager 2
cargo run -p swarm-cli -- manager \
  --cluster-mode \
  --join 192.168.1.10:50051 \
  --node-id 2 \
  --raft-addr 192.168.1.11:50051 \
  --bind 192.168.1.11:50051 \
  --state-dir /var/lib/rustswarm/node2

# Manager 3
cargo run -p swarm-cli -- manager \
  --cluster-mode \
  --join 192.168.1.10:50051 \
  --node-id 3 \
  --raft-addr 192.168.1.12:50051 \
  --bind 192.168.1.12:50051 \
  --state-dir /var/lib/rustswarm/node3

For detailed deployment instructions, see docs/MULTI_NODE_DEPLOYMENT.md.

Testing

Run All Tests

cargo test

Run Tests for Specific Crate

cargo test -p swarm-core
cargo test -p swarm-consensus
cargo test -p swarm-manager

Run Multi-Node Integration Tests

cargo test -p swarm-consensus --test multi_node_cluster

Code Quality Checks

# Format code
cargo fmt --all

# Run linter
cargo clippy --all-targets --all-features

# Check for issues
cargo check --all-targets --all-features

Build Release Binary

cargo build --release -p swarm-cli

The binary will be available at target/release/swarm-cli.

Documentation

• Architecture Overview – Raft consensus architecture and data flow
• Multi-Node Deployment – Production deployment guide
• Troubleshooting – Common issues and debugging

License

This project is a clean-room implementation inspired by Docker SwarmKit. See the original SwarmKit project at github.com/moby/swarmkit.

Contributing

This is a production-grade rewrite following SwarmKit’s design. When contributing:

1. Consult docker-swarm-reference/ for design and behavior reference
2. Write tests first for new functionality
3. Ensure all tests pass before submitting
4. Follow Rust best practices and idioms

Acknowledgments

RustSwarm is inspired by and compatible with Docker SwarmKit, the original Go implementation of Docker Swarm mode.