How to Check the Health and Status of Individual Replica Sets with rs.status()

Use docker exec to pipe rs.status() into mongosh for any containerized MongoDB node to retrieve real-time replica set health, member states, and election metadata.

The minhhungit/mongodb-cluster-docker-compose repository orchestrates a sharded MongoDB cluster using Docker Compose, where each shard and config server runs as a replica set inside isolated containers. To monitor these distributed sets, you need to execute MongoDB's rs.status() command against individual containers without attaching to them interactively.

Understanding rs.status() in Containerized Environments

rs.status() returns a document containing the state of every member in a replica set, including state strings like PRIMARY, SECONDARY, ARBITER, or DOWN. In the Docker Compose setup defined in docker-compose.yml, each node (e.g., shard-01-node-a, mongo-config-01) exposes MongoDB on port 27017 internally.

Because containers run in isolation, you invoke rs.status() from the host machine using docker exec combined with mongosh, the modern MongoDB shell bundled in the official image.

Basic Syntax for Checking Replica Set Health

The standard pattern for checking any replica set member's health uses docker exec to stream the command into mongosh:

docker exec -it <container-name> bash -c \
  "echo 'rs.status()' | mongosh --port 27017"

Replace <container-name> with the service name defined in docker-compose.yml, such as shard-01-node-a or mongo-config-01.

Example for a shard replica set:

docker exec -it shard-01-node-a bash -c \
  "echo 'rs.status()' | mongosh --port 27017"

This returns a JSON-like document containing set name, myState, members array with health and stateStr fields, and election metadata.

Filtering rs.status() Output for Quick Health Checks

When monitoring multiple shards, you often need only the state strings of members to verify quorum health. You can filter rs.status() output using JavaScript array methods inside mongosh:

docker exec -it shard-01-node-a bash -c \
  "echo 'rs.status().members.forEach(m => print(m.stateStr))' | mongosh --port 27017"

Expected output:

PRIMARY
SECONDARY
SECONDARY

This pattern makes it easy to spot unhealthy states like DOWN, RECOVERING, or STARTUP without parsing verbose JSON.

Automated Health Monitoring in Startup Scripts

The repository's initialization logic relies on rs.status() polling to coordinate cluster startup. In scripts/entrypoint-route.sh, the system waits for a primary to be elected before proceeding with shard registration.

Pattern used in entrypoint scripts:

until mongosh --host rs-shard-01/shard01-a:27017,shard01-b:27017,shard01-c:27017 \
      --eval 'rs.status().members.some(m => m.stateStr === "PRIMARY")' | grep -q 'true'; do
  echo "Waiting for shard rs-shard-01 to elect a PRIMARY..."
  sleep 5
done

This demonstrates how rs.status() drives orchestration logic, checking the members array for stateStr === "PRIMARY" to confirm replica set readiness.

Checking Different Replica Set Types

Shard Replica Sets

Each shard runs as an independent replica set (e.g., rs-shard-01). Check individual members using their container names:

docker exec -it shard-02-node-b bash -c \
  "echo 'rs.status()' | mongosh --port 27017"

Config Server Replica Sets

The config servers (mongo-config-01, mongo-config-02, mongo-config-03) form rs-config-server. Check their health similarly:

docker exec -it mongo-config-01 bash -c \
  "echo 'rs.status()' | mongosh --port 27017"

Authenticated Clusters

If you enabled authentication using the with-keyfile-auth configuration, include credentials in the mongosh command:

docker exec -it shard-01-node-a bash -c \
  "echo 'rs.status()' | mongosh --port 27017 -u 'admin' -p 'password' --authenticationDatabase admin"

As documented in with-keyfile-auth/readme.md, authentication requires valid user credentials for rs.status() to return data.

Summary

• Use docker exec to run rs.status() via mongosh against any containerized MongoDB node without interactive shell access.
• Filter output with JavaScript methods like members.forEach(m => print(m.stateStr)) to quickly identify PRIMARY, SECONDARY, or unhealthy states.
• Reference startup scripts like scripts/entrypoint-route.sh to see how rs.status() drives cluster orchestration by polling for primary election.
• Include authentication flags when checking replica sets in the with-keyfile-auth configuration.

Frequently Asked Questions

What does rs.status() return in MongoDB?

rs.status() returns a document containing the replica set's current configuration and operational state, including the set name, myState field, and a members array. Each member object includes name (host:port), health (0 or 1), state (integer code), and stateStr (human-readable state like PRIMARY or SECONDARY).

How do I run rs.status() inside a Docker container?

Execute rs.status() using docker exec combined with mongosh: docker exec -it <container-name> bash -c "echo 'rs.status()' | mongosh --port 27017". Replace <container-name> with the specific service name from your docker-compose.yml, such as shard-01-node-a or mongo-config-01.

Can I check replica set health without authentication?

In the default minhhungit/mongodb-cluster-docker-compose configuration without keyfile authentication, you can run rs.status() without credentials. However, if you deployed the cluster using the with-keyfile-auth configuration, you must provide valid username, password, and --authenticationDatabase admin flags to mongosh to retrieve replica set status.

How do I identify the primary node using rs.status()?

Query the members array for the document where stateStr equals "PRIMARY". You can filter the output using: rs.status().members.find(m => m.stateStr === "PRIMARY"). In shell scripts, use rs.status().members.some(m => m.stateStr === "PRIMARY") to return a boolean indicating whether a primary currently exists in the replica set.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}