MongoDB Cluster Deployment Guide

This project provides shell scripts to quickly deploy and manage MongoDB clusters, including replica sets and sharded clusters with enhanced features and beautiful output.

✨ Features

• 🚀 One-command deployment - Deploy complete clusters with a single command
• 📊 Beautiful output - Color-coded status messages and detailed information
• 🔍 Cluster monitoring - Check cluster status with the status command
• 🔌 Easy connection - Connect to clusters with automatic failover support
• 🎯 Tab completion - Full command auto-completion support
• 🔒 Hidden nodes - Automatic configuration of hidden replica set members
• ⚡ High availability - Built-in support for automatic failover

Available Scripts

1. replica_cluster.sh: Deploys and manages a MongoDB replica set cluster.
2. shard_cluster.sh: Deploys and manages a MongoDB sharded cluster.
3. run_completions.bash: Provides command completion for both scripts.

Usage

Replica Set Cluster

Quick Start

Deploy a replica set cluster (3 nodes with 1 hidden member):

./replica_cluster.sh deploy

Available Commands

Cluster Management:

• ./replica_cluster.sh deploy - Deploy and initialize the replica set
• ./replica_cluster.sh destroy - Destroy the cluster (removes all data)
• ./replica_cluster.sh status - View cluster status and member health
• ./replica_cluster.sh connect - Connect to the replica set (auto-connects to PRIMARY)

Global Operations:

• ./replica_cluster.sh start_all - Start all mongod processes
• ./replica_cluster.sh restart_all - Restart all mongod processes
• ./replica_cluster.sh stop_all - Stop all mongod processes gracefully

Single Node Operations:

• ./replica_cluster.sh start <i> - Start a specific mongod (i=0-2)
• ./replica_cluster.sh stop <i> - Stop a specific mongod (i=0-2)
• ./replica_cluster.sh restart <i> - Restart a specific mongod (i=0-2)

Cluster Configuration

• Replica Set Name: rs0
• Number of Nodes: 3 (configurable via REPLICA_COUNT)
• Hidden Node Count: 1 (configurable via HIDDEN_NODE_COUNT, counted from the last node)
• Default Ports: 30000, 30001, 30002
• Hidden Node: By default, the last 1 node (mongod2) is configured as hidden with priority 0
• Connection String: mongodb://host:30000,host:30001/?replicaSet=rs0 (automatically excludes hidden nodes)

Configuration examples:

# Default (1 hidden node)
REPLICA_COUNT=3
HIDDEN_NODE_COUNT=1      # mongod2 is HIDDEN

# Multiple hidden nodes
REPLICA_COUNT=5
HIDDEN_NODE_COUNT=2      # mongod3-4 are HIDDEN

# No hidden nodes
REPLICA_COUNT=3
HIDDEN_NODE_COUNT=0      # All nodes can become PRIMARY

Sharded Cluster

Quick Start

Deploy a sharded cluster (3 shards, each with 3 replicas):

./shard_cluster.sh deploy

Available Commands

Cluster Management:

• ./shard_cluster.sh deploy - Deploy complete sharded cluster
• ./shard_cluster.sh destroy - Destroy the cluster (removes all data)
• ./shard_cluster.sh status - View cluster status and shard information
• ./shard_cluster.sh connect - Connect to mongos router

Global Operations:

• ./shard_cluster.sh start_all - Start all services (config + shards + mongos)
• ./shard_cluster.sh stop_all - Stop all services gracefully
• ./shard_cluster.sh stop_mongod - Stop all mongod processes (config + shards)

Component Operations:

• ./shard_cluster.sh restart_config - Restart config server
• ./shard_cluster.sh restart_shards - Restart all shard replica sets
• ./shard_cluster.sh restart_mongos - Restart mongos router
• ./shard_cluster.sh stop_config - Stop config server
• ./shard_cluster.sh stop_shards - Stop all shard replica sets
• ./shard_cluster.sh stop_mongos - Stop mongos router

Single Node Operations:

• ./shard_cluster.sh stop_shard_node <shard_id> <replica_id> - Stop specific shard node
• ./shard_cluster.sh start_shard_node <shard_id> <replica_id> - Start specific shard node
• ./shard_cluster.sh restart_shard_node <shard_id> <replica_id> - Restart specific shard node

Parameter description:

• shard_id: Shard ID, range 0-2 (default configuration)
• replica_id: Replica ID, range 0-2 (default configuration)

Examples:

./shard_cluster.sh stop_shard_node 0 1    # Stop shard0 replica1
./shard_cluster.sh start_shard_node 1 2   # Start shard1 replica2
./shard_cluster.sh restart_shard_node 2 0 # Restart shard2 replica0

Cluster Configuration

• Shard Count: 3 (configurable via SHARD_COUNT)
• Replicas per Shard: 3 (configurable via SHARD_REPLICA_COUNT)
• Hidden Node Count: 1 (configurable via HIDDEN_NODE_COUNT, last N nodes of each shard)
• Config Server Port: 27000
• Shard Base Port: 28000 (28000-28008 for 3 shards with 3 replicas each)
• Mongos Port: 29000
• Hidden Nodes: By default, the last 1 replica of each shard is configured as hidden
• Replica Set Names: shardReplSet0, shardReplSet1, shardReplSet2

Configuration examples:

# Default (1 hidden node per shard)
SHARD_REPLICA_COUNT=3
HIDDEN_NODE_COUNT=1      # replica2 of each shard is HIDDEN

# Multiple hidden nodes
SHARD_REPLICA_COUNT=4
HIDDEN_NODE_COUNT=2      # replica2-3 of each shard are HIDDEN

# No hidden nodes
SHARD_REPLICA_COUNT=3
HIDDEN_NODE_COUNT=0      # All replicas can become PRIMARY

Command Completion

Enable Tab auto-completion for faster command input:

Temporary (current shell only):

source ./run_completions.bash

Permanent (add to ~/.bashrc):

echo "source $(pwd)/run_completions.bash" >> ~/.bashrc
source ~/.bashrc

Usage Examples:

# Command completion
./replica_cluster.sh st<Tab>      # Auto-completes to 'status'
./replica_cluster.sh co<Tab>      # Auto-completes to 'connect'
./replica_cluster.sh <Tab><Tab>   # Shows all available commands

# Option completion
./replica_cluster.sh connect <Tab>  # Shows: -js --js

# File and directory completion (New Feature!)
./replica_cluster.sh connect -js <Tab>        # Shows all .js files and directories
./replica_cluster.sh connect -js jstest/<Tab> # Shows .js files in jstest/ directory
./replica_cluster.sh connect -js jstest/r<Tab> # Auto-completes to read_preference_test.js

Examples

Replica Set Workflow

# Deploy the cluster
./replica_cluster.sh deploy

# Check cluster status
./replica_cluster.sh status

# Connect to the replica set
./replica_cluster.sh connect

# Stop a specific node (test failover)
./replica_cluster.sh stop 0

# Check status again (PRIMARY should have changed)
./replica_cluster.sh status

# Restart the stopped node
./replica_cluster.sh start 0

# Clean up everything
./replica_cluster.sh destroy

Sharded Cluster Workflow

# Deploy the sharded cluster
./shard_cluster.sh deploy

# Check cluster status
./shard_cluster.sh status

# Connect to mongos
./shard_cluster.sh connect

# Restart mongos
./shard_cluster.sh restart_mongos

# Test single node operations (failover)
./shard_cluster.sh stop_shard_node 0 1   # Stop a node
./shard_cluster.sh status                # Check cluster status
./shard_cluster.sh start_shard_node 0 1  # Restart the node

# Clean up everything
./shard_cluster.sh destroy

Advanced Features

Hidden Nodes

Both scripts automatically configure hidden nodes for backup and analytics:

• Replica Set: The last node (mongod2) is configured as hidden
• Sharded Cluster: The last replica of each shard is configured as hidden

Hidden nodes:

• Don't accept client reads
• Cannot become PRIMARY
• Ideal for backups and analytics workloads

Automatic Failover

The connect command uses replica set connection strings:

• Automatically connects to the current PRIMARY
• Automatically reconnects if PRIMARY changes
• Provides high availability for client connections

Status Command

The status command provides a clean, formatted view:

• Node health and roles (PRIMARY/SECONDARY)
• Process information (PID, ports)
• Cluster statistics
• Simplified output (no verbose JSON dumps)

Single Node Operations (Sharded Cluster)

Sharded clusters support fine-grained control over individual nodes, suitable for:

Failover Testing:

• Stop PRIMARY nodes to test automatic failover
• Verify replica set high availability

Rolling Upgrades:

• Stop, upgrade, and start nodes one by one
• Complete version upgrades without service interruption

Node Maintenance:

• Maintain HIDDEN nodes (no business impact)
• Perform backup or data analysis operations

Performance Testing:

• Test performance with different node counts
• Simulate degraded scenarios

Example scenarios:

# Scenario 1: Test failover
./shard_cluster.sh stop_shard_node 0 0   # Stop a shard0 node
sleep 10                                  # Wait for new PRIMARY election
./shard_cluster.sh status                # Verify successful failover
./shard_cluster.sh start_shard_node 0 0  # Restart the node

# Scenario 2: Maintain HIDDEN node (no business impact)
./shard_cluster.sh stop_shard_node 1 2   # Stop HIDDEN node
# ... Perform backup or maintenance ...
./shard_cluster.sh start_shard_node 1 2  # Restart

Important Notes:

• Don't stop more than 1 node simultaneously (majority required)
• Stopping PRIMARY triggers election (~5-15 seconds write interruption)
• HIDDEN nodes (replica2) can be safely stopped without affecting service
• Recommended to perform operations during off-peak hours

Configuration Requirements

MongoDB Binaries

The scripts use MongoDB binaries from the following paths:

• Binary Directory: /data/workspace/mongodb/bin/
• mongod: /data/workspace/mongodb/bin/mongod
• mongos: /data/workspace/mongodb/bin/mongos
• mongo shell: /data/workspace/mongodb/bin/mongo

Ensure these binaries exist and have execute permissions.

Cluster Data Directories

• Replica Set: /data/workspace/mongodb/instance_replica/
• Sharded Cluster: /data/workspace/mongodb/instance_shard/

Data, logs, and configuration files are stored in these directories.

Notes

• Ports: Default ports are used (see cluster configuration sections above)
• Help: Run any script without arguments to see detailed usage information
• Data Persistence: Data is stored in the cluster directories and survives restarts
• Customization: Edit the variables at the top of each script to customize ports, directories, etc.