How to Verify the Overall Cluster Health and Status Using the sh.status() Command

Use the sh.status() command in the MongoDB shell to query the config server metadata and display the complete topology of shards, replica sets, and mongos routers in your Docker-based cluster.

The minhhungit/mongodb-cluster-docker-compose repository provides a production-ready sharded MongoDB cluster orchestrated via Docker Compose. To verify the overall cluster health and status using the sh.status() command, you connect to any mongos router instance and invoke the helper, which returns the authoritative view of the cluster topology stored in the config servers.

Why Use sh.status() for Cluster Verification

The sh.status() helper is the canonical method for inspecting a sharded cluster because it aggregates metadata from the config server replica set into a single, readable report. Unlike checking individual shard nodes with rs.status(), this command validates the entire ecosystem—including the balancer state, chunk distribution, and router connectivity.

What the Command Queries

When executed, sh.status() connects to the config server replica set defined in the mongos startup parameters. In the docker-compose.yml file, the router service (router-01) is initialized with the --configdb flag pointing to the config server replica set (cfgrs). The command reads from the config.shards, config.mongos, and config.settings collections to build its report.

Information Returned

The output contains four critical health indicators:

• Sharding version – The version of the cluster metadata protocol.
• Shards – A list of every shard replica set, including member hostnames, ports, and state codes.
• Active mongoses – The number of router processes currently registered with the config servers.
• Balancer – Whether the balancer is enabled and its current operational state.

Running sh.status() in the Docker Environment

The repository provides multiple pathways to execute the command depending on your authentication setup and whether you prefer interactive shells or one-liners.

Inside the Router Container

The most direct method uses docker exec to pipe the command into the mongosh client running inside the router-01 container defined in the root docker-compose.yml.

docker exec -it router-01 bash -c \
  "echo 'sh.status()' | mongosh --port 27017"

This approach requires no local MongoDB installation and works immediately after the containers start.

Using Docker Compose Exec

For better readability and consistency with the Compose workflow shown in the readme.md (lines 49-55), use the docker-compose exec shortcut to open an interactive mongosh session.

docker-compose exec router01 mongosh --port 27017

Once inside the shell, run:

sh.status()

This method is preferred when you need to run multiple diagnostic commands sequentially.

With Keyfile Authentication Enabled

When deploying the cluster with authentication enabled (as documented in with-keyfile-auth/readme.md, lines 89-100), you must provide credentials to query the config servers. The command requires the -u and -p flags along with --authenticationDatabase.

docker exec -it router-01 bash -c \
  "echo 'sh.status()' | mongosh --port 27017 \
   -u 'your_admin' -p 'your_password' \
   --authenticationDatabase admin"

Failure to authenticate will result in an authorization error because the config server collections are protected.

From the Host Machine

If you have mongosh installed locally, you can connect through the exposed port mappings defined in docker-compose.yml (typically 27117 or 27118 mapped to container port 27017).

mongosh --host 127.0.0.1 --port 27117 \
        -u "your_admin" --authenticationDatabase admin

Then execute sh.status() inside the shell. This avoids container context switching but requires proper port mapping and local client installation.

Interpreting the Output

Understanding the sh.status() report is essential for diagnosing cluster health. The output structure reflects the internal state stored in the config server replica set.

Sharding Version and Metadata

The first block displays the cluster metadata protocol version:

sharding version: {
  _id: 1,
  minCompatibleVersion: 5,
  currentVersion: 6,
  clusterId: ObjectId("...")
}

A version mismatch between config servers and routers indicates an incomplete upgrade or configuration drift. The clusterId should remain consistent across all mongos instances.

Shard Topology and Member States

The shards array lists every shard replica set. Healthy members show "state" : 1 (PRIMARY) or "state" : 2 (SECONDARY). As noted in the repository documentation, if all members of a shard display "state" : 2 and no primary is elected, the cluster cannot route writes to that shard.

shards:
  {  "_id": "shard01",  "host": "shard01/shard01-a:27018,shard01-b:27018,shard01-c:27018",  "state": 1 }
  {  "_id": "shard02",  "host": "shard02/shard02-a:27019,shard02-b:27019,shard02-c:27019",  "state": 1 }

The host field confirms the replica set name and member addresses match the Docker service names defined in docker-compose.yml.

Balancer and Mongos Status

The final sections report operational health:

• active mongoses: Counts the number of mongos router processes currently heartbeating to the config servers. A count of zero indicates all routers are down or network partitioned.
• balancer: Shows whether the chunk balancer is enabled and currently running. For a healthy idle cluster, expect currently enabled: yes and currently running: no.

active mongoses:
  "4.4.x": 2

balancer:
  Currently enabled: yes
  Currently running: no

If the balancer reports Currently running: yes for extended periods without data ingestion, investigate for orphaned chunks or jumbo chunks blocking migration.

Key Files in the Repository

The following files define the cluster topology and verification workflow:

File	Purpose	Location
docker-compose.yml	Defines the router-01 service, config server replica set, and shard nodes that sh.status() queries.	Root directory
readme.md	Contains the "Verify the status of the sharded cluster" section with exact sh.status() commands.	Root readme
with-keyfile-auth/readme.md	Documents authentication-required verification steps for hardened deployments.	with-keyfile-auth directory
scripts/entrypoint-router.sh	Initializes the mongos router process, ensuring it can respond to sh.status() queries.	scripts directory

Summary

To verify the overall cluster health and status using the sh.status() command in the minhhungit/mongodb-cluster-docker-compose repository:

• Execute sh.status() from any mongos router container to query the config server metadata.
• Inspect the shards array for "state" : 1 (PRIMARY) on all shard replica sets.
• Confirm active mongoses shows the expected router count and the balancer reports enabled: yes.
• Use authenticated commands (-u and -p) when running the with-keyfile-auth variant documented in with-keyfile-auth/readme.md.

Frequently Asked Questions

What does it mean if a shard shows state 2 instead of state 1?

A state value of 2 indicates the member is a SECONDARY node. If all members of a shard replica set show state: 2 and no primary is listed, the shard has no elected primary. According to the repository documentation, this prevents the cluster from routing writes to that shard and indicates an unhealthy replica set requiring immediate attention.

Can I run sh.status() from any container, or only the router?

You should run sh.status() from a mongos router container (such as router-01 defined in docker-compose.yml). While you can technically connect to a config server directly and query the config database, the sh.status() helper is designed to run against mongos routers. Running it from shard containers or config servers may return errors or incomplete views because those nodes do not maintain the full cluster routing table.

Why does sh.status() require authentication in some deployments but not others?

Authentication requirements depend on whether you deployed the cluster using the standard docker-compose.yml or the with-keyfile-auth variant. The base configuration in the root directory starts the cluster without authentication for local development. However, the with-keyfile-auth/readme.md documents a hardened setup where --auth and --keyFile parameters are enabled. In that environment, the config server collections are protected, so sh.status() requires valid credentials (-u, -p, --authenticationDatabase admin) to read the metadata.

How do I fix a cluster where sh.status() shows missing shards?

If sh.status() lists fewer shards than defined in your docker-compose.yml, or shows "stateStr": "UNKNOWN" for members, first verify that all shard containers are running with docker ps. Next, check individual shard replica set health by connecting to a shard node and running rs.status(). If a shard is running but not visible to sh.status(), you may need to re-add it using sh.addShard() from the mongos router, ensuring you use the replica set connection string format (shard01/shard01-a:27018) as specified in the repository's initialization scripts.

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