Agent HTTP API

The /agent endpoints are used to interact with the local Consul agent. Usually, services and checks are registered with an agent which then takes on the burden of keeping that data synchronized with the cluster. For example, the agent registers services and checks with the Catalog and performs anti-entropy to recover from outages.

In addition to these endpoints, additional endpoints are grouped in the navigation for Checks and Services.

Retrieve host information

This endpoint returns information about the host the agent is running on such as CPU, memory, and disk.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/agent/host

Sample Response

{
  "Memory": {
    "total": 8192864256,
    "available": 7154810880,
    "used": 1406787584,
    "usedPercent": 17.17088847126628,
    "free": 1683918848,
    "active": 2873405440,
    "inactive": 2777124864,
    "wired": 0,
    "laundry": 0,
    "buffers": 131567616,
    "cached": 4970590208,
    "writeBack": 0,
    "dirty": 1069056,
    "writeBackTmp": 0,
    "shared": 9121792,
    "slab": 770506752,
    "sreclaimable": 0,
    "sunreclaim": 0,
    "pageTables": 5103616,
    "swapCached": 143360,
    "commitLimit": 4201283584,
    "committedAS": 1514496000,
    "highTotal": 0,
    "highFree": 0,
    "lowTotal": 0,
    "lowFree": 0,
    "swapTotal": 104853504,
    "swapFree": 99696640,
    "mapped": 313540608,
    "vmallocTotal": 269240696832,
    "vmallocUsed": 25956352,
    "vmallocChunk": 0,
    "hugePagesTotal": 0,
    "hugePagesFree": 0,
    "hugePageSize": 0
  },
  "CPU": [
    {
      "cpu": 0,
      "vendorId": "",
      "family": "",
      "model": "",
      "stepping": 0,
      "physicalId": "",
      "coreId": "0",
      "cores": 1,
      "modelName": "",
      "mhz": 1500,
      "cacheSize": 0,
      "flags": [
        "fp",
        "asimd",
        "evtstrm",
        "crc32",
        "cpuid"
      ],
      "microcode": ""
    },
    {
      "cpu": 1,
      "vendorId": "",
      "family": "",
      "model": "",
      "stepping": 0,
      "physicalId": "",
      "coreId": "1",
      "cores": 1,
      "modelName": "",
      "mhz": 1500,
      "cacheSize": 0,
      "flags": [
        "fp",
        "asimd",
        "evtstrm",
        "crc32",
        "cpuid"
      ],
      "microcode": ""
    },
    {
      "cpu": 2,
      "vendorId": "",
      "family": "",
      "model": "",
      "stepping": 0,
      "physicalId": "",
      "coreId": "2",
      "cores": 1,
      "modelName": "",
      "mhz": 1500,
      "cacheSize": 0,
      "flags": [
        "fp",
        "asimd",
        "evtstrm",
        "crc32",
        "cpuid"
      ],
      "microcode": ""
    },
    {
      "cpu": 3,
      "vendorId": "",
      "family": "",
      "model": "",
      "stepping": 0,
      "physicalId": "",
      "coreId": "3",
      "cores": 1,
      "modelName": "",
      "mhz": 1500,
      "cacheSize": 0,
      "flags": [
        "fp",
        "asimd",
        "evtstrm",
        "crc32",
        "cpuid"
      ],
      "microcode": ""
    }
  ],
  "Host": {
    "hostname": "hashicorp-consul-server-2",
    "uptime": 6855759,
    "bootTime": 1620226737,
    "procs": 1,
    "os": "linux",
    "platform": "alpine",
    "platformFamily": "alpine",
    "platformVersion": "3.13.5",
    "kernelVersion": "5.10.17-v8+",
    "kernelArch": "aarch64",
    "virtualizationSystem": "",
    "virtualizationRole": "",
    "hostId": "7a8ef887-9dbe-4ed3-b45b-c04d7ee6476f"
  },
  "Disk": {
    "path": "/",
    "fstype": "",
    "total": 125550247936,
    "free": 93488398336,
    "used": 26909102080,
    "usedPercent": 22.350216563486036,
    "inodesTotal": 7684080,
    "inodesUsed": 442088,
    "inodesFree": 7241992,
    "inodesUsedPercent": 5.753297727249065
  },
  "CollectionTime": 1627082496166088783,
  "Errors": null
}

List Members

This endpoint returns the members the agent sees in the cluster gossip pool. Due to the nature of gossip, this is eventually consistent: the results may differ by agent. The strongly consistent view of nodes is instead provided by /v1/catalog/nodes.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul members.

Query Parameters

• wan (bool: false) - Specifies to list WAN members instead of the LAN members (which is the default). This is only eligible for agents running in server mode.

• segment (string: "") EnterpriseEnterprise - Specifies the segment to list members for. If left blank, this will query for the default segment when connecting to a server and the agent's own segment when connecting to a client (clients can only be part of one network segment). When querying a server, setting this to the special string _all will show members in all segments.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/agent/members

Sample Response

[
  {
    "Name": "foobar",
    "Addr": "10.1.10.12",
    "Port": 8301,
    "Tags": {
      "bootstrap": "1",
      "dc": "dc1",
      "port": "8300",
      "role": "consul"
    },
    "Status": 1,
    "ProtocolMin": 1,
    "ProtocolMax": 2,
    "ProtocolCur": 2,
    "DelegateMin": 1,
    "DelegateMax": 3,
    "DelegateCur": 3
  }
]

Read Configuration

This endpoint returns the configuration and member information of the local agent. The Config element contains a subset of the configuration and its format will not change in a backwards incompatible way between releases. DebugConfig contains the full runtime configuration but its format is subject to change without notice or deprecation.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/agent/self

Sample Response

{
  "Config": {
    "Datacenter": "dc1",
    "NodeName": "foobar",
    "NodeID": "9d754d17-d864-b1d3-e758-f3fe25a9874f",
    "Server": true,
    "Revision": "deadbeef",
    "Version": "1.0.0"
  },
  "DebugConfig": {
    ... full runtime configuration ...
    ... format subject to change ...
  },
  "Coord": {
    "Adjustment": 0,
    "Error": 1.5,
    "Vec": [0,0,0,0,0,0,0,0]
  },
  "Member": {
    "Name": "foobar",
    "Addr": "10.1.10.12",
    "Port": 8301,
    "Tags": {
      "bootstrap": "1",
      "dc": "dc1",
      "id": "40e4a748-2192-161a-0510-9bf59fe950b5",
      "port": "8300",
      "role": "consul",
      "vsn": "1",
      "vsn_max": "1",
      "vsn_min": "1"
    },
    "Status": 1,
    "ProtocolMin": 1,
    "ProtocolMax": 2,
    "ProtocolCur": 2,
    "DelegateMin": 2,
    "DelegateMax": 4,
    "DelegateCur": 4
  },
  "Meta": {
    "instance_type": "i2.xlarge",
    "os_version": "ubuntu_16.04"
  }
}

Reload Agent

This endpoint instructs the agent to reload its configuration. Any errors encountered during this process are returned.

Not all configuration options are reloadable. See the Reloadable Configuration section on the agent options page for details on which options are supported.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul reload.

Sample Request

$ curl \
    --request PUT \
    http://127.0.0.1:8500/v1/agent/reload

Enable Maintenance Mode

This endpoint places the agent into "maintenance mode". During maintenance mode, the node will be marked as unavailable and will not be present in DNS or API queries. This API call is idempotent.

Maintenance mode is persistent and will be automatically restored on agent restart.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul maint.

Query Parameters

• enable (bool: <required>) - Specifies whether to enable or disable maintenance mode.

• reason (string: "") - Specifies a text string explaining the reason for placing the node into maintenance mode. This is simply to aid human operators. If no reason is provided, a default value is used instead. This parameter must be URI-encoded.

Sample Request

$ curl \
    --request PUT \
    http://127.0.0.1:8500/v1/agent/maintenance?enable=true&reason=For+API+docs

View Metrics

This endpoint will dump the metrics for the most recent finished interval. For more information about metrics, see the telemetry page.

In order to enable Prometheus support, you need to use the configuration directive prometheus_retention_time.

Since Consul 1.7.2 this endpoint will also automatically switch output format if the request contains an Accept header with a compatible MIME type such as application/openmetrics-text. Prometheus v2.5.0 and newer pass this header in scraping queries, and so will get a compatible format by default. Older versions of Prometheus may work by default as several previously used MIME types are also detected, but the ?format query parameter may also be used to specify the output format manually if needed. simplifying scrape configuration.

Note: If using the default format and your metric includes labels that use the same key name multiple times (i.e. tag=tag2 and tag=tag1), only the sorted last value (tag=tag2) will be visible on this endpoint due to a display issue. The complete label set is correctly applied and passed to external metrics providers even though it is not visible through this endpoint.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/agent/metrics

Sample Response

{
  "Timestamp": "2017-08-08 02:55:10 +0000 UTC",
  "Gauges": [
    {
      "Name": "consul.consul.session_ttl.active",
      "Value": 0,
      "Labels": {}
    },
    {
      "Name": "consul.runtime.alloc_bytes",
      "Value": 4704344,
      "Labels": {}
    },
    {
      "Name": "consul.runtime.free_count",
      "Value": 74063,
      "Labels": {}
    }
  ],
  "Points": [],
  "Counters": [
    {
      "Name": "consul.consul.catalog.service.query",
      "Count": 1,
      "Sum": 1,
      "Min": 1,
      "Max": 1,
      "Mean": 1,
      "Stddev": 0,
      "Labels": {
        "service": "consul"
      }
    },
    {
      "Name": "consul.raft.apply",
      "Count": 1,
      "Sum": 1,
      "Min": 1,
      "Max": 1,
      "Mean": 1,
      "Stddev": 0,
      "Labels": {}
    }
  ],
  "Samples": [
    {
      "Name": "consul.consul.http.GET.v1.agent.metrics",
      "Count": 1,
      "Sum": 0.1817069947719574,
      "Min": 0.1817069947719574,
      "Max": 0.1817069947719574,
      "Mean": 0.1817069947719574,
      "Stddev": 0,
      "Labels": {}
    },
    {
      "Name": "consul.consul.http.GET.v1.catalog.service._",
      "Count": 1,
      "Sum": 0.23342099785804749,
      "Min": 0.23342099785804749,
      "Max": 0.23342099785804749,
      "Mean": 0.23342099785804749,
      "Stddev": 0,
      "Labels": {}
    },
    {
      "Name": "consul.serf.queue.Query",
      "Count": 20,
      "Sum": 0,
      "Min": 0,
      "Max": 0,
      "Mean": 0,
      "Stddev": 0,
      "Labels": {}
    }
  ]
}

• Timestamp is the timestamp of the interval for the displayed metrics. Metrics are aggregated on a ten second interval, so this value (along with the displayed metrics) will change every ten seconds.

• Gauges is a list of gauges which store one value that is updated as time goes on, such as the amount of memory allocated.

• Points is a list of point metrics, which each store a series of points under a given name.

• Counters is a list of counters, which store info about a metric that is incremented over time such as the number of requests to an HTTP endpoint.

• Samples is a list of samples, which store info about the amount of time spent on an operation, such as the time taken to serve a request to a specific http endpoint.

Stream Logs

This endpoint streams logs from the local agent until the connection is closed.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Query Parameters

• loglevel (string: "info") - Specifies a text string containing a log level to filter on, such as info.

• logjson (bool: false) - Specifies whether the logs will be output in JSON format.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/agent/monitor

Sample Response

YYYY/MM/DD HH:MM:SS [INFO] raft: Initial configuration (index=1): [{Suffrage:Voter ID:127.0.0.1:8300 Address:127.0.0.1:8300}]
YYYY/MM/DD HH:MM:SS [INFO] raft: Node at 127.0.0.1:8300 [Follower] entering Follower state (Leader: "")
YYYY/MM/DD HH:MM:SS [INFO] serf: EventMemberJoin: machine-osx 127.0.0.1
YYYY/MM/DD HH:MM:SS [INFO] consul: Adding LAN server machine-osx (Addr: tcp/127.0.0.1:8300) (DC: dc1)
YYYY/MM/DD HH:MM:SS [INFO] serf: EventMemberJoin: machine-osx.dc1 127.0.0.1
YYYY/MM/DD HH:MM:SS [INFO] consul: Handled member-join event for server "machine-osx.dc1" in area "wan"
# ...

Join Agent

This endpoint instructs the agent to attempt to connect to a given address.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul join.

Path Parameters

• address (string: <required>) - Specifies the address of the other agent to join.

Query Parameters

• wan (bool: false) - Specifies to try and join over the WAN pool. This is only optional for agents running in server mode.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/agent/join/1.2.3.4

Graceful Leave and Shutdown

This endpoint triggers a graceful leave and shutdown of the agent. It is used to ensure other nodes see the agent as "left" instead of "failed". Nodes that leave will not attempt to re-join the cluster on restarting with a snapshot.

For nodes in server mode, the node is removed from the Raft peer set in a graceful manner. This is critical, as in certain situations a non-graceful leave can affect cluster availability.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul leave.

Sample Request

$ curl \
    --request PUT \
    http://127.0.0.1:8500/v1/agent/leave

Force Leave and Shutdown

This endpoint instructs the agent to force a node into the left state in the LAN and WAN gossip pools. If a node fails unexpectedly, then it will be in a failed state. Once in the failed state, Consul will attempt to reconnect, and the services and checks belonging to that node will not be cleaned up. Forcing a node into the left state allows its old entries to be removed.

Additionally, by specifying the prune flag, a node can be forcibly removed from the list of members entirely.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul force-leave.

Path Parameters

• node_name (string: <required>) - Specifies the name of the node to be forced into left state.

Query Parameters

• prune (bool: false) - Specifies whether to forcibly remove the node from the list of members. Pruning a node in the left or failed state removes it from the list altogether. Added in Consul 1.6.2.

• wan (bool: false) - Specifies the node should only be removed from the WAN gossip pool. Added in Consul 1.11.0.

Sample Request

$ curl \
    --request PUT \
    http://127.0.0.1:8500/v1/agent/force-leave/agent-one

Update ACL Tokens

This endpoint updates the ACL tokens currently in use by the agent. It can be used to introduce ACL tokens to the agent for the first time, or to update tokens that were initially loaded from the agent's configuration. Tokens will be persisted only if the acl.enable_token_persistence configuration is true. When not being persisted, they will need to be reset if the agent is restarted.

The paths above correspond to the token names as found in the agent configuration: default, agent, agent_recovery, config_file_service_registration, and replication.

The paths above correspond to the token names as found in the agent configuration: agent_master.

The paths above correspond to the token names as found in the agent configuration: acl_token, acl_agent_token, acl_agent_master_token, and acl_replication_token.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul acl set-agent-token.

JSON Request Body Schema

• Token (string: "") - Specifies the ACL token to set.

Sample Payload

{
  "Token": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}

Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/agent/token/acl_token