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

ActionWhat it does
Check cluster statusCheck that a datacenter's Consul servers have a leader (without one, Consul can't answer or change anything), with its servers.
Delete keyDelete a key, or every key under a prefix.
Fire eventSend a Consul user event, such as deploy, to every node or only those running a service.
Get key valueRead a key's value, such as a feature flag or a setting, to use in a later step.
Get keys under a prefixRead every key under a prefix, such as an app's settings in config/app/, as one object, up to 1000 keys.
Get service healthSee 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 checksList 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 nodesList the nodes (machines) in a datacenter with their addresses and whether Consul can reach them.
List service instancesList a service's instances with the address and port to reach each, its tags and its health, or only the healthy ones.
List servicesList the services registered in Consul, with their tags, or only those with a tag.
Set key valueSet a key's value, such as turning a feature flag on, creating the key if it isn't there.
Set maintenance modePut 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

Datacenterdatacentertext
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

KeykeytextRequired
The key to delete, or the prefix with 'Everything under it', such as config/old-app/.
Everything under itrecursetrue/false
Delete every key that starts with this, for good.Default: false.
Only if unchanged sincecas_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.
Datacenterdatacentertext
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 nameevent_nametextRequired
The event's name, as the watches expect it, such as deploy.
Payloadpayloadtext
A short text to send with it, such as a version, up to about 300 characters.
Only nodes runningservice_filtertext
Only nodes running this service. Leave blank for every node.
With tagtag_filtertext
Only nodes running the service with this tag, such as canary.
Nodes namednode_filtertext
Only nodes whose names match this pattern, such as web-.*.
Datacenterdatacentertext
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

KeykeytextRequired
The key, as Consul's Key/Value page shows it, such as config/app/feature_x.
Datacenterdatacentertext
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

PrefixprefixtextRequired
The folder to read, such as config/app/. Keys under it come back without it.
Datacenterdatacentertext
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

ServiceservicetextRequired
The service's name, such as web.
Datacenterdatacentertext
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 checksstatetext
Which checks to list.One of: failing (Failing (critical or warning)), critical, warning, passing, any (Every check). Default: failing.
Serviceservicetext
Only this service's checks. Leave blank for every service.
Nodenodetext
Only checks on this node. Leave blank for every node.
Datacenterdatacentertext
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

Datacenterdatacentertext
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

ServiceservicetextRequired
The service's name, such as web.
Only healthy instancespassing_onlytrue/false
Leave out instances with a warning or critical check.Default: false.
Tagtagtext
Only instances with this tag, such as canary.
Datacenterdatacentertext
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

Datacenterdatacentertext
The datacenter, such as dc1. Leave blank for the connection's.
Tagtagtext
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

KeykeytextRequired
The key, as Consul's Key/Value page shows it, such as config/app/feature_x.
Valuevaluetext
The value to store, such as true. Leave blank for an empty value.
Only if unchanged sincecas_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.
Datacenterdatacentertext
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

ServiceservicetextRequired
The service's name, such as web.
Instanceinstancetext
One instance, such as web-1. Leave blank for every instance of the service registered with this agent.
In maintenanceenabletrue/false
On to put them into maintenance, off to take them out.Default: true.
Reasonreasontext
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"
}

On this page