# HashiCorp Consul

> 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.

App · 12 actions. Web page: https://docs.lodol.com/docs/integrations/hashicorp-consul

## Actions

### 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 (`datacenter`, text): The datacenter, such as dc1. Leave blank for the connection's.

**Outputs**

- `datacenter` (text): The datacenter, such as dc1
- `datacenters` (list): Every datacenter Consul knows, the nearest first
- `healthy` (true/false): True when the datacenter has a leader
- `leader` (text): The leading server's address, such as 10.0.0.5:8300; empty for none
- `server_count` (number): How many servers there are
- `servers` (list): The servers' addresses

**Example output**

```json
{
  "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 (`key`, text, required): The key to delete, or the prefix with 'Everything under it', such as config/old-app/.
- Everything under it (`recurse`, true/false): Delete every key that starts with this, for good. Default: `false`.
- Only if unchanged since (`cas_index`, number): 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 (`datacenter`, text): The datacenter, such as dc1. Leave blank for the connection's.

**Outputs**

- `count` (number): How many keys were deleted
- `datacenter` (text): The datacenter, such as dc1
- `deleted` (true/false): False when there was nothing there to delete
- `key` (text): The key or prefix deleted
- `keys_deleted` (list): The keys deleted
- `recurse` (true/false): True when everything under it was deleted

**Example output**

```json
{
  "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_name`, text, required): The event's name, as the watches expect it, such as deploy.
- Payload (`payload`, text): A short text to send with it, such as a version, up to about 300 characters.
- Only nodes running (`service_filter`, text): Only nodes running this service. Leave blank for every node.
- With tag (`tag_filter`, text): Only nodes running the service with this tag, such as canary.
- Nodes named (`node_filter`, text): Only nodes whose names match this pattern, such as web-.*.
- Datacenter (`datacenter`, text): The datacenter, such as dc1. Leave blank for the connection's.

**Outputs**

- `datacenter` (text): The datacenter, such as dc1
- `id` (text): The event's ID
- `name` (text): The event's name
- `node_filter` (text): Only nodes matching this got it
- `payload` (text): The payload sent with it
- `service_filter` (text): Only nodes running this service got it
- `tag_filter` (text): Only nodes running the service with this tag got it

**Example output**

```json
{
  "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 (`key`, text, required): The key, as Consul's Key/Value page shows it, such as config/app/feature_x.
- Datacenter (`datacenter`, text): The datacenter, such as dc1. Leave blank for the connection's.

**Outputs**

- `create_index` (number): Consul's index when the key was created
- `datacenter` (text): The datacenter, such as dc1
- `flags` (number): The number stored with the key by whoever wrote it; usually 0
- `found` (true/false): False when the key isn't set; its value is then empty
- `is_text` (true/false): False when the value isn't text, such as a file, and is given as base64
- `json` (object): The value read as JSON, when it is a JSON object or list; empty otherwise
- `key` (text): The key, such as config/app/feature_x
- `link` (text): A link to the key in Consul
- `locked` (true/false): True while a Consul lock session holds the key
- `modify_index` (number): Consul's index when the key last changed; give it to 'Set key value' to write only if nothing changed it since
- `value` (text): The value as text (base64 when it isn't text)

**Example output**

```json
{
  "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 (`prefix`, text, required): The folder to read, such as config/app/. Keys under it come back without it.
- Datacenter (`datacenter`, text): The datacenter, such as dc1. Leave blank for the connection's.

**Outputs**

- `count` (number): How many keys were read
- `data` (object): Each key without the prefix, with its value, such as db/host
- `datacenter` (text): The datacenter, such as dc1
- `items` (list): Each key with its value and indexes, in order
- `keys` (list): The keys, in order
- `prefix` (text): The prefix read, such as config/app/
- `tree` (object): The same values nested by folder, such as db then host; a key that is also a folder keeps its value under _value
- `truncated` (true/false): True when there were more keys than Lodol reads at once

**Example output**

```json
{
  "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 (`service`, text, required): The service's name, such as web.
- Datacenter (`datacenter`, text): The datacenter, such as dc1. Leave blank for the connection's.

**Outputs**

- `checks_critical` (number): Checks critical
- `checks_passing` (number): Checks passing
- `checks_warning` (number): Checks warning
- `critical` (number): Instances with a critical check
- `datacenter` (text): The datacenter, such as dc1
- `failing_checks` (list): Each check that isn't passing, with what it printed
- `healthy` (true/false): True when every instance passes every check
- `in_maintenance` (number): Instances in maintenance mode
- `instances` (number): How many instances it has
- `link` (text): A link to the service in Consul
- `passing` (number): Instances passing every check
- `service` (text): The service
- `status` (text): The worst instance's status: passing, warning or critical
- `warning` (number): Instances whose worst check is warning

**Example output**

```json
{
  "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 (`state`, text): Which checks to list. One of: `failing` (Failing (critical or warning)), `critical`, `warning`, `passing`, `any` (Every check). Default: `failing`.
- Service (`service`, text): Only this service's checks. Leave blank for every service.
- Node (`node`, text): Only checks on this node. Leave blank for every node.
- Datacenter (`datacenter`, text): The datacenter, such as dc1. Leave blank for the connection's.

**Outputs**

- `checks` (list): The checks, critical first, then by node
- `count` (number): How many checks are listed
- `critical` (number): How many are critical
- `datacenter` (text): The datacenter, such as dc1
- `passing` (number): How many are passing
- `state` (text): The checks asked for: failing, critical, warning, passing or any
- `warning` (number): How many are warning

**Example output**

```json
{
  "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 (`datacenter`, text): The datacenter, such as dc1. Leave blank for the connection's.

**Outputs**

- `count` (number): How many nodes are listed
- `datacenter` (text): The datacenter, such as dc1
- `nodes` (list): The nodes, by name

**Example output**

```json
{
  "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 (`service`, text, required): The service's name, such as web.
- Only healthy instances (`passing_only`, true/false): Leave out instances with a warning or critical check. Default: `false`.
- Tag (`tag`, text): Only instances with this tag, such as canary.
- Datacenter (`datacenter`, text): The datacenter, such as dc1. Leave blank for the connection's.

**Outputs**

- `count` (number): How many instances are listed
- `datacenter` (text): The datacenter, such as dc1
- `instances` (list): Its instances, by node
- `passing_only` (true/false): True when only instances passing every check are listed
- `service` (text): The service
- `tag` (text): The tag asked for, if one was

**Example output**

```json
{
  "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 (`datacenter`, text): The datacenter, such as dc1. Leave blank for the connection's.
- Tag (`tag`, text): Only services with this tag, such as api.

**Outputs**

- `count` (number): How many services are listed
- `datacenter` (text): The datacenter, such as dc1
- `services` (list): The services, by name
- `tag` (text): The tag asked for, if one was

**Example output**

```json
{
  "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 (`key`, text, required): The key, as Consul's Key/Value page shows it, such as config/app/feature_x.
- Value (`value`, text): The value to store, such as true. Leave blank for an empty value.
- Only if unchanged since (`cas_index`, number): 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 (`datacenter`, text): The datacenter, such as dc1. Leave blank for the connection's.

**Outputs**

- `create_index` (number): Consul's index when it was created
- `created` (true/false): True when the key didn't exist before
- `datacenter` (text): The datacenter, such as dc1
- `key` (text): The key written
- `link` (text): A link to the key in Consul
- `modify_index` (number): Its new modify index
- `value` (text): The value it now has

**Example output**

```json
{
  "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 (`service`, text, required): The service's name, such as web.
- Instance (`instance`, text): One instance, such as web-1. Leave blank for every instance of the service registered with this agent.
- In maintenance (`enable`, true/false): On to put them into maintenance, off to take them out. Default: `true`.
- Reason (`reason`, text): Why, shown in Consul, such as Deploying 2.5.0. Only when In maintenance is `true`.

**Outputs**

- `count` (number): How many instances
- `instances` (list): The instances put into (or out of) maintenance
- `link` (text): A link to the service in Consul
- `maintenance` (true/false): True when they were put into maintenance, false when taken out
- `reason` (text): The reason given, shown in Consul
- `service` (text): The service

**Example output**

```json
{
  "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"
}
```
