vh/VuongKB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d994526207ab04d47d16f0734f29d8dc9ad40edb
VuongKB/reference/rustfs.md
T
Atlas c204f1d934 Create: reference/rustfs.md
2026-04-15 20:58:55 -07:00

14 KiB
Raw Blame History

created, id, keywords, links, modified, summary, tags, title
created id keywords links modified summary tags title
2026-04-16T03:58:55+00:00 c724b70a-3a92-4527-82a8-22a64533adee
RustFS
object storage
S3 compatible
Rust
erasure coding
Reed-Solomon
distributed storage
docker
kubernetes
MinIO client
mc
AWS S3 SDK
Apache 2.0
Blake3
Rayon
AVX2
WORM
federation
multi-cloud gateway
SNSD
SNMD
MNMD
2026-04-16T03:58:55+00:00 Comprehensive reference for RustFS, a high-performance distributed object storage system written in Rust. Covers architecture, installation, S3 compatibility, erasure coding, SDKs, management, and usage limits.
rustfs
object-storage
s3
distributed-storage
docker
kubernetes
rust
devops
reference
RustFS — High-Performance Distributed Object Storage

id: reference/rustfs title: "RustFS — High-Performance Distributed Object Storage" created: 2025-07-10 modified: 2025-07-10 tags:

  • rustfs
  • object-storage
  • s3
  • distributed-storage
  • docker
  • kubernetes
  • rust
  • devops
  • reference keywords:
  • RustFS
  • object storage
  • S3 compatible
  • Rust
  • erasure coding
  • Reed-Solomon
  • distributed storage
  • docker
  • kubernetes
  • MinIO client
  • mc
  • AWS S3 SDK
  • Apache 2.0
  • Blake3
  • Rayon
  • AVX2
  • WORM
  • federation
  • multi-cloud gateway
  • SNSD
  • SNMD
  • MNMD links:
  • "reference/docker-compose"

RustFS — High-Performance Distributed Object Storage

Official documentation: https://docs.rustfs.com License: Apache 2.0 (commercially friendly) Repository: git@github.com:rustfs/rustfs.git Docker image: rustfs/rustfs

RustFS is a high-performance, distributed object storage solution designed for simplicity and efficiency. Fully compatible with the S3 protocol, it is open-source software built with Rust — leveraging industry-leading memory safety and zero-cost abstractions to deliver exceptional performance comparable to C/C++.

It serves as a modern alternative to legacy object storage solutions, offering a robust platform for data-intensive applications.

Table of Contents

Overview & Features

Feature Detail
S3 Compatible Fully compatible with the S3 API (V2 and V4)
Distributed Architecture Horizontal scaling, symmetric nodes
License Apache v2.0 — commercially friendly
Language Rust — memory safety, zero-cost abstractions
Performance Comparable to C/C++
Security Rust memory safety guarantees, TLS, AES-256-GCM, KMS integration
Cross-Platform Linux, macOS, Windows, FreeBSD, Docker, edge gateways
Extensible Plugin architecture
Cloud-Native Docker and Kubernetes optimized
Single Binary ~100 MB static binary

Vision: Provide the storage foundation for the AI era, enabling every personal AI agent to securely store and access data.

Architecture

RustFS uses a fully symmetric architecture — all servers are functionally equal. There are no name nodes or metadata servers. Data and metadata are written atomically. Key architectural characteristics:

  • One process per node with lightweight coroutines for high concurrency.
  • Erasure sets group drives (default: 16 drives/set) with deterministic hashing for object placement.
  • Inline operations: erasure coding, bitrot checking, and encryption are strictly consistent — applied before the write acknowledgment is returned.
  • Single-layer software-defined design running on industry-standard hardware (JBOD/JBOF commodity servers).
  • Lightweight containers suitable for Kubernetes deployment.
  • Multi-datacenter support: each tenant runs an isolated cluster; independent scaling via federation across geographies.

S3 Ports

Port Purpose
9000 S3 API
9001 Console UI

Installation

Deployment Modes

RustFS supports three installation modes, each suited to different scales:

Mode Abbreviation Use Case Redundancy
Single Node, Single Disk SNSD Local testing, small-scale None — zero erasure coding
Single Node, Multiple Disk SNMD Development, moderate workloads Erasure coding across local disks
Multiple Node, Multiple Disk MNMD Enterprise-grade production Full erasure coding + distributed redundancy

Pre-installation checks are recommended. RustFS runs on almost any CPU/OS (x86, ARM).

Docker Quick Start

Prerequisites: Docker ≥ 20.10, port 9000 open.

docker pull rustfs/rustfs

docker run -d \
  --name rustfs_local \
  -p 9000:9000 \
  -p 9001:9001 \
  -v /mnt/rustfs/data:/data \
  rustfs/rustfs:latest \
  /data

The container runs as a non-root user rustfs (UID 10001).

Environment Variables

Variable Default Description
RUSTFS_ADDRESS :9000 S3 API bind address
RUSTFS_SERVER_DOMAINS — Server domain(s)
RUSTFS_ACCESS_KEY rustfsadmin Access key
RUSTFS_SECRET_KEY rustfsadmin Secret key
RUSTFS_CONSOLE_ENABLE true Enable Console UI on port 9001

Command-line parameters are also supported and take higher priority than environment variables.

Docker Compose Deployment

For the full Docker Compose reference, see Docker Compose Deployment.

# Clone the repository
git clone git@github.com:rustfs/rustfs.git

# Start with observability stack (Grafana, Prometheus, Jaeger, OpenTelemetry Collector)
docker compose --profile observability up -d

# Start RustFS only (no observability)
docker compose -f docker-compose.yml up -d rustfs

The observability profile starts: rustfs-server, Grafana, Prometheus, Jaeger, and otel-collector.

Default Credentials

Method Username Password
Environment variables rustfsadmin rustfsadmin
Some documentation rustfsadmin ChangeMe123!

TLS Support

Mount certificates and set RUSTFS_TLS_PATH to enable TLS.

Production Recommendations

  • Deploy multi-node for redundancy and performance.
  • Enable TLS for all connections.
  • Configure log rotation.
  • Establish a backup strategy.
  • Use local SSD/NVMe storage.
  • Avoid NFS — use direct-attached storage.

S3 Compatibility

RustFS maintains strict adherence to S3 API standards, supporting API V2 and V4 with location-independent compatibility across:

  • Public cloud
  • Private cloud
  • Data center
  • Multi-cloud
  • Hybrid cloud
  • Edge deployments

Core S3 Features

  • S3 Select: SIMD-optimized queries on CSV, Parquet, and JSON data.
  • AWS Signature Version 4: Policy-based access control compatible with AWS IAM.
  • Broad ecosystem support: GitHub/GitLab, MongoDB, ClickHouse, MariaDB, CockroachDB, Teradata, KubeFlow, TensorFlow.

Erasure Coding

RustFS uses Reed-Solomon (RS) Code based on finite field algebraic structures.

Key Parameters

Parameter Meaning
k Original data shards
m Parity shards
n Total shards (k + m)

Any k of n shards are sufficient to recover the original data. Recovery uses Gaussian elimination or FFT.

Example: RS(10, 4)

  • Fault tolerance: 4 nodes
  • Storage utilization: 71% (vs 33% for triple replication)

RustFS Implementation Details

Component Detail
Shard size Dynamic, 64 KB – 4 MB
Hash checksum Blake3 algorithm
Parallel encoding Rayon framework + AVX2 SIMD instructions
Finite field GF(2⁸) with generator polynomial 0x11D
Tiering Runtime (k, m) adjustment for hot/warm/cold tiers
Max parity N/2

Bare Metal & Virtualized Deployment

RustFS is software-defined, runs on industry-standard hardware, and requires no special storage appliances.

Key Capabilities

Feature Detail
Bitrot Protection HighwayHash, READ/WRITE verification, >10 GB/s hash speed on single core
Server-Side Encryption AES-256-GCM, ChaCha20-Poly1305, AES-CBC; AEAD encryption; KMS integration (HashiCorp Vault); SSE-S3 support
WORM Write Once Read Many — disables all mutation APIs; for regulatory compliance
Identity Management OpenID Connect, external IdP integration, temporary rotated passwords, fine-grained access policies
Continuous Replication Lambda-based notifications for immediate change propagation; cross-datacenter, multi-vendor
Global Federation Unified namespace across distributed mode sets; unlimited mode sets per federation; single console administration
Multi-Cloud Gateway S3 API view regardless of data location; makes non-S3 storage appear S3-compatible

Enterprise Features

  • Object Lock & Read-Only: Compliance and governance modes.
  • Cross-Region Replication: Active-active and active-passive.
  • Version Control: Configurable version limits.
  • Lifecycle Management: Automated tiering and expiration policies.
  • Log Management: Structured logging with observability integration.
  • Encryption: At-rest and in-transit with KMS support.

SDKs & Client Libraries

Management Interfaces

  1. Console UI — web-based (port 9001)
  2. MinIO Client (mc) — CLI tool
  3. SDKs — programmatic access

Available SDKs

Language Recommended SDK
Java Official AWS S3 SDK for Java
JavaScript Official AWS S3 SDK for JavaScript
Python Official AWS S3 SDK for Python (boto3)
Rust Official AWS S3 SDK for Rust
TypeScript Official AWS S3 SDK for TypeScript
Golang Official AWS S3 SDK for Go

Recommendation: Use the official AWS S3 SDKs — they are mature, well-maintained, and highly optimized. RustFS is fully compatible. Fully compatible with MinIO SDKs as well (just change Endpoint, AK, SK). Avoid non-S3-compliant third-party SDKs.

MinIO Client (mc) Reference

Setup

mc alias set rustfs http://12.34.56.78:9000 ACCESS_KEY SECRET_KEY

Common Operations

mc ls rustfs                              # List buckets
mc mb rustfs/mybucket                     # Create bucket
mc rb rustfs/mybucket                     # Delete bucket
mc cp localfile.txt rustfs/mybucket       # Upload object
mc rm rustfs/mybucket/localfile.txt       # Delete object
mc get rustfs/mybucket/localfile.txt .    # Download object

Quick Verification

mc alias set rustfs http://localhost:9000 rustfsadmin ChangeMe123!
mc mb rustfs/mybucket
mc ls rustfs

Usage Limits

S3 API Limits

Resource Limit
Max object size 5 TiB
Min object size 0 B
Single PUT max (non-multipart) 500 GiB
Multipart upload max 5 TiB
Max parts per upload 10,000
Part size range 5 MiB – 5 GiB (last part: 0 – 5 GiB)
Max list objects per request 1,000
Bucket name max length 63 characters
Object name max length 1,024 characters
Object name segment max (per /) 255 characters
Max versions per object 10,000 (configurable)

Erasure Coding Limits

Resource Limit
Max servers per cluster No hard limit
Max drives per server No hard limit
Min servers 1 (SNSD — no redundancy)
Read quorum N/2
Write quorum (N/2) + 1

Naming Conventions

  • Production recommendation: Linux + XFS filesystem.
  • Avoid special characters on Windows.
  • Do not create objects whose names conflict with parent or sibling prefixes.

Platform & OS Support

Platform Supported
Linux ✅
Unix ✅
Windows ✅
macOS ✅
FreeBSD ✅
Docker ✅
Edge gateways ✅

CPU architectures: x86, ARM, and others.

Documentation Map

Reference structure of the official RustFS documentation at https://docs.rustfs.com:

Installation

Performance

  • Comparison, Design Architecture, Terminology, Usage Limits

Core Concepts

Management

  • Bucket (creation/deletion)
  • Object (upload/deletion/scanner)
  • IAM (access tokens)
  • Upgrade / Expansion / Uninstallation
  • Troubleshooting: Disk Failure, Object Healing, Node Failure

Integration

  • Nginx Reverse Proxy
  • Virtual Host Mode
  • TLS Configuration

Developer

Features

Solutions

  • Modern Data Lake
  • AI / ML
  • Cloud Native
  • Big Data — Compute/Storage Separation
  • SQL Support
  • Quantitative Trading
  • Manufacturing Cost Reduction
  • Cold Archive
  • Video Storage
  • Domestic Innovation

Related

  • Docker Compose Deployment — Docker Compose deployment patterns and configuration reference, including the RustFS observability stack.

Source: https://docs.rustfs.com — official RustFS documentation.

Reference in New Issue View Git Blame Copy Permalink