HashiCorp Consul
App · 12 actions
Read and change Consul's key/value settings, see services, their instances and health for status reports, put instances into maintenance around a deploy, and fire events. Start a workflow when a health check goes critical or recovers, or when a key changes.
Actions
| Action | What it does |
|---|---|
| Check cluster status | Check that a datacenter's Consul servers have a leader (without one, Consul can't answer or change anything), with its servers. |
| Delete key | Delete a key, or every key under a prefix. |
| Fire event | Send a Consul user event, such as deploy, to every node or only those running a service. |
| Get key value | Read a key's value, such as a feature flag or a setting, to use in a later step. |
| Get keys under a prefix | Read every key under a prefix, such as an app's settings in config/app/, as one object, up to 1000 keys. |
| Get service health | See how a service is doing for a status report: how many instances are passing, warning and critical, and what each failing check printed. |
| List health checks | List the health checks that are failing (or critical, warning, passing, or every one) across the datacenter, or for one service or node, with what each printed. |
| List nodes | List the nodes (machines) in a datacenter with their addresses and whether Consul can reach them. |
| List service instances | List a service's instances with the address and port to reach each, its tags and its health, or only the healthy ones. |
| List services | List the services registered in Consul, with their tags, or only those with a tag. |
| Set key value | Set a key's value, such as turning a feature flag on, creating the key if it isn't there. |
| Set maintenance mode | Put a service's instances into maintenance mode, such as before a deploy, so Consul stops sending traffic to them, or take them out again. |
Check cluster status
Check that a datacenter's Consul servers have a leader (without one, Consul can't answer or change anything), with its servers.
Inputs
- Datacenter
datacentertext - The datacenter, such as dc1. Leave blank for the connection's.
Outputs
datacentertext- The datacenter, such as dc1
datacenterslist- Every datacenter Consul knows, the nearest first
healthytrue/false- True when the datacenter has a leader
leadertext- The leading server's address, such as 10.0.0.5:8300; empty for none
server_countnumber- How many servers there are
serverslist- The servers' addresses
Example output
{
"datacenter": "dc1",
"datacenters": [
"dc1",
"dc2"
],
"healthy": true,
"leader": "10.0.0.5:8300",
"server_count": 3,
"servers": [
"10.0.0.5:8300",
"10.0.0.6:8300",
"10.0.0.7:8300"
]
}Delete key
Delete a key, or every key under a prefix. Consul keeps no history, so a deleted key can't be brought back.
Inputs
- Key
keytextRequired - The key to delete, or the prefix with 'Everything under it', such as config/old-app/.
- Everything under it
recursetrue/false - Delete every key that starts with this, for good.Default:
false. - Only if unchanged since
cas_indexnumber - A modify index from 'Get key value': the key is deleted only if nothing changed it since. Leave blank to delete it anyway.Only when Everything under it is
false. At least 1. - Datacenter
datacentertext - The datacenter, such as dc1. Leave blank for the connection's.
Outputs
countnumber- How many keys were deleted
datacentertext- The datacenter, such as dc1
deletedtrue/false- False when there was nothing there to delete
keytext- The key or prefix deleted
keys_deletedlist- The keys deleted
recursetrue/false- True when everything under it was deleted
Example output
{
"count": 2,
"datacenter": "dc1",
"deleted": true,
"key": "config/old-app/",
"keys_deleted": [
"config/old-app/db/host",
"config/old-app/feature_x"
],
"recurse": true
}Fire event
Send a Consul user event, such as deploy, to every node or only those running a service. Scripts set up with consul watch on the nodes act on it.
Inputs
- Event name
event_nametextRequired - The event's name, as the watches expect it, such as deploy.
- Payload
payloadtext - A short text to send with it, such as a version, up to about 300 characters.
- Only nodes running
service_filtertext - Only nodes running this service. Leave blank for every node.
- With tag
tag_filtertext - Only nodes running the service with this tag, such as canary.
- Nodes named
node_filtertext - Only nodes whose names match this pattern, such as web-.*.
- Datacenter
datacentertext - The datacenter, such as dc1. Leave blank for the connection's.
Outputs
datacentertext- The datacenter, such as dc1
idtext- The event's ID
nametext- The event's name
node_filtertext- Only nodes matching this got it
payloadtext- The payload sent with it
service_filtertext- Only nodes running this service got it
tag_filtertext- Only nodes running the service with this tag got it
Example output
{
"datacenter": "dc1",
"id": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c",
"name": "deploy",
"node_filter": "",
"payload": "2.5.0",
"service_filter": "web",
"tag_filter": ""
}Get key value
Read a key's value, such as a feature flag or a setting, to use in a later step. A key that isn't set comes back with found false and an empty value rather than failing the step.
Inputs
- Key
keytextRequired - The key, as Consul's Key/Value page shows it, such as config/app/feature_x.
- Datacenter
datacentertext - The datacenter, such as dc1. Leave blank for the connection's.
Outputs
create_indexnumber- Consul's index when the key was created
datacentertext- The datacenter, such as dc1
flagsnumber- The number stored with the key by whoever wrote it; usually 0
foundtrue/false- False when the key isn't set; its value is then empty
is_texttrue/false- False when the value isn't text, such as a file, and is given as base64
jsonobject- The value read as JSON, when it is a JSON object or list; empty otherwise
keytext- The key, such as config/app/feature_x
linktext- A link to the key in Consul
lockedtrue/false- True while a Consul lock session holds the key
modify_indexnumber- Consul's index when the key last changed; give it to 'Set key value' to write only if nothing changed it since
valuetext- The value as text (base64 when it isn't text)
Example output
{
"create_index": 38,
"datacenter": "dc1",
"flags": 0,
"found": true,
"is_text": true,
"json": {
"retries": 3,
"theme": "dark"
},
"key": "config/app/settings.json",
"link": "https://consul.example.com:8501/ui/dc1/kv/config/app/settings.json/edit",
"locked": false,
"modify_index": 52,
"value": "{\"theme\": \"dark\", \"retries\": 3}"
}Get keys under a prefix
Read every key under a prefix, such as an app's settings in config/app/, as one object, up to 1000 keys.
Inputs
- Prefix
prefixtextRequired - The folder to read, such as config/app/. Keys under it come back without it.
- Datacenter
datacentertext - The datacenter, such as dc1. Leave blank for the connection's.
Outputs
countnumber- How many keys were read
dataobject- Each key without the prefix, with its value, such as db/host
datacentertext- The datacenter, such as dc1
itemslist- Each key with its value and indexes, in order
keyslist- The keys, in order
prefixtext- The prefix read, such as config/app/
treeobject- The same values nested by folder, such as db then host; a key that is also a folder keeps its value under _value
truncatedtrue/false- True when there were more keys than Lodol reads at once
Example output
{
"count": 3,
"data": {
"db/host": "db.internal",
"db/port": "5432",
"feature_x": "true"
},
"datacenter": "dc1",
"items": [
{
"create_index": 36,
"flags": 0,
"is_text": true,
"key": "config/app/db/host",
"modify_index": 36,
"relative_key": "db/host",
"value": "db.internal"
},
{
"create_index": 37,
"flags": 0,
"is_text": true,
"key": "config/app/db/port",
"modify_index": 37,
"relative_key": "db/port",
"value": "5432"
},
{
"create_index": 35,
"flags": 0,
"is_text": true,
"key": "config/app/feature_x",
"modify_index": 61,
"relative_key": "feature_x",
"value": "true"
}
],
"keys": [
"config/app/db/host",
"config/app/db/port",
"config/app/feature_x"
],
"prefix": "config/app/",
"tree": {
"db": {
"host": "db.internal",
"port": "5432"
},
"feature_x": "true"
},
"truncated": false
}Get service health
See how a service is doing for a status report: how many instances are passing, warning and critical, and what each failing check printed.
Inputs
- Service
servicetextRequired - The service's name, such as web.
- Datacenter
datacentertext - The datacenter, such as dc1. Leave blank for the connection's.
Outputs
checks_criticalnumber- Checks critical
checks_passingnumber- Checks passing
checks_warningnumber- Checks warning
criticalnumber- Instances with a critical check
datacentertext- The datacenter, such as dc1
failing_checkslist- Each check that isn't passing, with what it printed
healthytrue/false- True when every instance passes every check
in_maintenancenumber- Instances in maintenance mode
instancesnumber- How many instances it has
linktext- A link to the service in Consul
passingnumber- Instances passing every check
servicetext- The service
statustext- The worst instance's status: passing, warning or critical
warningnumber- Instances whose worst check is warning
Example output
{
"checks_critical": 1,
"checks_passing": 3,
"checks_warning": 0,
"critical": 1,
"datacenter": "dc1",
"failing_checks": [
{
"check_id": "billing-2-http",
"instance": "billing-2",
"name": "Billing API",
"node": "app-02",
"output": "Get http://10.0.0.22:9002/health: connection refused",
"status": "critical"
}
],
"healthy": false,
"in_maintenance": 0,
"instances": 2,
"link": "https://consul.example.com:8501/ui/dc1/services/billing/instances",
"passing": 1,
"service": "billing",
"status": "critical",
"warning": 0
}List health checks
List the health checks that are failing (or critical, warning, passing, or every one) across the datacenter, or for one service or node, with what each printed.
Inputs
- Which checks
statetext - Which checks to list.One of:
failing(Failing (critical or warning)),critical,warning,passing,any(Every check). Default:failing. - Service
servicetext - Only this service's checks. Leave blank for every service.
- Node
nodetext - Only checks on this node. Leave blank for every node.
- Datacenter
datacentertext - The datacenter, such as dc1. Leave blank for the connection's.
Outputs
checkslist- The checks, critical first, then by node
countnumber- How many checks are listed
criticalnumber- How many are critical
datacentertext- The datacenter, such as dc1
passingnumber- How many are passing
statetext- The checks asked for: failing, critical, warning, passing or any
warningnumber- How many are warning
Example output
{
"checks": [
{
"check_id": "billing-2-http",
"check_type": "http",
"link": "https://consul.example.com:8501/ui/dc1/services/billing/instances/app-02/billing-2/health-checks",
"maintenance": false,
"name": "Billing API",
"node": "app-02",
"notes": "",
"output": "Get http://10.0.0.22:9002/health: connection refused",
"service_id": "billing-2",
"service_name": "billing",
"service_tags": [
"api"
],
"status": "critical"
}
],
"count": 1,
"critical": 1,
"datacenter": "dc1",
"passing": 0,
"state": "failing",
"warning": 0
}List nodes
List the nodes (machines) in a datacenter with their addresses and whether Consul can reach them.
Inputs
- Datacenter
datacentertext - The datacenter, such as dc1. Leave blank for the connection's.
Outputs
countnumber- How many nodes are listed
datacentertext- The datacenter, such as dc1
nodeslist- The nodes, by name
Example output
{
"count": 1,
"datacenter": "dc1",
"nodes": [
{
"address": "10.0.0.21",
"datacenter": "dc1",
"failing_checks": [],
"id": "0c5c3f3e-6d1f-2a1e-9c3b-5d0b2f1a7e44",
"link": "https://consul.example.com:8501/ui/dc1/nodes/app-01/health-checks",
"maintenance": false,
"meta": {
"consul-network-segment": ""
},
"node": "app-01",
"status": "passing"
}
]
}List service instances
List a service's instances with the address and port to reach each, its tags and its health, or only the healthy ones.
Inputs
- Service
servicetextRequired - The service's name, such as web.
- Only healthy instances
passing_onlytrue/false - Leave out instances with a warning or critical check.Default:
false. - Tag
tagtext - Only instances with this tag, such as canary.
- Datacenter
datacentertext - The datacenter, such as dc1. Leave blank for the connection's.
Outputs
countnumber- How many instances are listed
datacentertext- The datacenter, such as dc1
instanceslist- Its instances, by node
passing_onlytrue/false- True when only instances passing every check are listed
servicetext- The service
tagtext- The tag asked for, if one was
Example output
{
"count": 1,
"datacenter": "dc1",
"instances": [
{
"address": "10.0.0.21",
"checks": [
{
"check_id": "serfHealth",
"name": "Serf Health Status",
"output": "Agent alive and reachable",
"status": "passing"
},
{
"check_id": "web-1-http",
"name": "Web home page",
"output": "HTTP GET http://10.0.0.21:8080/: 200 OK",
"status": "passing"
}
],
"datacenter": "dc1",
"id": "web-1",
"link": "https://consul.example.com:8501/ui/dc1/services/web/instances/app-01/web-1",
"maintenance": false,
"meta": {
"version": "2.4.1"
},
"node": "app-01",
"node_address": "10.0.0.21",
"port": 8080,
"service": "web",
"status": "passing",
"tags": [
"frontend",
"v2"
]
}
],
"passing_only": false,
"service": "web",
"tag": ""
}List services
List the services registered in Consul, with their tags, or only those with a tag.
Inputs
- Datacenter
datacentertext - The datacenter, such as dc1. Leave blank for the connection's.
- Tag
tagtext - Only services with this tag, such as api.
Outputs
countnumber- How many services are listed
datacentertext- The datacenter, such as dc1
serviceslist- The services, by name
tagtext- The tag asked for, if one was
Example output
{
"count": 2,
"datacenter": "dc1",
"services": [
{
"link": "https://consul.example.com:8501/ui/dc1/services/billing/instances",
"name": "billing",
"tags": [
"api",
"canary"
]
},
{
"link": "https://consul.example.com:8501/ui/dc1/services/web/instances",
"name": "web",
"tags": [
"frontend",
"v2"
]
}
],
"tag": ""
}Set key value
Set a key's value, such as turning a feature flag on, creating the key if it isn't there. With 'Only if unchanged since', a change someone else made in between is caught rather than overwritten.
Inputs
- Key
keytextRequired - The key, as Consul's Key/Value page shows it, such as config/app/feature_x.
- Value
valuetext - The value to store, such as true. Leave blank for an empty value.
- Only if unchanged since
cas_indexnumber - A modify index from 'Get key value': the change is refused if anything changed the key since. 0 writes only if the key doesn't exist yet. Leave blank to write whatever is there.At least 0.
- Datacenter
datacentertext - The datacenter, such as dc1. Leave blank for the connection's.
Outputs
create_indexnumber- Consul's index when it was created
createdtrue/false- True when the key didn't exist before
datacentertext- The datacenter, such as dc1
keytext- The key written
linktext- A link to the key in Consul
modify_indexnumber- Its new modify index
valuetext- The value it now has
Example output
{
"create_index": 35,
"created": false,
"datacenter": "dc1",
"key": "config/app/feature_x",
"link": "https://consul.example.com:8501/ui/dc1/kv/config/app/feature_x/edit",
"modify_index": 62,
"value": "false"
}Set maintenance mode
Put a service's instances into maintenance mode, such as before a deploy, so Consul stops sending traffic to them, or take them out again. Works for instances registered with the Consul agent at the connection's address.
Inputs
- Service
servicetextRequired - The service's name, such as web.
- Instance
instancetext - One instance, such as web-1. Leave blank for every instance of the service registered with this agent.
- In maintenance
enabletrue/false - On to put them into maintenance, off to take them out.Default:
true. - Reason
reasontext - Why, shown in Consul, such as Deploying 2.5.0.Only when In maintenance is
true.
Outputs
countnumber- How many instances
instanceslist- The instances put into (or out of) maintenance
linktext- A link to the service in Consul
maintenancetrue/false- True when they were put into maintenance, false when taken out
reasontext- The reason given, shown in Consul
servicetext- The service
Example output
{
"count": 1,
"instances": [
"web-1"
],
"link": "https://consul.example.com:8501/ui/dc1/services/web/instances",
"maintenance": true,
"reason": "Deploying 2.5.0",
"service": "web"
}