Zhengchao An
87d47a6e5d
Add a per-backend rotation-driver matrix to docs/operations/kms-backend-security.md: who performs the rotation on each backend (RustFS for Vault KV2, Vault's Transit engine for Transit, AWS RotateKeyOnDemand for AWS, nobody for Local/Static), how periodic rotation must be scheduled on each (external scheduler for KV2 by design, Vault auto_rotate_period for Transit, AWS-native automatic rotation for AWS since RotateKeyOnDemand carries a lifetime quota), the NIST SP 800-38D 2^32 random-nonce AES-GCM wrap ceiling that Local/Static can never reset, and a pre-rotation checklist referencing the existing upgrade-ordering hard constraint. Add the KmsKeyRotationOverdue Prometheus rule on rustfs_kms_oldest_key_rotation_age_seconds (400-day conservative default, warning severity, no traffic guard because it is direct gauge state) and its runbook response procedure in docs/operations/kms-observability-runbook.md, following the existing per-alert format. Sharpen the runbook's rotation-timestamp paragraph with verified per-backend behavior: only Vault KV2 persists rotated_at (stamped in the same check-and-set write that commits the rotation), while Transit and AWS key listings always report it absent, so on those backends the gauge measures key age and does not reset on rotation. Update Threshold calibration and Coverage gaps for the new rule. Validated with promtool check rules (7 rules, SUCCESS) and scripts/check_doc_paths.sh. Part of rustfs/backlog#1636 (PR-4).
RustFS Docker Infrastructure
This directory contains the complete Docker infrastructure for building, deploying, and monitoring RustFS. It provides ready-to-use configurations for development, testing, and production-grade observability.
📂 Directory Structure
| Directory | Description | Status |
|---|---|---|
observability/ |
[RECOMMENDED] Full-stack observability (Prometheus, Grafana, Tempo, Loki). | ✅ Production-Ready |
compose/ |
Specialized setups (e.g., 4-node distributed cluster testing). | ⚠️ Testing Only |
mqtt/ |
EMQX Broker configuration for MQTT integration testing. | 🧪 Development |
openobserve-otel/ |
Alternative lightweight observability stack using OpenObserve. | 🔄 Alternative |
📄 Root Directory Files
The following files in the project root are essential for Docker operations:
Build Scripts & Dockerfiles
| File | Description | Usage |
|---|---|---|
docker-buildx.sh |
Multi-Arch Build Script Automates building and pushing Docker images for amd64 and arm64. Supports release and dev channels. |
./docker-buildx.sh --push |
Dockerfile |
Production Image (Alpine) Lightweight image using musl libc. Downloads pre-built binaries from GitHub Releases. |
docker build -t rustfs:latest . |
Dockerfile.glibc |
Production Image (Ubuntu) Standard image using glibc. Useful if you need specific dynamic libraries. |
docker build -f Dockerfile.glibc . |
Dockerfile.source |
Development Image Builds RustFS from source code. Includes build tools. Ideal for local development and CI. |
docker build -f Dockerfile.source . |
Docker Compose Configurations
| File | Description | Usage |
|---|---|---|
docker-compose.yml |
Main Development Setup Comprehensive setup with profiles for development, observability, and proxying. |
docker compose up -ddocker compose --profile observability up -d |
docker-compose-simple.yml |
Quick Start Setup Minimal configuration running a single RustFS instance with 4 volumes. Perfect for first-time users. |
docker compose -f docker-compose-simple.yml up -d |
🌟 Observability Stack (Recommended)
Located in: .docker/observability/
We provide a comprehensive, industry-standard observability stack designed for deep insights into RustFS performance. This is the recommended setup for both development and production monitoring.
Components
- Metrics: Prometheus (Collection) + Grafana (Visualization)
- Traces: Tempo (Storage) + Jaeger (UI)
- Logs: Loki
- Ingestion: OpenTelemetry Collector
Key Features
- Full Persistence: All metrics, logs, and traces are saved to Docker volumes, ensuring no data loss on restarts.
- Correlation: Seamlessly jump between Logs, Traces, and Metrics in Grafana.
- High Performance: Optimized configurations for batching, compression, and memory management.
Quick Start
cd .docker/observability
docker compose up -d
🧪 Specialized Environments
Located in: .docker/compose/
These configurations are tailored for specific testing scenarios that require complex topologies.
Distributed Cluster (4-Nodes)
Simulates a real-world distributed environment with 4 RustFS nodes running locally.
docker compose -f .docker/compose/docker-compose.cluster.yaml up -d
Integrated Observability Test
A self-contained environment running 4 RustFS nodes alongside the full observability stack. Useful for end-to-end testing of telemetry.
docker compose -f .docker/compose/docker-compose.observability.yaml up -d
📡 MQTT Integration
Located in: .docker/mqtt/
Provides an EMQX broker for testing RustFS MQTT features.
Quick Start
cd .docker/mqtt
docker compose up -d
- Dashboard: http://localhost:18083 (Default:
admin/public) - MQTT Port:
1883
👁️ Alternative: OpenObserve
Located in: .docker/openobserve-otel/
For users preferring a lightweight, all-in-one solution, we support OpenObserve. It combines logs, metrics, and traces into a single binary and UI.
Quick Start
cd .docker/openobserve-otel
docker compose up -d
🔧 Common Operations
Cleaning Up
To stop all containers and remove volumes (WARNING: deletes all persisted data):
docker compose down -v
Viewing Logs
To follow logs for a specific service:
docker compose logs -f [service_name]
Checking Status
To see the status of all running containers:
docker compose ps