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

> Learn how to check MongoDB replica set health and status with rs.status() in Docker. Execute rs.status() via mongosh for real-time member states and election data.

- Repository: [Jin/mongodb-cluster-docker-compose](https://github.com/minhhungit/mongodb-cluster-docker-compose)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`:

```bash
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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml), such as `shard-01-node-a` or `mongo-config-01`.

**Example for a shard replica set:**

```bash
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`:

```bash
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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-route.sh), the system waits for a primary to be elected before proceeding with shard registration.

**Pattern used in entrypoint scripts:**

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/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.