consul(8)
Consul is a distributed service mesh and service discovery tool that manages service registration, health checking, and network configuration across infrastructure.
Synopsis
consul [command] [options]Description
Consul is a HashiCorp tool for discovering and configuring services in dynamic infrastructure. It provides service discovery via DNS or HTTP API, health checking to detect and isolate unhealthy services, and key-value storage for configuration management.
Consul runs as either an agent (in client or server mode) and forms a cluster of nodes that maintain consistent state about all registered services. It uses the Raft consensus algorithm for server nodes and gossip protocol for cluster membership.
Common use cases include microservice discovery, load balancing, health monitoring, and implementing service mesh policies with Consul Connect.
Common options
| Flag | What it does |
|---|---|
-server | Run in server mode (maintains full state and participates in Raft consensus) |
-client | Run in client mode (queries and registers services with servers) |
-node=<name> | Specify the node name for this Consul agent |
-datacenter=<dc> | Set the datacenter name (default: dc1) |
-bind=<addr> | Set the bind address for cluster gossip traffic |
-ui | Enable the built-in Consul web UI |
-config-file=<path> | Load configuration from a file |
-config-dir=<dir> | Load all .json files in a directory as configuration |
-bootstrap-expect=<num> | Wait for specified number of servers before bootstrapping the cluster |
-retry-join=<addr> | Address of an existing node to join |
-log-level=<level> | Set logging level (trace, debug, info, warn, err) |
Examples
Start a server node in bootstrap mode with UI enabled, waiting for 3 servers to form a cluster
consul agent -server -ui -bootstrap-expect=3Start a client node named web-1 with configuration loaded from /etc/consul.d directory
consul agent -client -node=web-1 -config-dir=/etc/consul.dList all nodes in the Consul cluster and their status
consul membersRegister a service named 'api' running on port 8080 with production tag
consul services register -name=api -port=8080 -tag=productionStore a key-value pair in Consul's distributed config store
consul kv put config/database/host localhostRetrieve a value from the key-value store
consul kv get config/database/hostPerform a DNS lookup for a service using Consul's DNS interface
consul dns -query api.service.consulValidate Consul configuration file syntax before deployment
consul validate /etc/consul.d/config.json