93 lines
3.0 KiB
Plaintext
93 lines
3.0 KiB
Plaintext
---
|
|
layout: commands
|
|
page_title: 'Commands: Catalog List Nodes'
|
|
---
|
|
|
|
# Consul Catalog List Nodes
|
|
|
|
Command: `consul catalog nodes`
|
|
|
|
Corresponding HTTP API Endpoint: [\[GET\] /v1/catalog/nodes](/api-docs/catalog#list-nodes)
|
|
|
|
The `catalog nodes` command prints all known nodes and metadata about them.
|
|
It can also query for nodes that match a particular metadata or provide a
|
|
particular service.
|
|
|
|
The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of
|
|
[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching)
|
|
are not supported from commands, but may be from the corresponding HTTP endpoint.
|
|
|
|
| ACL Required |
|
|
| ------------ |
|
|
| `node:read` |
|
|
|
|
## Examples
|
|
|
|
List all nodes:
|
|
|
|
```shell-session
|
|
$ consul catalog nodes
|
|
Node ID Address DC
|
|
worker-01 1b662d97 10.4.5.31 dc1
|
|
```
|
|
|
|
Print detailed node information such as tagged addresses and node metadata:
|
|
|
|
```shell-session
|
|
$ consul catalog nodes -detailed
|
|
Node ID Address DC TaggedAddresses Meta
|
|
worker-01 1b662d97-8b5c-3cc2-0ac0-96f55ad423b5 10.4.5.31 dc1 lan=10.4.5.31, wan=10.4.5.31
|
|
```
|
|
|
|
List nodes which provide the service name "web":
|
|
|
|
```shell-session
|
|
$ consul catalog nodes -service=web
|
|
Node ID Address DC TaggedAddresses Meta
|
|
worker-01 1b662d97-8b5c-3cc2-0ac0-96f55ad423b5 10.4.5.31 dc1 lan=10.4.5.31, wan=10.4.5.31
|
|
```
|
|
|
|
Sort the resulting node list by estimated round trip time to worker-05:
|
|
|
|
```shell-session
|
|
$ consul catalog nodes -near=web-05
|
|
Node ID Address DC TaggedAddresses Meta
|
|
worker-01 1b662d97-8b5c-3cc2-0ac0-96f55ad423b5 10.4.5.31 dc1 lan=10.4.5.31, wan=10.4.5.31
|
|
worker-02 d407a592-e93c-4d8e-8a6d-aba853d1e067 10.4.4.158 dc1 lan=10.4.4.158, wan=10.4.4.158
|
|
```
|
|
|
|
## Usage
|
|
|
|
Usage: `consul catalog nodes [options]`
|
|
|
|
#### Command Options
|
|
|
|
- `-detailed` - Output detailed information about the nodes including their
|
|
addresses and metadata.
|
|
|
|
- `-near=<string>`- Node name to sort the node list in ascending order based on
|
|
estimated round-trip time from that node. Passing `"_agent"` will use this
|
|
agent's node for sorting.
|
|
|
|
- `-node-meta=<key=value>` - Metadata to filter nodes with the given key=value
|
|
pairs. This flag may be specified multiple times to filter on multiple sources
|
|
of metadata.
|
|
|
|
- `-service=<id or name>` - Service id or name to filter nodes. Only nodes
|
|
which are providing the given service will be returned.
|
|
|
|
- `-filter=<filter>` - Expression to use for filtering the results. Can be passed
|
|
via stdin by using `-` for the value or from a file by passing `@<file path>`.
|
|
See the [`/catalog/nodes` API documentation](/api-docs/catalog#filtering) for a
|
|
description of what is filterable.
|
|
|
|
#### Enterprise Options
|
|
|
|
@include 'http_api_partition_options.mdx'
|
|
|
|
#### API Options
|
|
|
|
@include 'http_api_options_client.mdx'
|
|
|
|
@include 'http_api_options_server.mdx'
|