> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/iagctl/inspect-cluster-health/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# iagctl inspect cluster health

Gateway 5.4+

Check the health of a gateway cluster.

The `iagctl inspect cluster health` command checks whether the gateway's backing datastore is reachable and whether each registered runner node is responding. Use this command before performing cluster maintenance to confirm the cluster is in a known good state, or after making changes to verify the cluster recovered as expected.

You can also run `iagctl inspect cluster` without a subcommand to display health and activity output together.

For guidance on using this command as part of a maintenance workflow, see [Monitor cluster health and activity](../monitor-cluster-health-activity).

## Syntax

```bash
iagctl inspect cluster health [flags]
```

## Output

**Summary**

| Field             | Description                                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| `Cluster`         | The cluster ID                                                                    |
| `Store`           | The store backend and its health status                                           |
| `Runners`         | The number of registered runner nodes and how many are reachable                  |
| `Gateway Manager` | The Gateway Manager connection status: `connected`, `disconnected`, or `disabled` |

**Details Table**

| Column      | Description                                                                                                                                                                             |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COMPONENT` | The type of cluster component: `store`, `runner`, `gateway-manager`, or `controller`                                                                                                    |
| `TYPE`      | The component subtype — store backend (`local`, `memory`, `etcd`, `dynamodb`), runner type (`remote`, `embedded`), or Gateway Manager type. Empty entry (`-`) for controller nodes      |
| `ADDRESS`   | The address or path of the component. For controller nodes, the OS hostname of the gateway node                                                                                         |
| `STATUS`    | Component status. `healthy`/`unhealthy` for store; `reachable`/`unreachable` for runners; `connected`/`disconnected`/`disabled` for Gateway Manager; `active`/`standby` for controllers |

The command exits with code `0` when the cluster is healthy and a non-zero code when unhealthy.

## Examples

### Check cluster health

```bash
iagctl inspect cluster health
```

### Check cluster health using a specific config file

```bash
iagctl inspect cluster health --config /path/to/gateway.conf
```

## Options

```bash
  -h, --help   help for health
```

## Options inherited from parent commands

```bash
      --config string    Specify the path to the configuration file
      --profile string   Specify the client profile to use (case-insensitive, defaults to [client] section)
      --raw              Displays the result of the command in its raw format
      --verbose          Enable verbose output
```