bazbeans 0.1.0

Generic Multi-Node Control Plane Toolkit

BazBeans - Generic Multi-Node Control Plane Toolkit

Orchestrate distributed applications with ease - A reusable toolkit for managing multi-node deployments with automatic health monitoring, load balancer integration, and centralized control.

🎯 What is BazBeans?

BazBeans is a generic control plane toolkit that helps you manage distributed applications across multiple servers. Think of it as the "operating system" for your cluster - it handles the hard parts of distributed coordination so you can focus on your application.

🚀 Key Capabilities

• 🏥 Self-Healing Nodes - Nodes monitor their own health and automatically remove themselves from the load balancer when unhealthy
• 🎛️ Centralized Control - Manage your entire cluster from a simple command-line interface
• ⚡ Auto Load Balancing - Automatic Nginx upstream updates via Redis pub/sub
• 🔌 Pluggable Architecture - Add custom health checks, commands, and IP resolution strategies
• 🔄 Zero Project Coupling - Generic design works with any application stack

🛤️ Choose Your Path (30 seconds)

🎮 I want to manage existing nodes

Goal: Control and monitor a running cluster Start: CLI Setup Guide → 5-minute setup

🤖 I want to deploy new agents

Goal: Add BazBeans agents to my applications Start: Agent Deployment Guide → Production-ready setup

⚡ I want to try it right now

Goal: Quick test on my local machine Start: Quick Start Guide → 5-minute working demo

📚 I want to understand how it works

Goal: Learn the architecture and concepts Start: Architecture Guide → Deep dive

---

🚀 Quick Start (5 minutes)

Get a working cluster in under 5 minutes:

# 1. Start Redis
redis-server

# 2. Install BazBeans
pip install bazbeans

# 3. Run a test agent
python -c "
from bazbeans import BazBeansConfig, NodeAgent
config = BazBeansConfig(redis_url='redis://localhost:6379/0', node_id='test-node')
NodeAgent(config).run()
" &

# 4. Manage your cluster
bazbeans list-nodes
bazbeans status test-node

⚠️ Note: For production deployment, see the Agent Deployment Guide

---

🏗️ Architecture Overview

graph TB
    subgraph "Control Plane"
        CLI[CLI Interface]
        Redis[(Redis Server)]
    end
    
    subgraph "Data Center 1"
        N1[Node Agent 1]
        N2[Node Agent 2]
    end
    
    subgraph "Data Center 2"
        N3[Node Agent 3]
        N4[Node Agent 4]
    end
    
    subgraph "Load Balancer"
        LB[Nginx Updater]
    end
    
    CLI --> Redis
    N1 --> Redis
    N2 --> Redis
    N3 --> Redis
    N4 --> Redis
    Redis --> LB
    
    N1 -.-> |Health Check| N1
    N2 -.-> |Health Check| N2
    N3 -.-> |Health Check| N3
    N4 -.-> |Health Check| N4

Core Components

Component	Purpose	Key Features
NodeAgent	Runs on each server	Health monitoring, command handling, self-management
ControlCLI	Administrative interface	Cluster management, node control, file deployment
NginxUpdater	Load balancer integration	Automatic upstream updates, IP resolution
NodePool	Redis state management	Heartbeats, status tracking, command queues

---

🎯 Use Cases

🌐 Web Application Clusters

# Perfect for FastAPI, Django, Flask applications
# Automatic health checks and load balancer updates
# Rolling updates with zero downtime

📦 Microservices Management

# Manage containerized services
# Docker-compose integration included
# Custom health checks per service

🔄 Background Job Processing

# Monitor Celery, RQ, or custom job queues
# Auto-freeze unhealthy workers
# Centralized job queue management

🏢 Enterprise Applications

# Multi-datacenter deployments
# Custom command handlers for business logic
# Integration with existing monitoring systems

---

🛠️ Configuration Examples

Basic Web Server Setup

from bazbeans import BazBeansConfig, NodeAgent, DockerComposeCommands

config = BazBeansConfig(
    redis_url="redis://cluster-redis:6379/0",
    node_id="web-server-01",
    data_center="us-east-1",
    node_port=8000,
    cpu_threshold=85,
    memory_threshold=80
)

agent = NodeAgent(config)
agent.register_command_plugin(DockerComposeCommands(config))

# Add web-specific health check
@agent.health_check
def check_web_health():
    import requests
    return requests.get("http://localhost:8000/health").status_code == 200

agent.run()

Database Server Setup

config = BazBeansConfig(
    redis_url="redis://cluster-redis:6379/0",
    node_id="db-server-01",
    data_center="us-east-1",
    cpu_threshold=95,  # Higher threshold for databases
    memory_threshold=90
)

agent = NodeAgent(config)

# Add database-specific health checks
@agent.health_check
def check_database():
    # Your database connection logic
    return database.is_connected()

@agent.health_check
def check_replication():
    # Check replication lag
    return database.replication_lag() < 10

agent.run()

---

🎮 CLI Commands

Node Management

# List all nodes with health status
bazbeans list-nodes

# Get detailed node information
bazbeans status web-server-01

# Freeze a node (remove from load balancer)
bazbeans freeze web-server-01 --reason "maintenance"

# Unfreeze a node
bazbeans unfreeze web-server-01

Service Control

# Start services on a node
bazbeans start web-server-01

# Stop services
bazbeans stop web-server-01

# Restart services
bazbeans restart web-server-01

# Rolling update across datacenter
bazbeans update --dc us-east-1

Operations

# Execute commands on nodes
bazbeans exec web-server-01 "docker ps"

# Deploy files to nodes
bazbeans deploy-file web-server-01 ./config.yaml /opt/app/config.yaml

# Clean up dead nodes
bazbeans cleanup

---

🔌 Extensibility

Custom Health Checks

@agent.health_check
def check_custom_service():
    """Check if your custom service is healthy."""
    try:
        # Your health check logic
        return service.ping()
    except:
        return False

@agent.health_check
def check_disk_space():
    """Custom disk space check."""
    import psutil
    return psutil.disk_usage('/app').percent < 95

Custom Command Handlers

@agent.command_handler("backup")
def handle_backup(command):
    """Handle backup commands."""
    # Your backup logic
    return {"status": "backup_started", "timestamp": time.time()}

@agent.command_handler("custom_action")
def handle_custom(command):
    """Handle custom business logic."""
    # Your custom logic
    return {"status": "completed", "result": "success"}

IP Resolution Strategies

from bazbeans.ip_resolvers import (
    RedisIPResolver,      # Nodes self-register IPs
    DNSIPResolver,        # DNS lookup
    StaticIPResolver,     # Static mapping
    ChainedIPResolver     # Primary + fallback
)

# Choose your strategy
resolver = ChainedIPResolver(
    primary=RedisIPResolver(redis_client),
    fallback=StaticIPResolver({"emergency-ip": "10.0.1.100"})
)

---

📊 System Requirements

Minimum Requirements

• Python: 3.8 or higher
• Memory: 512MB per node
• Disk: 100MB free space
• Network: Port 6379 (Redis) accessible

Recommended for Production

• Python: 3.9+ with virtual environment
• Memory: 1GB+ per node
• Redis: Dedicated server with persistence
• Network: Private network or VPN
• Security: Redis AUTH + TLS

Platform Support

• ✅ Linux (Ubuntu, CentOS, Debian)
• ✅ macOS (development only)
• ✅ Windows (development only)
• ✅ Docker containers
• ✅ Kubernetes (with custom setup)

---

🔒 Security Considerations

Redis Security

# Enable Redis authentication
requirepass your-secure-password

# Use TLS in production
tls-port 6380
tls-cert-file /path/to/redis.crt
tls-key-file /path/to/redis.key

# Network isolation
bind 10.0.1.10 127.0.0.1

Agent Security

# Run as non-root user
# Use virtual environments
# Validate file paths
# Whitelist allowed commands
config.allowed_exec_prefixes = ["docker", "systemctl", "ls"]

Network Security

• Use VPN or private networks
• Implement firewall rules
• Monitor for unauthorized access
• Regular security audits

---

📚 Documentation

Getting Started

• Quick Start Guide - 5-minute setup
• CLI Setup Guide - Install management tools
• Agent Deployment Guide - Production deployment

Advanced Topics

• Architecture Guide - System design and components
• Troubleshooting Guide - Common issues and solutions
• Examples - Integration patterns and samples

Reference

• Configuration Reference - All configuration options
• CLI Command Reference - Complete command list
• API Documentation - Programmatic usage

---

🆘 Getting Help

Self-Service

• Troubleshooting Guide - Step-by-step problem solving
• FAQ - Common questions
• Examples - Working code samples

Community

• GitHub Issues - Bug reports and feature requests
• Discussions - Questions and best practices
• Wiki - Community-contributed content

Enterprise Support

• Priority support channels
• Custom integration assistance
• Architecture consulting
• Training sessions

---

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

---

📄 License

This toolkit is designed to be generic and reusable across projects. Please adapt and extend as needed for your specific use case.

---

🎯 Next Steps

1. New Users: Start with Quick Start Guide
2. Production Setup: Read Agent Deployment Guide
3. Custom Integration: See Examples folder
4. Deep Understanding: Review Architecture Guide

---

⏱️ Time to First Value: 5 minutes with Quick Start
🎯 Primary Goal: Simplify distributed application management
🔧 Approach: Generic, pluggable, production-ready toolkit