-bootstrap-expect=3 \ ## Consul waits until the specified number of servers are available and then bootstraps the cluster
-bind=10.0.20.1 \ ## If you have multi local IPs, choose one manually. Otherwize it will fail
-client=10.0.20.1 \ ## Don't set it, unless you expects the HTTP, DNS and RPC servers be exposed to non-127.0.0.1
-config-dir=/etc/consul.d/ \ ## A directory of configuration files (.json) to load
-data-dir=~/usr/local/consul/ \ ## Persistent state, the directory must be durable across reboots
-datacenter=uat \ ## Default: `dc1`. Nodes in the same datacenter should be on a single LAN
-encrypt=<`consul keygen`> \ ## All nodes in the cluster share the same key, used for messages between agents
-node=node_name \ ## Default: `$hostname`, must be unique within the cluster
-server \ ## Server mode, otherwise client mode
-ui ## Enable the default dashboard on http://localhost:8500/ui
Docker
Dev Mode:
1
2
3
4
5
6
7
docker run -d \
--name consul \
-p 8300:8300 \
-p 8400:8400 \
-p 8500:8500 \
-p 8600:8600 \
consul
hashi-ui
1
2
3
4
5
6
docker run -d \
--name=hashi-ui \
-e CONSUL_ENABLE=1 \
-e CONSUL_ADDR=<ip>:<port> \
-p 3000:3000 \
jippi/hashi-ui
Used Ports
8300: server RPC, TCP only, handle RPC from other agents
8301: gossip in LAN, TCP and UDP, required
8302: gossip over WAN, TCP and UDP
8400: cli RPC, TCP only, handle RPC from cli
8500: HTTP API, UI, TCP only
8600: DNS Interface, TCP and UDP, handle DNS queries
Cluster
Server
3 or 5 server recommended. Start the Consul server with the following command on 3 or 5 servers.
1
2
3
4
5
6
consul agent \
-server \
-bootstrap-expect=3 \
-data-dir=/tmp/consul \
-bind=<ip> \
-start_join=<server1>
Client
Start the Consul client on every server that is part of the cluster with the following command.
1
2
3
4
consul agent \
-data-dir=/tmp/consul \
-bind=<ip> \
-start_join=<server1,server2,server3>
Health Checks
Script + Interval
Exit code of 0 will be treated as passing. Example:
1
2
3
4
5
6
{
"check": {
"script": "curl localhost >/dev/null 2>&1",
"interval": "10s"
}
}
1
2
3
4
5
6
7
8
9
{
"check": {
"id": "mem-util",
"name": "Memory utilization",
"script": "/usr/local/bin/check_mem.py",
"interval": "10s",
"timeout": "1s"
}
}
HTTP + Interval
Based on the http response code:
2xx: passing
429 (Too Many Requests): warning
others: failure
Example:
1
2
3
4
5
6
7
8
9
{
"check": {
"id": "api",
"name": "HTTP API on port 5000",
"http": "http://localhost:5000/health",
"interval": "10s",
"timeout": "1s"
}
}
TCP + Interval
Checks if the tcp connection attemp is successful.
Example:
1
2
3
4
5
6
7
8
9
{
"check": {
"id": "ssh",
"name": "SSH TCP on port 22",
"tcp": "localhost:22",
"interval": "10s",
"timeout": "1s"
}
}
TTL
Services report its status to Consul periodically over the HTTP, if no updates for the given TTL, the service will be marked as cretical. Endpoint: /v1/agent/check/pass/<checkId>
Example:
1
2
3
4
5
6
7
8
{
"check": {
"id": "web-app",
"name": "Web App Status",
"notes": "Web app does a curl internally every 10 seconds",
"ttl": "30s"
}
}
Docker + Interval
Docker ported [Script + Interval]
Example:
1
2
3
4
5
6
7
8
9
10
{
"check": {
"id": "mem-util",
"name": "Memory utilization",
"docker_container_id": "f972c95ebf0e",
"shell": "/bin/bash",
"script": "/usr/local/bin/check_mem.py",
"interval": "10s"
}
}
Watches
key
Watch a specific KV pair.
Example:
1
2
3
4
5
{
"type": "key",
"key": "foo/bar/baz",
"handler": "/usr/bin/my-key-handler.sh"
}
1
consul watch -type=key -key=foo/bar/baz /usr/bin/my-key-handler.sh
keyprefix
Watch a prefix in the KV store.
Example:
1
2
3
4
5
{
"type": "keyprefix",
"prefix": "foo/",
"handler": "/usr/bin/my-prefix-handler.sh"
}
1
consul watch -type=keyprefix -prefix=foo/ /usr/bin/my-prefix-handler.sh
services
Watch the list of available services.
nodes
Watch the list of nodes.
service
Watch the instances of a service.
Example:
1
2
3
4
5
{
"type": "service",
"service": "redis",
"handler": "/usr/bin/my-service-handler.sh"
}
1
consul watch -type=service -service=redis /usr/bin/my-service-handler.sh
checks
Watch the value of health checks.
event
Watch for custom user events.
Example:
1
2
3
4
5
{
"type": "event",
"name": "web-deploy",
"handler": "/usr/bin/my-deploy-handler.sh"
}
1
consul watch -type=event -name=web-deploy /usr/bin/my-deploy-handler.sh
To fire a new web-deploy event:
1
consul event -name=web-deploy 1609030
HTTP API
ACLs
Create ACL Token
payload.json
1
2
3
4
5
{
"Name": "my-app-token",
"Type": "client",
"Rules": ""
}
Param
Type
Description
ID
string
If not provided, a UUID is generated
Name
string
a human-friendly name for the ACL token
Type
string
client (default) or management
Rules
string
rules for this ACL token
1
curl -X PUT -d @payload.json http://localhost:8500/v1/acl/create
Update ACL Token
payload.json:
1
2
3
4
5
6
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Name": "my-app-token-updated",
"Type": "client",
"Rules": "# New Rules",
}
1
curl -X PUT -d @payload.json http://localhost:8500/v1/acl/update
Delete ACL Token
1
curl -X PUT http://localhost:8500/v1/acl/destroy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05