Consul
Comprehensive HashiCorp Consul commands and workflows for service discovery, configuration management, and service mesh.
Installation & Setup
Command |
Description |
consul version |
Show Consul version |
consul agent -dev |
Start development agent |
consul agent -config-dir=/etc/consul.d |
Start with configuration |
consul members |
List cluster members |
consul info |
Show agent information |
Agent Management
Basic Agent Operations
Command |
Description |
consul agent -server -bootstrap-expect=3 |
Start server agent |
consul agent -client=0.0.0.0 |
Start client agent |
consul join 192.168.1.100 |
Join cluster |
consul leave |
Gracefully leave cluster |
consul reload |
Reload configuration |
Agent Configuration
Command |
Description |
consul validate /etc/consul.d |
Validate configuration |
consul configtest |
Test configuration |
Service Discovery
Service Registration
Command |
Description |
consul services register service.json |
Register service from file |
consul services deregister service-id |
Deregister service |
consul catalog services |
List all services |
consul catalog nodes |
List all nodes |
Service Queries
Command |
Description |
consul catalog service web |
List instances of service |
consul catalog service web -tag production |
Filter by tag |
consul health service web |
Health check status |
consul health node node1 |
Node health status |
DNS Interface
Command |
Description |
dig @127.0.0.1 -p 8600 web.service.consul |
Query service via DNS |
dig @127.0.0.1 -p 8600 web.service.dc1.consul |
Query specific datacenter |
dig @127.0.0.1 -p 8600 node1.node.consul |
Query node via DNS |
Key-Value Store
KV Operations
Command |
Description |
consul kv put config/database/url "postgresql://..." |
Store key-value |
consul kv get config/database/url |
Retrieve value |
consul kv get -recurse config/ |
Get all keys under prefix |
consul kv delete config/database/url |
Delete key |
consul kv delete -recurse config/ |
Delete all keys under prefix |
KV Advanced Operations
Command |
Description |
consul kv put -cas -modify-index=123 config/app/version "2.0" |
Conditional update |
consul kv get -detailed config/app/version |
Get with metadata |
consul kv export config/ |
Export keys |
consul kv import @backup.json |
Import keys |
Health Checks
Health Check Management
Command |
Description |
consul health checks |
List all health checks |
consul health checks web |
List checks for service |
consul health state critical |
List critical checks |
consul health state passing |
List passing checks |
Access Control Lists (ACLs)
ACL Management
Command |
Description |
consul acl bootstrap |
Bootstrap ACL system |
consul acl token create -description="Web service token" |
Create token |
consul acl token list |
List tokens |
consul acl token delete TOKEN_ID |
Delete token |
ACL Policies
Command |
Description |
consul acl policy create -name web-policy -rules @policy.hcl |
Create policy |
consul acl policy list |
List policies |
consul acl policy read web-policy |
Read policy |
consul acl policy update -id POLICY_ID -rules @new-policy.hcl |
Update policy |
Connect (Service Mesh)
Connect Configuration
Command |
Description |
consul connect ca get-config |
Get CA configuration |
consul connect ca set-config -config-file ca.json |
Set CA configuration |
consul connect proxy -service web |
Start Connect proxy |
Intentions
Command |
Description |
consul intention create web db |
Allow web to connect to db |
consul intention create -deny web cache |
Deny web to cache |
consul intention list |
List all intentions |
consul intention delete web db |
Delete intention |
Configuration Entries
Service Configuration
Command |
Description |
consul config write service-defaults.hcl |
Write service defaults |
consul config write proxy-defaults.hcl |
Write proxy defaults |
consul config list -kind service-defaults |
List configurations |
consul config read -kind service-defaults -name web |
Read configuration |
consul config delete -kind service-defaults -name web |
Delete configuration |
Snapshots and Backups
Snapshot Operations
Command |
Description |
consul snapshot save backup.snap |
Create snapshot |
consul snapshot restore backup.snap |
Restore snapshot |
consul snapshot inspect backup.snap |
Inspect snapshot |
Monitoring and Debugging
Monitoring Commands
Command |
Description |
consul monitor |
Stream logs |
consul monitor -log-level=DEBUG |
Debug level logs |
consul debug |
Collect debug information |
consul operator raft list-peers |
List Raft peers |
Command |
Description |
consul operator autopilot get-config |
Get autopilot config |
consul operator autopilot set-config -cleanup-dead-servers=true |
Set autopilot config |
Configuration Examples
Server Configuration
datacenter = "dc1"
data_dir = "/opt/consul"
log_level = "INFO"
node_name = "consul-server-1"
server = true
bootstrap_expect = 3
retry_join = ["10.0.1.10", "10.0.1.11"]
bind_addr = "10.0.1.10"
client_addr = "0.0.0.0"
ui_config \\\\{
enabled = true
\\\\}
connect \\\\{
enabled = true
\\\\}
acl = \\\\{
enabled = true
default_policy = "deny"
enable_token_persistence = true
\\\\}
Client Configuration
datacenter = "dc1"
data_dir = "/opt/consul"
log_level = "INFO"
node_name = "consul-client-1"
retry_join = ["10.0.1.10", "10.0.1.11", "10.0.1.12"]
bind_addr = "10.0.1.20"
client_addr = "127.0.0.1"
services \\\\{
name = "web"
port = 80
tags = ["production", "v1.0"]
check \\\\{
http = "http://localhost:80/health"
interval = "10s"
\\\\}
\\\\}
Service Definition
\\\\{
"service": \\\\{
"name": "web",
"port": 80,
"tags": ["production"],
"check": \\\\{
"http": "http://localhost:80/health",
"interval": "10s"
\\\\},
"connect": \\\\{
"sidecar_service": \\\\{\\\\}
\\\\}
\\\\}
\\\\}
ACL Policy
node_prefix "" \\\\{
policy = "read"
\\\\}
service_prefix "" \\\\{
policy = "read"
\\\\}
service "web" \\\\{
policy = "write"
\\\\}
key_prefix "config/web/" \\\\{
policy = "write"
\\\\}
session_prefix "" \\\\{
policy = "read"
\\\\}
Service Mesh Configuration
Proxy Defaults
Kind = "proxy-defaults"
Name = "global"
Config \\\\{
protocol = "http"
\\\\}
MeshGateway \\\\{
Mode = "local"
\\\\}
Service Defaults
Kind = "service-defaults"
Name = "web"
Protocol = "http"
MeshGateway \\\\{
Mode = "local"
\\\\}
Expose \\\\{
Checks = true
Paths = [
\\\\{
Path = "/health"
LocalPathPort = 8080
ListenerPort = 21500
\\\\}
]
\\\\}
Multi-Datacenter Setup
WAN Federation
Command |
Description |
consul join -wan 192.168.2.10 |
Join WAN |
consul members -wan |
List WAN members |
consul catalog datacenters |
List datacenters |
Cross-DC Queries
Command |
Description |
consul catalog service web -datacenter dc2 |
Query service in DC2 |
dig @127.0.0.1 -p 8600 web.service.dc2.consul |
DNS query to DC2 |
Troubleshooting
Common Issues
Command |
Description |
consul operator raft list-peers |
Check Raft cluster state |
consul debug -duration=30s |
Collect debug info |
consul validate /etc/consul.d |
Validate configuration |
consul members -detailed |
Detailed member information |
Log Analysis
Command |
Description |
consul monitor -log-level=TRACE |
Trace level logging |
journalctl -u consul -f |
Follow systemd logs |
Best Practices
Security
- Enable ACLs: Always use ACLs in production
- TLS Encryption: Enable TLS for all communication
- Gossip Encryption: Use gossip encryption
- Network Segmentation: Proper network security
- Token Management: Rotate tokens regularly
- Resource Allocation: Adequate CPU and memory
- Network Latency: Minimize network latency
- Disk I/O: Use fast storage for data directory
- Cluster Size: Optimal cluster sizing
- Monitoring: Comprehensive monitoring setup
Operations
- Backup Strategy: Regular snapshots
- Upgrade Planning: Careful upgrade procedures
- Health Monitoring: Monitor service health
- Capacity Planning: Plan for growth
- Documentation: Document service topology
Development
- Service Registration: Proper service definitions
- Health Checks: Comprehensive health checks
- Configuration Management: Use KV store effectively
- Service Discovery: Implement proper discovery patterns
- Testing: Test service mesh configurations