luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-consul/website/source/api/agent.html.md

580 lines
20 KiB
Markdown
Raw Normal View History

Update API docs
2017-04-04 16:33:22 +00:00
---
layout: api
page_title: Agent - HTTP API
sidebar_current: api-agent
description: |-
The /agent endpoints interact with the local Consul agent to register
services, checks, list members, and more.
---
# 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](/docs/internals/anti-entropy.html) to recover from outages.
In addition to these endpoints, additional endpoints are grouped in the
navigation for `Checks` and `Services`.
## 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`.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/agent/members` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
[consistency modes](/api/index.html#consistency-modes),
[agent caching](/api/index.html#agent-caching), and
Update API docs
2017-04-04 16:33:22 +00:00
[required ACLs](/api/index.html#acls).
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `node:read` |
Update API docs
2017-04-04 16:33:22 +00:00
### 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**. This is specified as part of the URL as a query parameter.
Makes the all segments query explict, and the default for `consul members`.
2017-09-05 19:22:20 +00:00
- `segment` `(string: "")` - (Enterprise-only) 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.
Add doc sections for network segments
2017-08-31 18:19:08 +00:00
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
```text
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/agent/members
Update API docs
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
[
{
"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
Provide stable config for agent/self (#3532) * config: provide stable config for /v1/agent/self (#3530) This patch adds a stable subset of the previous Config struct to the agent/self response. The actual runtime configuration is moved into DebugConfig and will be documented to change. Fixes #3530 * config: fix tests * doc: update api documentation for /v1/agent/self
2017-10-04 17:43:17 +00:00
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.
Update API docs
2017-04-04 16:33:22 +00:00
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/agent/self` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
[consistency modes](/api/index.html#consistency-modes),
[agent caching](/api/index.html#agent-caching), and
Update API docs
2017-04-04 16:33:22 +00:00
[required ACLs](/api/index.html#acls).
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `agent:read` |
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
```text
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/agent/self
Update API docs
2017-04-04 16:33:22 +00:00
```
### Sample Response
```json
{
"Config": {
"Datacenter": "dc1",
"NodeName": "foobar",
Adds the NodeID field back to the /v1/agent/self Config block. Fixes #3778
2018-01-10 23:17:33 +00:00
"NodeID": "9d754d17-d864-b1d3-e758-f3fe25a9874f",
Provide stable config for agent/self (#3532) * config: provide stable config for /v1/agent/self (#3530) This patch adds a stable subset of the previous Config struct to the agent/self response. The actual runtime configuration is moved into DebugConfig and will be documented to change. Fixes #3530 * config: fix tests * doc: update api documentation for /v1/agent/self
2017-10-04 17:43:17 +00:00
"Server": true,
"Revision": "deadbeef",
"Version": "1.0.0"
},
"DebugConfig": {
... full runtime configuration ...
... format subject to change ...
Update API docs
2017-04-04 16:33:22 +00:00
},
"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",
Fix invalid JSON in agent-api /v1/self example output. (#3183)
2017-06-24 23:16:27 +00:00
"os_version": "ubuntu_16.04"
Update API docs
2017-04-04 16:33:22 +00:00
}
}
```
## 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](/docs/agent/options.html#reloadable-configuration)
section on the agent options page for details on which options are supported.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/agent/reload` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
[consistency modes](/api/index.html#consistency-modes),
[agent caching](/api/index.html#agent-caching), and
Update API docs
2017-04-04 16:33:22 +00:00
[required ACLs](/api/index.html#acls).
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `agent:write` |
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
```text
$ curl \
--request PUT \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/agent/reload
Update API docs
2017-04-04 16:33:22 +00:00
```
## 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.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/agent/maintenance` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
[consistency modes](/api/index.html#consistency-modes),
[agent caching](/api/index.html#agent-caching), and
Update API docs
2017-04-04 16:33:22 +00:00
[required ACLs](/api/index.html#acls).
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `node:write` |
Update API docs
2017-04-04 16:33:22 +00:00
### Parameters
- `enable` `(bool: <required>)` - Specifies whether to enable or disable
maintenance mode. This is specified as part of the URL as a query string
parameter.
- `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 will be used instead. This is
specified as part of the URL as a query string parameter, and, as such, must
be URI-encoded.
### Sample Request
```text
$ curl \
--request PUT \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/agent/maintenance?enable=true&reason=For+API+docs
Update API docs
2017-04-04 16:33:22 +00:00
```
Add support for labels/filters from go-metrics
2017-08-08 08:31:38 +00:00
## View Metrics
This endpoint will dump the metrics for the most recent finished interval.
For more information about metrics, see the [telemetry](/docs/agent/telemetry.html)
page.
Added documentation for telemetry{ prometheus_retention_time = duration }
2018-04-06 12:50:03 +00:00
In order to enable [Prometheus](https://prometheus.io/) support, you need to use the
configuration directive
[`prometheus_retention_time`](/docs/agent/options.html#telemetry-prometheus_retention_time).
ACL Token Persistence and Reloading (#5328) This PR adds two features which will be useful for operators when ACLs are in use. 1. Tokens set in configuration files are now reloadable. 2. If `acl.enable_token_persistence` is set to `true` in the configuration, tokens set via the `v1/agent/token` endpoint are now persisted to disk and loaded when the agent starts (or during configuration reload) Note that token persistence is opt-in so our users who do not want tokens on the local disk will see no change. Some other secondary changes: * Refactored a bunch of places where the replication token is retrieved from the token store. This token isn't just for replicating ACLs and now it is named accordingly. * Allowed better paths in the `v1/agent/token/` API. Instead of paths like: `v1/agent/token/acl_replication_token` the path can now be just `v1/agent/token/replication`. The old paths remain to be valid. * Added a couple new API functions to set tokens via the new paths. Deprecated the old ones and pointed to the new names. The names are also generally better and don't imply that what you are setting is for ACLs but rather are setting ACL tokens. There is a minor semantic difference there especially for the replication token as again, its no longer used only for ACL token/policy replication. The new functions will detect 404s and fallback to using the older token paths when talking to pre-1.4.3 agents. * Docs updated to reflect the API additions and to show using the new endpoints. * Updated the ACL CLI set-agent-tokens command to use the non-deprecated APIs.
2019-02-27 19:28:31 +00:00
Note: If 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
Update docs to include multiple tag support (#4797) * Update docs to include multiple tag support * Sort tags before using them in metrics This addresses the potential proliferation of metrics if a query of "?tag=foo&tag=bar" is treated differently than "?tag=bar&tag=foo". Now, tags are always sorted before being recorded, making these two emit the same metric. * Add caveat about multiple tags returned by the metrics endpoint
2018-10-19 15:52:17 +00:00
passed to external metrics providers even though it is not visible through this endpoint.
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Method | Path | Produces |
| ------ | ---------------------------------- | ------------------------------------------ |
| `GET` | `/agent/metrics` | `application/json` |
| `GET` | `/agent/metrics?format=prometheus` | `text/plain; version=0.0.4; charset=utf-8` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes),
[agent caching](/api/index.html#agent-caching), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `agent:read` |
Add support for labels/filters from go-metrics
2017-08-08 08:31:38 +00:00
### Sample Request
```text
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/agent/metrics
Add support for labels/filters from go-metrics
2017-08-08 08:31:38 +00:00
```
### Sample Response
```json
{
"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": {}
}
]
}
```
Update docs for metrics endpoint
2017-08-08 19:33:30 +00:00
- `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.
Update API docs
2017-04-04 16:33:22 +00:00
## Stream Logs
This endpoint streams logs from the local agent until the connection is closed.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/agent/monitor` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
[consistency modes](/api/index.html#consistency-modes),
[agent caching](/api/index.html#agent-caching), and
Update API docs
2017-04-04 16:33:22 +00:00
[required ACLs](/api/index.html#acls).
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `agent:read` |
Update API docs
2017-04-04 16:33:22 +00:00
### Parameters
- `loglevel` `(string: "info")` - Specifies a text string containing a log level
to filter on, such as `info`.
### Sample Request
```text
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/agent/monitor
Update API docs
2017-04-04 16:33:22 +00:00
```
### Sample Response
```text
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.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
agent: consolidate handling of 405 Method Not Allowed (#3405) * agent: consolidate http method not allowed checks This patch uses the error handling of the http handlers to handle HTTP method not allowed errors across all available endpoints. It also adds a test for testing whether the endpoints respond with the correct status code. * agent: do not panic on metrics tests * agent: drop other tests for MethodNotAllowed * agent: align /agent/join with reality /agent/join uses PUT instead of GET as documented. * agent: align /agent/check/{fail,warn,pass} with reality /agent/check/{fail,warn,pass} uses PUT instead of GET as documented. * fix some tests * Drop more tests for method not allowed * Align TestAgent_RegisterService_InvalidAddress with reality * Changes API client join to use PUT instead of GET. * Fixes agent endpoint verbs and removes obsolete tests. * Updates the change log.
2017-09-26 06:11:19 +00:00
| `PUT` | `/agent/join/:address` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
[consistency modes](/api/index.html#consistency-modes),
[agent caching](/api/index.html#agent-caching), and
Update API docs
2017-04-04 16:33:22 +00:00
[required ACLs](/api/index.html#acls).
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `agent:write` |
Update API docs
2017-04-04 16:33:22 +00:00
### Parameters
- `address` `(string: <required>)` - Specifies the address of the other agent to
join. This is specified as part of the URL.
- `wan` `(bool: false)` - Specifies to try and join over the WAN pool. This is
only optional for agents running in server mode. This is specified as part of
the URL as a query parameter
### Sample Request
```text
$ curl \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/agent/join/1.2.3.4
Update API docs
2017-04-04 16:33:22 +00:00
```
## 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.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/agent/leave` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
[consistency modes](/api/index.html#consistency-modes),
[agent caching](/api/index.html#agent-caching), and
Update API docs
2017-04-04 16:33:22 +00:00
[required ACLs](/api/index.html#acls).
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `agent:write` |
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
```text
$ curl \
--request PUT \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/agent/leave
Update API docs
2017-04-04 16:33:22 +00:00
```
## Force Leave and Shutdown
This endpoint instructs the agent to force a node into the `left` state. 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.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
website: mention node name for "agent/force-leave" HTTP endpoint (#4542) * Adjust documentation for agent/force-leave endpoint A node must be specified when calling agent/force-leave. See: - https://github.com/hashicorp/consul/blob/master/agent/http_oss.go#L25 - https://github.com/hashicorp/consul/blob/master/agent/agent_endpoint.go#L323 - https://github.com/hashicorp/consul/blob/master/agent/agent.go#L1442 However, the documentation does not specify it. Note that Consul returns "301 Moved Permanently v1/agent/force-leave/" when sending PUT request on "v1/agent/force-leave". * Switch from node id to node name
2018-10-24 15:20:05 +00:00
| `PUT` | `/agent/force-leave/:node` | `application/json` |
Update API docs
2017-04-04 16:33:22 +00:00
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
[consistency modes](/api/index.html#consistency-modes),
[agent caching](/api/index.html#agent-caching), and
Update API docs
2017-04-04 16:33:22 +00:00
[required ACLs](/api/index.html#acls).
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `agent:write` |
Update API docs
2017-04-04 16:33:22 +00:00
website: mention node name for "agent/force-leave" HTTP endpoint (#4542) * Adjust documentation for agent/force-leave endpoint A node must be specified when calling agent/force-leave. See: - https://github.com/hashicorp/consul/blob/master/agent/http_oss.go#L25 - https://github.com/hashicorp/consul/blob/master/agent/agent_endpoint.go#L323 - https://github.com/hashicorp/consul/blob/master/agent/agent.go#L1442 However, the documentation does not specify it. Note that Consul returns "301 Moved Permanently v1/agent/force-leave/" when sending PUT request on "v1/agent/force-leave". * Switch from node id to node name
2018-10-24 15:20:05 +00:00
### Parameters
- `node` `(string: <required>)` - Specifies the name of the node to be forced into `left` state. This is specified as part of the URL.
Update API docs
2017-04-04 16:33:22 +00:00
### Sample Request
```text
$ curl \
--request PUT \
website: mention node name for "agent/force-leave" HTTP endpoint (#4542) * Adjust documentation for agent/force-leave endpoint A node must be specified when calling agent/force-leave. See: - https://github.com/hashicorp/consul/blob/master/agent/http_oss.go#L25 - https://github.com/hashicorp/consul/blob/master/agent/agent_endpoint.go#L323 - https://github.com/hashicorp/consul/blob/master/agent/agent.go#L1442 However, the documentation does not specify it. Note that Consul returns "301 Moved Permanently v1/agent/force-leave/" when sending PUT request on "v1/agent/force-leave". * Switch from node id to node name
2018-10-24 15:20:05 +00:00
http://127.0.0.1:8500/v1/agent/force-leave/agent-one
Update API docs
2017-04-04 16:33:22 +00:00
```
Adds support for agent-side ACL token management via API instead of config files. (#3324) * Adds token store and removes all runtime use of config for ACL tokens. * Adds a new API for changing agent tokens on the fly.
2017-07-26 18:03:43 +00:00
## 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
ACL Token Persistence and Reloading (#5328) This PR adds two features which will be useful for operators when ACLs are in use. 1. Tokens set in configuration files are now reloadable. 2. If `acl.enable_token_persistence` is set to `true` in the configuration, tokens set via the `v1/agent/token` endpoint are now persisted to disk and loaded when the agent starts (or during configuration reload) Note that token persistence is opt-in so our users who do not want tokens on the local disk will see no change. Some other secondary changes: * Refactored a bunch of places where the replication token is retrieved from the token store. This token isn't just for replicating ACLs and now it is named accordingly. * Allowed better paths in the `v1/agent/token/` API. Instead of paths like: `v1/agent/token/acl_replication_token` the path can now be just `v1/agent/token/replication`. The old paths remain to be valid. * Added a couple new API functions to set tokens via the new paths. Deprecated the old ones and pointed to the new names. The names are also generally better and don't imply that what you are setting is for ACLs but rather are setting ACL tokens. There is a minor semantic difference there especially for the replication token as again, its no longer used only for ACL token/policy replication. The new functions will detect 404s and fallback to using the older token paths when talking to pre-1.4.3 agents. * Docs updated to reflect the API additions and to show using the new endpoints. * Updated the ACL CLI set-agent-tokens command to use the non-deprecated APIs.
2019-02-27 19:28:31 +00:00
tokens that were initially loaded from the agent's configuration. Tokens will be persisted
only if the [`acl.enable_token_persistence`](/docs/agent/options.html#acl_enable_token_persistence)
configuration is `true`. When not being persisted, they will need to be reset if the agent
is restarted.
| Method | Path | Produces |
| ------ | --------------------------- | -------------------------- |
| `PUT` | `/agent/token/default` | `application/json` |
| `PUT` | `/agent/token/agent` | `application/json` |
| `PUT` | `/agent/token/agent_master` | `application/json` |
| `PUT` | `/agent/token/replication` | `application/json` |
The paths above correspond to the token names as found in the agent configuration:
[`default`](/docs/agent/options.html#acl_tokens_default), [`agent`](/docs/agent/options.html#acl_tokens_agent),
[`agent_master`](/docs/agent/options.html#acl_tokens_agent_master), and
[`replication`](/docs/agent/options.html#acl_tokens_replication).
-> **Deprecation Note:** The following paths were deprecated in version 1.4.3
Adds support for agent-side ACL token management via API instead of config files. (#3324) * Adds token store and removes all runtime use of config for ACL tokens. * Adds a new API for changing agent tokens on the fly.
2017-07-26 18:03:43 +00:00
| Method | Path | Produces |
| ------ | ------------------------------------- | -------------------------- |
| `PUT` | `/agent/token/acl_token` | `application/json` |
| `PUT` | `/agent/token/acl_agent_token` | `application/json` |
| `PUT` | `/agent/token/acl_agent_master_token` | `application/json` |
Adds secure introduction for the ACL replication token. (#3357) Adds secure introduction for the ACL replication token, as well as a separate enable config for ACL replication.
2017-08-03 22:39:31 +00:00
| `PUT` | `/agent/token/acl_replication_token` | `application/json` |
Adds support for agent-side ACL token management via API instead of config files. (#3324) * Adds token store and removes all runtime use of config for ACL tokens. * Adds a new API for changing agent tokens on the fly.
2017-07-26 18:03:43 +00:00
Adds secure introduction for the ACL replication token. (#3357) Adds secure introduction for the ACL replication token, as well as a separate enable config for ACL replication.
2017-08-03 22:39:31 +00:00
The paths above correspond to the token names as found in the agent configuration:
ACL Token Persistence and Reloading (#5328) This PR adds two features which will be useful for operators when ACLs are in use. 1. Tokens set in configuration files are now reloadable. 2. If `acl.enable_token_persistence` is set to `true` in the configuration, tokens set via the `v1/agent/token` endpoint are now persisted to disk and loaded when the agent starts (or during configuration reload) Note that token persistence is opt-in so our users who do not want tokens on the local disk will see no change. Some other secondary changes: * Refactored a bunch of places where the replication token is retrieved from the token store. This token isn't just for replicating ACLs and now it is named accordingly. * Allowed better paths in the `v1/agent/token/` API. Instead of paths like: `v1/agent/token/acl_replication_token` the path can now be just `v1/agent/token/replication`. The old paths remain to be valid. * Added a couple new API functions to set tokens via the new paths. Deprecated the old ones and pointed to the new names. The names are also generally better and don't imply that what you are setting is for ACLs but rather are setting ACL tokens. There is a minor semantic difference there especially for the replication token as again, its no longer used only for ACL token/policy replication. The new functions will detect 404s and fallback to using the older token paths when talking to pre-1.4.3 agents. * Docs updated to reflect the API additions and to show using the new endpoints. * Updated the ACL CLI set-agent-tokens command to use the non-deprecated APIs.
2019-02-27 19:28:31 +00:00
[`acl_token`](/docs/agent/options.html#acl_token_legacy), [`acl_agent_token`](/docs/agent/options.html#acl_agent_token_legacy),
[`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token_legacy), and
[`acl_replication_token`](/docs/agent/options.html#acl_replication_token_legacy).
Adds support for agent-side ACL token management via API instead of config files. (#3324) * Adds token store and removes all runtime use of config for ACL tokens. * Adds a new API for changing agent tokens on the fly.
2017-07-26 18:03:43 +00:00
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
[consistency modes](/api/index.html#consistency-modes),
[agent caching](/api/index.html#agent-caching), and
Adds support for agent-side ACL token management via API instead of config files. (#3324) * Adds token store and removes all runtime use of config for ACL tokens. * Adds a new API for changing agent tokens on the fly.
2017-07-26 18:03:43 +00:00
[required ACLs](/api/index.html#acls).
Support Agent Caching for Service Discovery Results (#4541) * Add cache types for catalog/services and health/services and basic test that caching works * Support non-blocking cache types with Cache-Control semantics. * Update API docs to include caching info for every endpoint. * Comment updates per PR feedback. * Add note on caching to the 10,000 foot view on the architecture page to make the new data path more clear. * Document prepared query staleness quirk and force all background requests to AllowStale so we can spread service discovery load across servers.
2018-09-06 10:34:28 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------- |
| `NO` | `none` | `none` | `agent:write` |
Adds support for agent-side ACL token management via API instead of config files. (#3324) * Adds token store and removes all runtime use of config for ACL tokens. * Adds a new API for changing agent tokens on the fly.
2017-07-26 18:03:43 +00:00
### Parameters
- `Token` `(string: "")` - Specifies the ACL token to set.
### Sample Payload
```json
{
"Token": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
website: use 127.0.0.1 instead of consul.rocks (#4523) By default, the Consul agent listens on the local interface at port 8500 for API requests. This change makes the API examples using `curl` copy-pasteable for this default configuration.
2018-08-28 16:07:15 +00:00
http://127.0.0.1:8500/v1/agent/token/acl_token
Adds support for agent-side ACL token management via API instead of config files. (#3324) * Adds token store and removes all runtime use of config for ACL tokens. * Adds a new API for changing agent tokens on the fly.
2017-07-26 18:03:43 +00:00
```