rustfs/crates/madmin

RustFS MadAdmin - Administrative Interface

Administrative interface and management APIs for RustFS distributed object storage

📖 Documentation · 🐛 Bug Reports · 💬 Discussions

---

📖 Overview

RustFS MadAdmin provides comprehensive administrative interfaces and management APIs for the RustFS distributed object storage system. It enables cluster management, monitoring, configuration, and administrative operations through both programmatic APIs and interactive interfaces.

Note: This is a core submodule of RustFS that provides essential administrative capabilities for the distributed object storage system. For the complete RustFS experience, please visit the main RustFS repository.

✨ Features

🎛️ Cluster Management

• Node Management: Add, remove, and monitor cluster nodes
• Service Discovery: Automatic service discovery and registration
• Load Balancing: Distribute load across cluster nodes
• Health Monitoring: Real-time cluster health monitoring

📊 System Monitoring

• Performance Metrics: CPU, memory, disk, and network metrics
• Storage Analytics: Capacity planning and usage analytics
• Alert Management: Configurable alerts and notifications
• Dashboard Interface: Web-based monitoring dashboard

⚙️ Configuration Management

• Dynamic Configuration: Runtime configuration updates
• Policy Management: Access control and bucket policies
• User Management: User and group administration
• Backup Configuration: Backup and restore settings

🔧 Administrative Operations

• Data Migration: Cross-cluster data migration
• Healing Operations: Data integrity repair and healing
• Rebalancing: Storage rebalancing operations
• Maintenance Mode: Graceful maintenance operations

📦 Installation

Add this to your Cargo.toml:

[dependencies]
rustfs-madmin = "0.1.0"

🔧 Usage

Basic Admin Client

use rustfs_madmin::{AdminClient, AdminConfig, ServerInfo};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create admin client
    let config = AdminConfig {
        endpoint: "https://admin.rustfs.local:9001".to_string(),
        access_key: "admin".to_string(),
        secret_key: "password".to_string(),
        region: "us-east-1".to_string(),
    };

    let client = AdminClient::new(config).await?;

    // Get server information
    let server_info = client.server_info().await?;
    println!("Server Version: {}", server_info.version);
    println!("Uptime: {}", server_info.uptime);

    Ok(())
}

Cluster Management

use rustfs_madmin::{AdminClient, AddServerRequest, RemoveServerRequest};

async fn cluster_management(client: &AdminClient) -> Result<(), Box<dyn std::error::Error>> {
    // List cluster nodes
    let nodes = client.list_servers().await?;
    for node in nodes {
        println!("Node: {} - Status: {}", node.endpoint, node.state);
    }

    // Add new server to cluster
    let add_request = AddServerRequest {
        endpoint: "https://new-node.rustfs.local:9000".to_string(),
        access_key: "node-key".to_string(),
        secret_key: "node-secret".to_string(),
    };

    client.add_server(add_request).await?;
    println!("New server added successfully");

    // Remove server from cluster
    let remove_request = RemoveServerRequest {
        endpoint: "https://old-node.rustfs.local:9000".to_string(),
    };

    client.remove_server(remove_request).await?;
    println!("Server removed successfully");

    Ok(())
}

System Monitoring

use rustfs_madmin::{AdminClient, MetricsRequest, AlertConfig};

async fn monitoring_operations(client: &AdminClient) -> Result<(), Box<dyn std::error::Error>> {
    // Get system metrics
    let metrics = client.get_metrics(MetricsRequest::default()).await?;

    println!("CPU Usage: {:.2}%", metrics.cpu_usage);
    println!("Memory Usage: {:.2}%", metrics.memory_usage);
    println!("Disk Usage: {:.2}%", metrics.disk_usage);

    // Get storage information
    let storage_info = client.storage_info().await?;
    println!("Total Capacity: {} GB", storage_info.total_capacity / 1024 / 1024 / 1024);
    println!("Used Capacity: {} GB", storage_info.used_capacity / 1024 / 1024 / 1024);

    // Configure alerts
    let alert_config = AlertConfig {
        name: "high-cpu-usage".to_string(),
        condition: "cpu_usage > 80".to_string(),
        notification_endpoint: "https://webhook.example.com/alerts".to_string(),
        enabled: true,
    };

    client.set_alert_config(alert_config).await?;

    Ok(())
}

User and Policy Management

use rustfs_madmin::{AdminClient, UserInfo, PolicyDocument};

async fn user_management(client: &AdminClient) -> Result<(), Box<dyn std::error::Error>> {
    // Create user
    let user_info = UserInfo {
        access_key: "user123".to_string(),
        secret_key: "user-secret".to_string(),
        status: "enabled".to_string(),
        policy: Some("readwrite-policy".to_string()),
    };

    client.add_user("new-user", user_info).await?;

    // List users
    let users = client.list_users().await?;
    for (username, info) in users {
        println!("User: {} - Status: {}", username, info.status);
    }

    // Set user policy
    let policy_doc = PolicyDocument {
        version: "2012-10-17".to_string(),
        statement: vec![/* policy statements */],
    };

    client.set_user_policy("new-user", policy_doc).await?;

    Ok(())
}

Data Operations

use rustfs_madmin::{AdminClient, HealRequest, RebalanceRequest};

async fn data_operations(client: &AdminClient) -> Result<(), Box<dyn std::error::Error>> {
    // Start healing operation
    let heal_request = HealRequest {
        bucket: Some("important-bucket".to_string()),
        prefix: Some("documents/".to_string()),
        recursive: true,
        dry_run: false,
    };

    let heal_result = client.heal(heal_request).await?;
    println!("Healing started: {}", heal_result.heal_sequence);

    // Check healing status
    let heal_status = client.heal_status(&heal_result.heal_sequence).await?;
    println!("Healing progress: {:.2}%", heal_status.progress);

    // Start rebalancing
    let rebalance_request = RebalanceRequest {
        servers: vec![], // Empty means all servers
    };

    client.start_rebalance(rebalance_request).await?;
    println!("Rebalancing started");

    Ok(())
}

Configuration Management

use rustfs_madmin::{AdminClient, ConfigUpdate, NotificationTarget};

async fn configuration_management(client: &AdminClient) -> Result<(), Box<dyn std::error::Error>> {
    // Get current configuration
    let config = client.get_config().await?;
    println!("Current config version: {}", config.version);

    // Update configuration
    let config_update = ConfigUpdate {
        region: Some("us-west-2".to_string()),
        browser: Some(true),
        compression: Some(true),
        // ... other config fields
    };

    client.set_config(config_update).await?;

    // Configure notification targets
    let notification_target = NotificationTarget {
        arn: "arn:aws:sns:us-east-1:123456789012:my-topic".to_string(),
        target_type: "webhook".to_string(),
        endpoint: "https://webhook.example.com/notifications".to_string(),
    };

    client.set_notification_target("bucket1", notification_target).await?;

    Ok(())
}

🏗️ Architecture

MadAdmin Architecture

MadAdmin Architecture:
┌─────────────────────────────────────────────────────────────┐
│                    Admin API Layer                          │
├─────────────────────────────────────────────────────────────┤
│   Cluster Mgmt   │   Monitoring    │   User Management      │
├─────────────────────────────────────────────────────────────┤
│   Data Ops       │   Config Mgmt   │   Notification         │
├─────────────────────────────────────────────────────────────┤
│              HTTP/gRPC Client Layer                         │
├─────────────────────────────────────────────────────────────┤
│              Storage System Integration                      │
└─────────────────────────────────────────────────────────────┘

Administrative Operations

Category	Operations	Description
Cluster	Add/Remove nodes, Health checks	Cluster management
Monitoring	Metrics, Alerts, Dashboard	System monitoring
Data	Healing, Rebalancing, Migration	Data operations
Config	Settings, Policies, Notifications	Configuration
Users	Authentication, Authorization	User management

🧪 Testing

Run the test suite:

# Run all tests
cargo test

# Test admin operations
cargo test admin_ops

# Test cluster management
cargo test cluster

# Test monitoring
cargo test monitoring

📋 Requirements

• Rust: 1.70.0 or later
• Platforms: Linux, macOS, Windows
• Network: Administrative access to RustFS cluster
• Permissions: Administrative credentials required

🌍 Related Projects

This module is part of the RustFS ecosystem:

• RustFS Main - Core distributed storage system
• RustFS IAM - Identity and access management
• RustFS Policy - Policy engine
• RustFS Common - Common types and utilities

📚 Documentation

For comprehensive documentation, visit:

• RustFS Documentation
• MadAdmin API Reference
• Administrative Guide

🔗 Links

• Documentation - Complete RustFS manual
• Changelog - Release notes and updates
• GitHub Discussions - Community support

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

---

RustFS is a trademark of RustFS, Inc.
All other trademarks are the property of their respective owners.

Made with 🎛️ by the RustFS Team