luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Update API docs

This commit is contained in:
Seth Vargo 2017-04-04 12:33:22 -04:00
parent e9c53e6b89
commit b0bb01d5da
No known key found for this signature in database
GPG Key ID: C921994F9C27E0FF
74 changed files with 5337 additions and 3815 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

343
website/source/api/acl.html.md Normal file
View File

@ -0,0 +1,343 @@
---
layout: api
page_title: ACLs - HTTP API
sidebar_current: api-acls
description: |-
The /acl endpoints create, update, destroy, and query ACL tokens in Consul.
---
# ACL HTTP API
The `/acl` endpoints create, update, destroy, and query ACL tokens in Consul.
## Create ACL Token
This endpoint makes a new ACL token.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/acl/create` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `management` |
### Parameters
- `ID` `(string: "")` - Specifies the ID of the ACL. If not provided, a UUID is
generated.
- `Name` `(string: "")` - Specifies a human-friendly name for the ACL token.
- `Type` `(string: "client")` - Specifies the type of ACL token. Valid values
are: `client` and `management`.
- `Rules` `(string: "")` - Specifies rules for this ACL token. The format of the
`Rules` property is [documented here](/docs/internals/acl.html).
### Sample Payload
```json
{
"Name": "my-app-token",
"Type": "client",
"Rules": ""
}
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/acl/create
```
### Sample Response
```json
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
```
## Update ACL Token
This endpoint is used to modify the policy for a given ACL token. Instead of
generating a new token ID, the `ID` field must be provided.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/acl/update` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `management` |
### Parameters
The parameters are the same as the _create_ endpoint, except the `ID` field is
required.
### Sample Payload
```json
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Name": "my-app-token-updated",
"Type": "client",
"Rules": "# New Rules",
}
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/acl/update
```
## Delete ACL Token
This endpoint deletes an ACL token with the given ID.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/acl/destroy/:uuid` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `management` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to
destroy. This is required and is specified as part of the URL path.
### Sample Request
```text
$ curl \
--request PUT \
https://consul.rocks/v1/acl/destroy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
## Read ACL Token
This endpoint reads an ACL token with the given ID.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/acl/info/:uuid` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `all` | `none` |
Note: No ACL is required because the ACL is specified in the URL path.
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to
destroy. This is required and is specified as part of the URL path.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/acl/info/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
### Sample Response
```json
[
{
"CreateIndex": 3,
"ModifyIndex": 3,
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"Name": "Client Token",
"Type": "client",
"Rules": "..."
}
]
```
## Clone ACL Token
This endpoint clones an ACL and returns a new token `ID`. This allows a token to
serve as a template for others, making it simple to generate new tokens without
complex rule management.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/acl/clone/:uuid` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `management` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to
destroy. This is required and is specified as part of the URL path.
### Sample Request
```text
$ curl \
--request PUT \
https://consul.rocks/v1/acl/clone/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
### Sample Response
```json
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
```
## List ACLs
This endpoint lists all the active ACL tokens.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/acl/list` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `all` | `management` |
### Sample Request
```text
$ curl \
https://consul.rocks/v1/acl/list
```
### Sample Response
```json
[
{
"CreateIndex": 3,
"ModifyIndex": 3,
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"Name": "Client Token",
"Type": "client",
"Rules": "..."
}
]
```
## Check ACL Replication
This endpoint returns the status of the ACL replication process in the
datacenter. This is intended to be used by operators, or by automation checking
the health of ACL replication.
Please see the [ACL replication](/docs/internals/acl.html#replication) section
of the internals guide for more details.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/acl/replication` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `consistent` | `none` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/acl/replication
```
### Sample Response
```json
{
"Enabled": true,
"Running": true,
"SourceDatacenter": "dc1",
"ReplicatedIndex": 1976,
"LastSuccess": "2016-08-05T06:28:58Z",
"LastError": "2016-08-05T06:28:28Z"
}
```
- `Enabled` reports whether ACL replication is enabled for the datacenter.
- `Running` reports whether the ACL replication process is running. The process
may take approximately 60 seconds to begin running after a leader election
occurs.
- `SourceDatacenter` is the authoritative ACL datacenter that ACLs are being
replicated from, and will match the
[`acl_datacenter`](/docs/agent/options.html#acl_datacenter) configuration.
- `ReplicatedIndex` is the last index that was successfully replicated. You can
compare this to the `X-Consul-Index` header returned by the
[`/v1/acl/list`](#acl_list) endpoint to determine if the replication process
has gotten all available ACLs. Replication runs as a background process
approximately every 30 seconds, and that local updates are rate limited to 100
updates/second, so so it may take several minutes to perform the initial sync
of a large set of ACLs. After the initial sync, replica lag should be on the
order of about 30 seconds.
- `LastSuccess` is the UTC time of the last successful sync operation. Since ACL
replication is done with a blocking query, this may not update for up to 5
minutes if there have been no ACL changes to replicate. A zero value of
"0001-01-01T00:00:00Z" will be present if no sync has been successful.
- `LastError` is the UTC time of the last error encountered during a sync
operation. If this time is later than `LastSuccess`, you can assume the
replication process is not in a good state. A zero value of
"0001-01-01T00:00:00Z" will be present if no sync has resulted in an error.

384
website/source/api/agent.html.md Normal file
View File

@ -0,0 +1,384 @@
---
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),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `node:read` |
### 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.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/agent/members
```
### 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
agent.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/agent/self` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `agent:read` |
### Sample Request
```text
$ curl \
https://consul.rocks/v1/agent/self
```
### Sample Response
```json
{
"Config": {
"Bootstrap": true,
"Server": true,
"Datacenter": "dc1",
"DataDir": "/tmp/consul",
"DNSRecursor": "",
"DNSRecursors": [],
"Domain": "consul.",
"LogLevel": "INFO",
"NodeID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"NodeName": "foobar",
"ClientAddr": "127.0.0.1",
"BindAddr": "0.0.0.0",
"AdvertiseAddr": "10.1.10.12",
"Ports": {
"DNS": 8600,
"HTTP": 8500,
"RPC": 8400,
"SerfLan": 8301,
"SerfWan": 8302,
"Server": 8300
},
"LeaveOnTerm": false,
"SkipLeaveOnInt": false,
"StatsiteAddr": "",
"Protocol": 1,
"EnableDebug": false,
"VerifyIncoming": false,
"VerifyOutgoing": false,
"CAFile": "",
"CertFile": "",
"KeyFile": "",
"StartJoin": [],
"UiDir": "",
"PidFile": "",
"EnableSyslog": false,
"RejoinAfterLeave": false
},
"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](/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),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------- |
| `NO` | `none` | `agent:write` |
### Sample Request
```text
$ curl \
--request PUT \
https://consul.rocks/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.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/agent/maintenance` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `node:write` |
### 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 \
https://consul.rocks/v1/agent/maintenance?enable=true&reason=For+API+docs
```
## 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),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `agent:read` |
### Parameters
- `loglevel` `(string: "info")` - Specifies a text string containing a log level
to filter on, such as `info`.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/agent/monitor
```
### 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 |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/agent/join/:address` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------- |
| `NO` | `none` | `agent:write` |
### 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 \
https://consul.rocks/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.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/agent/leave` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------- |
| `NO` | `none` | `agent:write` |
### Sample Request
```text
$ curl \
--request PUT \
https://consul.rocks/v1/agent/leave
```
## 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 |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/agent/force-leave` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------- |
| `NO` | `none` | `agent:write` |
### Sample Request
```text
$ curl \
--request PUT \
https://consul.rocks/v1/agent/force-leave
```

346
website/source/api/agent/check.html.md Normal file
View File

@ -0,0 +1,346 @@
---
layout: api
page_title: Check - Agent - HTTP API
sidebar_current: api-agent-check
description: |-
The /agent/check endpoints interact with checks on the local agent in Consul.
---
# Check - Agent HTTP API
The `/agent/check` endpoints interact with checks on the local agent in Consul.
These should not be confused with checks in the catalog.
## List Checks
This endpoint returns all checks that are registered with the local agent. These
checks were either provided through configuration files or added dynamically
using the HTTP API.
It is important to note that the checks known by the agent may be different from
those reported by the catalog. This is usually due to changes being made while
there is no leader elected. The agent performs active
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations
everything will be in sync within a few seconds.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/agent/checks` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------------------ |
| `NO` | `none` | `node:read,service:read` |
### Sample Request
```text
$ curl \
https://consul.rocks/v1/agent/checks
```
### Sample Response
```json
{
"service:redis": {
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
}
}
```
## Register Check
This endpoint adds a new check to the local agent. Checks may be of script,
HTTP, TCP, or TTL type. The agent is responsible for managing the status of the
check and keeping the Catalog in sync.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/agent/check/register` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------------------- |
| `NO` | `none` | `node:write,service:write` |
### Parameters
- `Name` `(string: <required>)` - Specifies the name of the check.
- `ID` `(string: "")` - Specifies a unique ID for this check in the cluster.
This defaults to the `"Name"` parameter, but it may be necessary to provide an
ID for uniqueness.
- `Interval` `(string: "")` - Specifies the frequency at which to run this
check. This is required for HTTP and TCP checks.
- `Notes` `(string: "")` - Specifies arbitrary information for humans. This is
not used by Consul internally.
- `DeregisterCriticalServiceAfter` `(string: "")` - Specifies that checks
associated with a service should deregister after this time. This is specified
as a time duration with suffix like "10m". If a check is in the critical state
for more than this configured value, then its associated service (and all of
its associated checks) will automatically be deregistered. The minimum timeout
is 1 minute, and the process that reaps critical services runs every 30
seconds, so it may take slightly longer than the configured timeout to trigger
the deregistration. This should generally be configured with a timeout that's
much, much longer than any expected recoverable outage for the given service.
- `Script` `(string: "")` - Specifies a script or path to a script to run on
`Interval` to update the status of the check. If specifying a path, this path
must exist on disk and be readable by the Consul agent.
- `DockerContainerID` `(string: "")` - Specifies that the check is a Docker
check, and Consul will evaluate the script every `Interval` in the given
container using the specified `Shell`. Note that `Shell` is currently only
supported for Docker checks.
- `HTTP` `(string: "")` - Specifies an `HTTP` check to perform a `GET` request
against the value of `HTTP` (expected to be a URL) every `Interval`. If the
response is any `2xx` code, the check is `passing`. If the response is `429
Too Many Requests`, the check is `warning`. Otherwise, the check is
`critical`. HTTP checks also support SSL. By default, a valid SSL certificate
is expected. Certificate verification can be controlled using the
`TLSSkipVerify`.
- `TLSSkipVerify` `(bool: false)` - Specifies if the certificate for an HTTPS
check should not be verified.
- `TCP` `(string: "")` - Specifies a `TCP` to connect against the value of `TCP`
(expected to be an IP or hostname plus port combination) every `Interval`. If
the connection attempt is successful, the check is `passing`. If the
connection attempt is unsuccessful, the check is `critical`. In the case of a
hostname that resolves to both IPv4 and IPv6 addresses, an attempt will be
made to both addresses, and the first successful connection attempt will
result in a successful check.
- `TTL` `(string: "")` - Specifies this is a TTL check, and the TTL endpoint
must be used periodically to update the state of the check.
- `ServiceID` `(string: "")` - Specifies the ID of a service to associate the
registered check with an existing service provided by the agent.
- `Status` `(string: "")` - Specifies the initial status of the health check.
### Sample Payload
```json
{
"ID": "mem",
"Name": "Memory utilization",
"Notes": "Ensure we don't oversubscribe memory",
"DeregisterCriticalServiceAfter": "90m",
"Script": "/usr/local/bin/check_mem.py",
"DockerContainerID": "f972c95ebf0e",
"Shell": "/bin/bash",
"HTTP": "http://example.com",
"TCP": "example.com:22",
"Interval": "10s",
"TTL": "15s",
"TLSSkipVerify": true
}
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/agent/check/register
```
## Deregister Check
This endpoint remove a check from the local agent. The agent will take care of
deregistering the check from the catalog. If the check with the provided ID does
not exist, no action is taken.
| Method | Path | Produces |
| ------ | ----------------------------------- | -------------------------- |
| `PUT` | `/agent/check/deregister/:check_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------------------- |
| `NO` | `none` | `node:write,service:write` |
### Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to
deregister. This is specified as part of the URL.
### Sample Request
```text
$ curl \
--request PUT \
https://consul.rocks/v1/agent/check/deregister/my-check-id
```
## TTL Check Pass
This endpoint is used with a TTL type check to set the status of the check to
`passing` and to reset the TTL clock.
| Method | Path | Produces |
| ------ | ----------------------------- | -------------------------- |
| `GET` | `/agent/check/pass/:check_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------------------- |
| `NO` | `none` | `node:write,service:write` |
### Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to
use. This is specified as part of the URL.
- `note` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/agent/check/pass/my-check-id
```
## TTL Check Warn
This endpoint is used with a TTL type check to set the status of the check to
`warning` and to reset the TTL clock.
| Method | Path | Produces |
| ------ | ----------------------------- | -------------------------- |
| `GET` | `/agent/check/warn/:check_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------------------- |
| `NO` | `none` | `node:write,service:write` |
### Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to
use. This is specified as part of the URL.
- `note` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/agent/check/warn/my-check-id
```
## TTL Check Fail
This endpoint is used with a TTL type check to set the status of the check to
`critical` and to reset the TTL clock.
| Method | Path | Produces |
| ------ | ----------------------------- | -------------------------- |
| `GET` | `/agent/check/fail/:check_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------------------- |
| `NO` | `none` | `node:write,service:write` |
### Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to
use. This is specified as part of the URL.
- `note` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/agent/check/fail/my-check-id
```
## TTL Check Update
This endpoint is used with a TTL type check to set the status of the check and
to reset the TTL clock.
| Method | Path | Produces |
| ------ | ------------------------------- | -------------------------- |
| `PUT` | `/agent/check/update/:check_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------------------- |
| `NO` | `none` | `node:write,service:write` |
### Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to
use. This is specified as part of the URL.
- `Status` `(string: "")` - Specifies the status of the check. Valid values are
`"passing"`, `"warning"`, and `"critical"`.
- `Output` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field.
### Sample Payload
```json
{
"Status": "passing",
"Output": "curl reported a failure:\n\n..."
}
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/agent/check/update/my-check-id
```

232
website/source/api/agent/service.html.md Normal file
View File

@ -0,0 +1,232 @@
---
layout: api
page_title: Service - Agent - HTTP API
sidebar_current: api-agent-service
description: |-
The /agent/service endpoints interact with services on the local agent in
Consul.
---
# Service - Agent HTTP API
The `/agent/service` endpoints interact with checks on the local agent in
Consul. These should not be confused with services in the catalog.
## List Services
This endpoint returns all the services that are registered with
the local agent. These services were either provided through configuration files
or added dynamically using the HTTP API.
It is important to note that the services known by the agent may be different
from those reported by the catalog. This is usually due to changes being made
while there is no leader elected. The agent performs active
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations
everything will be in sync within a few seconds.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/agent/services` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------- |
| `NO` | `none` | `service:read` |
### Sample Request
```text
$ curl \
https://consul.rocks/v1/agent/services
```
### Sample Response
```json
{
"redis": {
"ID": "redis",
"Service": "redis",
"Tags": null,
"Address": "",
"Port": 8000
}
}
```
## Register Service
This endpoint adds a new service, with an optional health check, to the local
agent.
The agent is responsible for managing the status of its local services, and for
sending updates about its local services to the servers to keep the global
catalog in sync.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/agent/service/register` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `service:write` |
### Parameters
- `Name` `(string: <required>)` - Specifies the logical name of the service.
Many service instances may share the same logical service name.
- `ID` `(string: "")` - Specifies a unique ID for this service. This must be
unique per _agent_. This defaults to the `Name` parameter if not provided.
- `Tags` `(array<string>: nil)` - Specifies a list of tags to assign to the
service. These tags can be used for later filtering and are exposed via the
APIs.
- `Address` `(string: "")` - Specifies the address of the service. If not
provided, the agent's address is used as the address for the service during
DNS queries.
- `Check` `(Check: nil)` - Specifies a check. Please see the
[check documentation](/api/agent/check.html) for more information about the
accepted fields.
- `EnableTagOverride` `(bool: false)` - Specifies to disable the anti-entropy
feature for this service's tags. If `EnableTagOverride` is set to `true` then
external agents can update this service in the [catalog](/api/catalog.html)
and modify the tags. Subsequent local sync operations by this agent will
ignore the updated tags. For instance, if an external agent modified both the
tags and the port for this service and `EnableTagOverride` was set to `true`
then after the next sync cycle the service's port would revert to the original
value but the tags would maintain the updated value. As a counter example, if
an external agent modified both the tags and port for this service and
`EnableTagOverride` was set to `false` then after the next sync cycle the
service's port _and_ the tags would revert to the original value and all
modifications would be lost.
It is important to note that this applies only to the locally registered
service. If you have multiple nodes all registering the same service their
`EnableTagOverride` configuration and all other service configuration items
are independent of one another. Updating the tags for the service registered
on one node is independent of the same service (by name) registered on
another node. If `EnableTagOverride` is not specified the default value is
`false`. See [anti-entropy syncs](/docs/internals/anti-entropy.html) for
more info.
### Sample Payload
```json
{
"ID": "redis1",
"Name": "redis",
"Tags": [
"primary",
"v1"
],
"Address": "127.0.0.1",
"Port": 8000,
"EnableTagOverride": false,
"Check": {
"DeregisterCriticalServiceAfter": "90m",
"Script": "/usr/local/bin/check_redis.py",
"HTTP": "http://localhost:5000/health",
"Interval": "10s",
"TTL": "15s"
}
}
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/agent/service/register
```
## Deregister Service
This endpoint removes a service from the local agent. If the service does not
exist, no action is taken.
The agent will take care of deregistering the service with the catalog. If there
is an associated check, that is also deregistered.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/agent/service/deregister/:service_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `service:write` |
### Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to
deregister. This is specified as part of the URL.
### Sample Request
```text
$ curl \
--request PUT \
https://consul.rocks/v1/agent/service/deregister/my-service-id
```
## Enable Maintenance Mode
This endpoint places a given service into "maintenance mode". During maintenance
mode, the service 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/service/maintenance/:service_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `service:write` |
### Parameters
- `service_id` `(string: <required>)` - Specifies the ID of the service to put
in maintenance mode. This is specified as part of the URL.
- `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 \
https://consul.rocks/v1/agent/service/maintenance/my-service-id?enable=true&reason=For+the+docs
```

523
website/source/api/catalog.html.md Normal file
View File

@ -0,0 +1,523 @@
---
layout: api
page_title: Catalog - HTTP API
sidebar_current: api-catalog
description: |-
The /catalog endpoints register and deregister nodes, services, and checks in
Consul.
---
# Catalog HTTP API
The `/catalog` endpoints register and deregister nodes, services, and checks in
Consul. The catalog should not be confused with the agent, since some of the
API methods look similar.
## Register Entity
This endpoint is a low-level mechanism for registering or updating
entries in the catalog. It is usually preferable to instead use the
[agent endpoints](/api/agent.html) for registration as they are simpler and
perform [anti-entropy](/docs/internals/anti-entropy.html).
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/catalog/register` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------------------- |
| `NO` | `none` | `node:write,service:write` |
### Parameters
- `ID` `(string: "")` - An optional UUID to assign to the service. If not
provided, one is generated. This must be a 36-character UUID.
- `Node` `(string: <required>)` - Specifies the node ID to register.
- `Address` `(string: <required>)` - Specifies the address to register.
- `Datacenter` `(string: "")` - Specifies the datacenter, which defaults to the
agent's datacenter if not provided.
- `TaggedAddresses` `(map<string|string>: nil)` - Specifies the tagged
addresses.
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
pairs for filtering purposes.
- `Service` `(Service: nil)` - Specifies to register a service. If `ID` is not
provided, it will be defaulted to the value of the `Service.Service` property.
Only one service with a given `ID` may be present per node. The service
`Tags`, `Address`, and `Port` fields are all optional.
- `Check` `(Check: nil)` - Specifies to register a check. The register API
manipulates the health check entry in the Catalog, but it does not setup the
script, TTL, or HTTP check to monitor the node's health. To truly enable a new
health check, the check must either be provided in agent configuration or set
via the [agent endpoint](agent.html).
The `CheckID` can be omitted and will default to the value of `Name`. As
with `Service.ID`, the `CheckID` must be unique on this node. `Notes` is an
opaque field that is meant to hold human-readable text. If a `ServiceID` is
provided that matches the `ID` of a service on that node, the check is
treated as a service level health check, instead of a node level health
check. The `Status` must be one of `passing`, `warning`, or `critical`.
Multiple checks can be provided by replacing `Check` with `Checks` and
sending an array of `Check` objects.
It is important to note that `Check` does not have to be provided with `Service`
and vice versa. A catalog entry can have either, neither, or both.
### Sample Payload
```json
{
"Datacenter": "dc1",
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Address": "192.168.10.10",
"TaggedAddresses": {
"lan": "192.168.10.10",
"wan": "10.0.10.10"
},
"NodeMeta": {
"somekey": "somevalue"
},
"Service": {
"ID": "redis1",
"Service": "redis",
"Tags": [
"primary",
"v1"
],
"Address": "127.0.0.1",
"Port": 8000
},
"Check": {
"Node": "foobar",
"CheckID": "service:redis1",
"Name": "Redis health check",
"Notes": "Script based health check",
"Status": "passing",
"ServiceID": "redis1"
}
}
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/catalog/register
```
## Deregister Entity
This endpoint is a low-level mechanism for directly removing
entries from the Catalog. It is usually preferable to instead use the
[agent endpoints](/api/agent.html) for deregistration as they are simpler and
perform [anti-entropy](/docs/internals/anti-entropy.html).
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/catalog/deregister` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------------------- |
| `NO` | `none` | `node:write,service:write` |
### Parameters
The behavior of the endpoint depends on what keys are provided.
- `Node` `(string: <required>)` - Specifies the ID of the node. If no other
values are provided, this node, all its services, and all its checks are
removed.
- `Datacenter` `(string: "")` - Specifies the datacenter, which defaults to the
agent's datacenter if not provided.
- `CheckID` `(string: "")` - Specifies the ID of the check to remove.
- `ServiceID` `(string: "")` - Specifies the ID of the service to remove. The
service and all associated checks will be removed.
### Sample Payloads
```json
{
"Datacenter": "dc1",
"Node": "foobar"
}
```
```json
{
"Datacenter": "dc1",
"Node": "foobar",
"CheckID": "service:redis1"
}
```
```json
{
"Datacenter": "dc1",
"Node": "foobar",
"ServiceID": "redis1"
}
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/catalog/deregister
```
## List Datacenters
This endpoint returns the list of all known datacenters. The datacenters will be
sorted in ascending order based on the estimated median round trip time from the
server to the servers in that datacenter.
This endpoint does not require a cluster leader and will succeed even during an
availability outage. Therefore, it can be used as a simple check to see if any
Consul servers are routable.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/catalog/datacenters` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `none` |
### Sample Request
```text
$ curl \
https://consul.rocks/v1/catalog/datacenters
```
### Sample Respons
```json
["dc1", "dc2"]
```
## List Nodes
This endpoint and returns the nodes registered in a given datacenter.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/catalog/nodes` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `all` | `node:read` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `near` `(string: "")` - Specifies a node name to sort the node list in
ascending order based on the estimated round trip time from that node. Passing
`?near=_agent` will use the agent's node for the sort. This is specified as
part of the URL as a query parameter.
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
of the form `key:value`. This parameter can be specified multiple times, and
will filter the results to nodes with the specified key/value pairs. This is
specified as part of the URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/catalog/nodes
```
### Sample Response
```json
[
{
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "baz",
"Address": "10.1.10.11",
"TaggedAddresses": {
"lan": "10.1.10.11",
"wan": "10.1.10.11"
},
"Meta": {
"instance_type": "t2.medium"
}
},
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"Node": "foobar",
"Address": "10.1.10.12",
"TaggedAddresses": {
"lan": "10.1.10.11",
"wan": "10.1.10.12"
},
"Meta": {
"instance_type": "t2.large"
}
}
]
```
## List Services
This endpoint returns the services registered in a given datacenter.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/catalog/services` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------- |
| `TEST` | `all` | `service:read` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
of the form `key:value`. This parameter can be specified multiple times, and
will filter the results to nodes with the specified key/value pairs. This is
specified as part of the URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/catalog/services
```
### Sample Response
```json
{
"consul": [],
"redis": [],
"postgresql": [
"primary",
"secondary"
]
}
```
The keys are the service names, and the array values provide all known tags for
a given service.
## List Nodes for Service
This endpoint returns the nodes providing a service in a given datacenter.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/catalog/service/:service` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------------------ |
| `YES` | `all` | `node:read,service:read` |
### Parameters
- `service` `(string: <required>)` - Specifies the name of the service for which
to list nodes. This is specified as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `tag` `(string: "")` - Specifies tags to filter on.
- `near` `(string: "")` - Specifies a node name to sort the node list in
ascending order based on the estimated round trip time from that node. Passing
`?near=_agent` will use the agent's node for the sort. This is specified as
part of the URL as a query parameter.
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
of the form `key:value`. This parameter can be specified multiple times, and
will filter the results to nodes with the specified key/value pairs. This is
specified as part of the URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/catalog/service/my-service
```
### Sample Response
```json
[
{
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Address": "192.168.10.10",
"TaggedAddresses": {
"lan": "192.168.10.10",
"wan": "10.0.10.10"
},
"Meta": {
"instance_type": "t2.medium"
},
"CreateIndex": 51,
"ModifyIndex": 51,
"ServiceAddress": "172.17.0.3",
"ServiceEnableTagOverride": false,
"ServiceID": "32a2a47f7992:nodea:5000",
"ServiceName": "foobar",
"ServicePort": 5000,
"ServiceTags": [
"tacos"
]
}
]
```
- `Address` is the IP address of the Consul node on which the service is
registered.
- `TaggedAddresses` is the list of explicit LAN and WAN IP addresses for the
agent
- `Meta` is a list of user-defined metadata key/value pairs for the node
- `CreateIndex` is an internal index value representing when the service was
created
- `ModifyIndex` is the last index that modified the service
- `Node` is the name of the Consul node on which the service is registered
- `ServiceAddress` is the IP address of the service host — if empty, node
address should be used
- `ServiceEnableTagOverride` indicates whether service tags can be overridden on
this service
- `ServiceID` is a unique service instance identifier
- `ServiceName` is the name of the service
- `ServicePort` is the port number of the service
- `ServiceTags` is a list of tags for the service
## List Services for Node
This endpoint returns the node's registered services.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/catalog/node/:node` | `application/json` |
The table below shows this endpoint's support for blocking queries and
consistency modes.
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------------------ |
| `YES` | `all` | `node:read,service:read` |
### Parameters
- `node` `(string: <required>)` - Specifies the name of the node for which
to list services. This is specified as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/catalog/node/my-node
```
### Sample Response
```json
{
"Node": {
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Address": "10.1.10.12",
"TaggedAddresses": {
"lan": "10.1.10.12",
"wan": "10.1.10.12"
},
"Meta": {
"instance_type": "t2.medium"
}
},
"Services": {
"consul": {
"ID": "consul",
"Service": "consul",
"Tags": null,
"Port": 8300
},
"redis": {
"ID": "redis",
"Service": "redis",
"Tags": [
"v1"
],
"Port": 8000
}
}
}
```

119
website/source/api/coordinate.html.md Normal file
View File

@ -0,0 +1,119 @@
---
layout: api
page_title: Coordinate - HTTP API
sidebar_current: api-coordinate
description: |-
The /coordinate endpoints query for the network coordinates for nodes in the
local datacenter as well as Consul servers in the local datacenter and remote
datacenters.
---
# Coordinate HTTP Endpoint
The `/coordinate` endpoints query for the network coordinates for nodes in the
local datacenter as well as Consul servers in the local datacenter and remote
datacenters.
Please see the [Network Coordinates](/docs/internals/coordinates.html) internals
guide for more information on how these coordinates are computed, and for
details on how to perform calculations with them.
## Read WAN Coordinates
This endpoint returns the WAN network coordinates for all Consul servers,
organized by datacenters. It serves data out of the server's local Serf data, so
its results may vary as requests are handled by different servers in the
cluster.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/coordinate/datacenters` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `none` |
### Sample Request
```text
$ curl \
https://consul.rocks/v1/coordinate/datacenters
```
### Sample Response
```json
[
{
"Datacenter": "dc1",
"AreaID": "WAN",
"Coordinates": [
{
"Node": "agent-one",
"Coord": {
"Adjustment": 0,
"Error": 1.5,
"Height": 0,
"Vec": [0, 0, 0, 0, 0, 0, 0, 0]
}
}
]
}
]
```
In **Consul Enterprise**, this will include coordinates for user-added network
areas as well, as indicated by the `AreaID`. Coordinates are only compatible
within the same area.
## Read LAN Coordinates
This endpoint returns the LAN network coordinates for all nodes in a given
datacenter.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/coordinate/nodes` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `all` | `node:read` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/coordinate/nodes
```
### Sample Response
```json
[
{
"Node": "agent-one",
"Coord": {
"Adjustment": 0,
"Error": 1.5,
"Height": 0,
"Vec": [0, 0, 0, 0, 0, 0, 0, 0]
}
}
]
```

156
website/source/api/event.html.md Normal file
View File

@ -0,0 +1,156 @@
---
layout: api
page_title: Events - HTTP API
sidebar_current: api-event
description: |-
The /event endpoints fire new events and to query the available events in
Consul.
---
# Event HTTP Endpoint
The `/event` endpoints fire new events and to query the available events in
Consul.
## Fire Event
This endpoint triggers a new user event.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/event/fire/:name` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------- |
| `NO` | `none` | `event:write` |
### Parameters
- `name` `(string: <required>)` - Specifies the name of the event to fire. This
is specified as part of the URL. This name must not start with an underscore,
since those are reserved for Consul internally.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `node` `(string: "")` - Specifies a regular expression to filter by node name.
This is specified as part of the URL as a query parameter.
- `service` `(string: "")` - Specifies a regular expression to filter by service
name. This is specified as part of the URL as a query parameter.
- `tag` `(string: "")` - Specifies a regular expression to filter by tag. This
is specified as part of the URL as a query parameter.
### Sample Payload
The body contents are opaque to Consul and become the "payload" that is passed
onto the receiver of the event.
```text
Lorem ipsum dolor sit amet, consectetur adipisicing elit...
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload \
https://consul.rocks/v1/event/fire/my-event
```
### Sample Response
```json
{
"ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c",
"Name": "deploy",
"Payload": null,
"NodeFilter": "",
"ServiceFilter": "",
"TagFilter": "",
"Version": 1,
"LTime": 0
}
```
- `ID` is a unique identifier the newly fired event
## List Events
This endpoint returns the most recent events known by the agent. As a
consequence of how the [event command](/docs/commands/event.html) works, each
agent may have a different view of the events. Events are broadcast using the
[gossip protocol](/docs/internals/gossip.html), so they have no global ordering
nor do they make a promise of delivery.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/event/list` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `none` | `event:read` |
### Parameters
- `name` `(string: <required>)` - Specifies the name of the event to filter.
This is specified as part of the URL as a query parameter.
- `node` `(string: "")` - Specifies a regular expression to filter by node name.
This is specified as part of the URL as a query parameter.
- `service` `(string: "")` - Specifies a regular expression to filter by service
name. This is specified as part of the URL as a query parameter.
- `tag` `(string: "")` - Specifies a regular expression to filter by tag. This
is specified as part of the URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/event/list
```
### Sample Response
```json
[
{
"ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c",
"Name": "deploy",
"Payload": "MTYwOTAzMA==",
"NodeFilter": "",
"ServiceFilter": "",
"TagFilter": "",
"Version": 1,
"LTime": 19
}
]
```
### Caveat
The semantics of this endpoint's blocking queries are slightly different. Most
blocking queries provide a monotonic index and block until a newer index is
available. This can be supported as a consequence of the total ordering of the
[consensus protocol](/docs/internals/consensus.html). With gossip, there is no
ordering, and instead `X-Consul-Index` maps to the newest event that matches the
query.
In practice, this means the index is only useful when used against a single
agent and has no meaning globally. Because Consul defines the index as being
opaque, clients should not be expecting a natural ordering either.

312
website/source/api/health.html.markdown Normal file
View File

@ -0,0 +1,312 @@
---
layout: api
page_title: Health - HTTP API
sidebar_current: api-health
description: |-
The /health endpoints query health-related information for services and checks
in Consul.
---
# Health HTTP Endpoint
The `/health` endpoints query health-related information. They are provided
separately from the `/catalog` endpoints since users may prefer not to use the
optional health checking mechanisms. Additionally, some of the query results
from the health endpoints are filtered while the catalog endpoints provide the
raw entries.
## List Checks for Node
This endpoint returns the checks specific to the node provided on the path.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/health/node/:node` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------------------ |
| `YES` | `all` | `node:read,service:read` |
### Parameters
- `node` `(string: <required>)` - Specifies the name or ID of the node to query.
This is specified as part of the URL
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/health/node/my-node
```
### Sample Response
```json
[
{
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"CheckID": "serfHealth",
"Name": "Serf Health Status",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "",
"ServiceName": ""
},
{
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
}
]
```
## List Checks for Service
This endpoint returns the checks associated with the service provided on the
path.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/health/checks/:service` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------------------ |
| `YES` | `all` | `node:read,service:read` |
### Parameters
- `service` `(string: <required>)` - Specifies the service to list checks for.
This is provided as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `near` `(string: "")` - Specifies a node name to sort the node list in
ascending order based on the estimated round trip time from that node. Passing
`?near=_agent` will use the agent's node for the sort. This is specified as
part of the URL as a query parameter.
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
of the form `key:value`. This parameter can be specified multiple times, and
will filter the results to nodes with the specified key/value pairs. This is
specified as part of the URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/health/checks/my-service
```
### Sample Response
```json
[
{
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
}
]
```
## List Nodes for Service
This endpoint returns the nodes providing the service indicated on the path.
Users can also build in support for dynamic load balancing and other features by
incorporating the use of health checks.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/health/service/:service` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------------------ |
| `YES` | `all` | `node:read,service:read` |
### Parameters
- `service` `(string: <required>)` - Specifies the service to list services for.
This is provided as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `near` `(string: "")` - Specifies a node name to sort the node list in
ascending order based on the estimated round trip time from that node. Passing
`?near=_agent` will use the agent's node for the sort. This is specified as
part of the URL as a query parameter.
- `tag` `(string: "")` - Specifies the list of tags to filter the list. This is
specifies as part of the URL as a query parameter.
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
of the form `key:value`. This parameter can be specified multiple times, and
will filter the results to nodes with the specified key/value pairs. This is
specified as part of the URL as a query parameter.
- `passing` `(bool: false)` - Specifies that the server should return only nodes
with all checks in the `passing` state. This can be used to avoid additional
filtering on the client side.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/health/service/my-service
```
### Sample Response
```json
[
{
"Node": {
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Address": "10.1.10.12",
"TaggedAddresses": {
"lan": "10.1.10.12",
"wan": "10.1.10.12"
},
"Meta": {
"instance_type": "t2.medium"
}
},
"Service": {
"ID": "redis",
"Service": "redis",
"Tags": null,
"Address": "10.1.10.12",
"Port": 8000
},
"Checks": [
{
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
},
{
"Node": "foobar",
"CheckID": "serfHealth",
"Name": "Serf Health Status",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "",
"ServiceName": ""
}
]
}
]
```
## List Checks in State
This endpoint returns the checks in the state provided on the path.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/health/state/:state` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------------------ |
| `YES` | `all` | `node:read,service:read` |
### Parameters
- `state` `(string: <required>)` - Specifies the state to query. Spported states
are `any`, `passing`, `warning`, or `critical`. The `any` state is a wildcard
that can be used to return all checks.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `near` `(string: "")` - Specifies a node name to sort the node list in
ascending order based on the estimated round trip time from that node. Passing
`?near=_agent` will use the agent's node for the sort. This is specified as
part of the URL as a query parameter.
- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
of the form `key:value`. This parameter can be specified multiple times, and
will filter the results to nodes with the specified key/value pairs. This is
specified as part of the URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/health/state/passing
```
### Sample Response
```json
[
{
"Node": "foobar",
"CheckID": "serfHealth",
"Name": "Serf Health Status",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "",
"ServiceName": ""
},
{
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
}
]
```

159
website/source/api/index.html.md Normal file
View File

@ -0,0 +1,159 @@
---
layout: api
page_title: HTTP API
sidebar_current: api-overview
description: |-
Consul exposes a RESTful HTTP API to control almost every aspect of the
Consul agent.
---
# HTTP API
The main interface to Consul is a RESTful HTTP API. The API can basic perform
CRUD operations on nodes, services, checks, configuration, and more.
## Version Prefix
All API routes are prefixed with `/v1/`.
This documentation is only for the v1 API.
~> **Backwards compatibility:** At the current version, Consul does not yet
promise backwards compatibility even with the v1 prefix. We'll remove this
warning when this policy changes. We expect to reach API stability by Consul
1.0.
## ACLs
Several endpoints in Consul use or require ACL tokens to operate. An agent
can be configured to use a default token in requests using the `acl_token`
configuration option. However, the token can also be specified per-request
by using the `X-Consul-Token` request header or the `token` querystring
parameter. The request header takes precedence over the default token, and
the querystring parameter takes precedence over everything.
## Authentication
When authentication is enabled, a Consul token should be provided to API
requests using the `X-Consul-Token` header. This reduces the probability of the
token accidentally getting logged or exposed. When using authentication,
clients should communicate via TLS.
Here is an example using `curl`:
```text
$ curl \
--header "X-Consul-Token: abcd1234" \
https://consul.rocks/v1/agent/members
```
Previously this was provided via a `?token=` query parameter. This functionality
exists on many endpoints for backwards compatibility, but its use is **highly
discouraged**, since it can show up in access logs as part of the URL.
## Blocking Queries
Many endpoints in Consul support a feature known as "blocking queries". A
blocking query is used to wait for a potential change using long polling. Not
all endpoints support blocking, but each endpoint uniquely documents its support
for blocking queries in the documentation.
Endpoints that support blocking queries return an HTTP header named
`X-Consul-Index`. This is a unique identifier representing the current state of
the requested resource.
On subsequent requests for this resource, the client can set the `index` query
string parameter to the value of `X-Consul-Index`, indicating that the client
wishes to wait for any changes subsequent to that index.
When this is provided, the HTTP request will "hang" until a change in the system
occurs, or the maximum timeout is reached. A critical note is that the return of
a blocking request is **no guarantee** of a change. It is possible that the
timeout was reached or that there was an idempotent write that does not affect
the result of the query.
In addition to `index`, endpoints that support blocking will also honor a `wait`
parameter specifying a maximum duration for the blocking request. This is
limited to 10 minutes. If not set, the wait time defaults to 5 minutes. This
value can be specified in the form of "10s" or "5m" (i.e., 10 seconds or 5
minutes, respectively). A small random amount of additional wait time is added
to the supplied maximum `wait` time to spread out the wake up time of any
concurrent requests. This adds up to `wait / 16` additional time to the maximum
duration.
## Consistency Modes
Most of the read query endpoints support multiple levels of consistency. Since
no policy will suit all clients' needs, these consistency modes allow the user
to have the ultimate say in how to balance the trade-offs inherent in a
distributed system.
The three read modes are:
- `default` - If not specified, the default is strongly consistent in almost all
cases. However, there is a small window in which a new leader may be elected
during which the old leader may service stale values. The trade-off is fast
reads but potentially stale values. The condition resulting in stale reads is
hard to trigger, and most clients should not need to worry about this case.
Also, note that this race condition only applies to reads, not writes.
- `consistent` - This mode is strongly consistent without caveats. It requires
that a leader verify with a quorum of peers that it is still leader. This
introduces an additional round-trip to all server nodes. The trade-off is
increased latency due to an extra round trip. Most clients should not use this
unless they cannot tolerate a stale read.
- `stale` - This mode allows any server to service the read regardless of
whether it is the leader. This means reads can be arbitrarily stale; however,
results are generally consistent to within 50 milliseconds of the leader. The
trade-off is very fast and scalable reads with a higher likelihood of stale
values. Since this mode allows reads without a leader, a cluster that is
unavailable will still be able to respond to queries.
To switch these modes, either the `stale` or `consistent` query parameters
should be provided on requests. It is an error to provide both.
To support bounding the acceptable staleness of data, responses provide the
`X-Consul-LastContact` header containing the time in milliseconds that a server
was last contacted by the leader node. The `X-Consul-KnownLeader` header also
indicates if there is a known leader. These can be used by clients to gauge the
staleness of a result and take appropriate action.
## Formatted JSON Output
By default, the output of all HTTP API requests is minimized JSON. If the client
passes `pretty` on the query string, formatted JSON will be returned.
## HTTP Methods
Consul's API aims to be RESTful, although there are some exceptions. The API
responds to the standard HTTP verbs GET, PUT, and DELETE. Each API method will
clearly document the verb(s) it responds to and the generated response. The same
path with different verbs may trigger different behavior. For example:
```text
PUT /v1/kv/foo
GET /v1/kv/foo
```
Even though these share a path, the `PUT` operation creates a new key whereas
the `GET` operation reads an existing key.
Here is the same example using `curl`:
```shell
$ curl \
--request PUT \
--data 'hello consul' \
https://consul.rocks/v1/kv/foo
```
## Translated Addresses
Consul 0.7 added the ability to translate addresses in HTTP response based on
the configuration setting for
[`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs). In order
to allow clients to know if address translation is in effect, the
`X-Consul-Translate-Addresses` header will be added if translation is enabled,
and will have a value of `true`. If translation is not enabled then this header
will not be present.

254
website/source/api/kv.html.md Normal file
View File

@ -0,0 +1,254 @@
---
layout: api
page_title: KV Store - HTTP API
sidebar_current: api-kv-store
description: |-
The /kv endpoints access Consul's simple key/value store, useful for storing
service configuration or other metadata.
---
# KV Store Endpoints
The `/kv` endpoints access Consul's simple key/value store, useful for storing
service configuration or other metadata.
It is important to note that each datacenter has its own KV store, and there is
no built-in replication between datacenters. If you are interested in
replication between datacenters, please view the
[Consul Replicate](https://github.com/hashicorp/consul-replicate) project.
~> Values in the KV store cannot be larger than 512kb.
For multi-key updates, please consider using [transaction](/api/txn.html).
## Read Key
This endpoint returns the specified key. If no key exists at the given path, a
404 is returned instead of a 200 response.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/kv/:key` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `all` | `key:read` |
### Parameters
- `key` `(string: "")` - Specifies the path of the key to read.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `recurse` `(bool: false)` - Specifies if the lookup should be recursive and
`key` treated as a prefix instead of a literal match. This is specified as
part of the URL as a query parameter.
- `raw` `(bool: false)` - Specifies the response is just the raw value of the
key, without any encoding or metadata. This is specified as part of the URL as
a query parameter.
- `keys` `(bool: false)` - Specifies to return only keys (no values or
metadata). Specifying this implies `recurse`. This is specified as part of the
URL as a query parameter.
- `separator` `(string: '/')` - Specifies the character to use as a separator
for recursive lookups. This is specified as part of the URL as a query
parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/kv/my-key
```
### Sample Response
#### Metadata Response
```json
[
{
"CreateIndex": 100,
"ModifyIndex": 200,
"LockIndex": 200,
"Key": "zip",
"Flags": 0,
"Value": "dGVzdA==",
"Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
]
```
- `CreateIndex` is the internal index value that represents when the entry was
created.
- `ModifyIndex` is the last index that modified this key. This index corresponds
to the `X-Consul-Index` header value that is returned in responses, and it can
be used to establish blocking queries by setting the `?index` query parameter.
You can even perform blocking queries against entire subtrees of the KV store:
if `?recurse` is provided, the returned `X-Consul-Index` corresponds to the
latest `ModifyIndex` within the prefix, and a blocking query using that
`?index` will wait until any key within that prefix is updated.
- `LockIndex` is the number of times this key has successfully been acquired in
a lock. If the lock is held, the `Session` key provides the session that owns
the lock.
- `Key` is simply the full path of the entry.
- `Flags` is an opaque unsigned integer that can be attached to each entry.
Clients can choose to use this however makes sense for their application.
- `Value` is a base64-encoded blob of data.
#### Keys Response
When using the `?keys` query parameter, the response structure changes to an
array of strings instead of an array of JSON objects. Listing `/web/` with a `/`
separator may return:
```json
[
"/web/bar",
"/web/foo",
"/web/subdir/"
]
```
Using the key listing method may be suitable when you do not need the values or
flags or want to implement a key-space explorer.
#### Raw Response
When using the `?raw` endpoint, the response is not `application/json`, but
rather the content type of the uploaded content.
```
)k<><6B><EFBFBD><EFBFBD><EFBFBD><EFBFBD>z^<5E>-<2D>ɑj<C991>q<EFBFBD><71><EFBFBD><EFBFBD>#u<>-R<>r<EFBFBD><72>T<EFBFBD>D<EFBFBD><44>٬<EFBFBD>Y<EFBFBD><59>l,<2C>ιK<CEB9><4B>Fm<46><6D>}<7D>#e<><65>
```
(Yes, that is intentionally a bunch of gibberish characters to showcase the
response)
## Create/Update Key
This endpoint
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/kv/:key` | `application/json` |
Even though the return type is `application/json`, the value is either `true` or
`false`, indicating whether the create/update succeeded.
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `key:write` |
### Parameters
- `key` `(string: "")` - Specifies the path of the key to read.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `flags` `(int: 0)` - Specifies an unsigned value between `0` and `(2^64)-1`.
Clients can choose to use this however makes sense for their application. This
is specified as part of the URL as a query parameter.
- `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. This is very
useful as a building block for more complex synchronization primitives. If the
index is 0, Consul will only put the key if it does not already exist. If the
index is non-zero, the key is only set if the index matches the `ModifyIndex`
of that key.
- `acquire` `(string: "")` - Specifies to use a lock acquisition operation. This
is useful as it allows leader election to be built on top of Consul. If the
lock is not held and the session is valid, this increments the `LockIndex` and
sets the `Session` value of the key in addition to updating the key contents.
A key does not need to exist to be acquired. If the lock is already held by
the given session, then the `LockIndex` is not incremented but the key
contents are updated. This lets the current lock holder update the key
contents without having to give up the lock and reacquire it.
- `release` `(string: "")` - Specifies to use a lock release operation. This is
useful when paired with `?acquire=` as it allows clients to yield a lock. This
will leave the `LockIndex` unmodified but will clear the associated `Session`
of the key. The key must be held by this session to be unlocked.
### Sample Payload
The payload is arbitrary, and is loaded directly into Consul as supplied.
### Sample Request
```text
$ curl \
--request PUT \
--data @contents \
https://consul.rocks/v1/kv/my-key
```
### Sample Response
```json
true
```
## Delete Key
This endpoint deletes a single key or all keys sharing a prefix.
| Method | Path | Produces |
| -------- | ---------------------------- | -------------------------- |
| `DELETE` | `/kv/:key` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `key:write` |
### Parameters
- `recurse` `(bool: false)` - Specifies to delete all keys which have the
specified prefix. Without this, only a key with an exact match will be
deleted.
- `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. This is very
useful as a building block for more complex synchronization primitives. Unlike
`PUT`, the index must be greater than 0 for Consul to take any action: a 0
index will not delete the key. If the index is non-zero, the key is only
deleted if the index matches the `ModifyIndex` of that key.
### Sample Request
```text
$ curl \
--request DELETE \
https://consul.rocks/v1/kv/my-key
```
### Sample Response
```json
true
```

72
website/source/api/libraries-and-sdks.html.md Normal file
View File

@ -0,0 +1,72 @@
---
layout: api
page_title: Libraries and SDKs - HTTP API
sidebar_current: api-libraries-and-sdks
description: |-
There are many third-party libraries for interacting with Consul's HTTP API.
This page lists the HashiCorp and community-maintained Consul HTTP API client
libraries.
---
# Client Libraries & SDKs
The programming libraries listed on this page can be used to consume the API
more conveniently. Some are officially maintained while others are provided by
the community.
<ul>
<li>
<a href="https://github.com/hashicorp/consul/tree/master/api">api</a> - Official Go client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/gmr/consulate">consulate</a> - Python client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/cablehead/python-consul">python-consul</a> - Python client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/vdloo/consul-kv">consul-kv</a> - Python 3 client for the Consul KV-store
</li>
<li>
<a href="https://github.com/sensiolabs/consul-php-sdk">consul-php-sdk</a> - PHP client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/dcarbone/php-consul-api">php-consul-api</a> - GO-like PHP Client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/tolitius/envoy">envoy</a> - Consul Clojure client with watchers and other goodies
</li>
<li>
<a href="https://github.com/hadielmougy/clj-consul-catalog">clj-consul-catalog</a> - Clojure discovery client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/codacy/scala-consul">scala-consul</a> - Scala client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/OrbitzWorldwide/consul-client">consul-client</a> - Java client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/Ecwid/consul-api">consul-api</a> - Java client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/undeadlabs/discovery">discovery</a> - Erlang/OTP client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/xaviershay/consul-client">consul-client</a> - Ruby client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/WeAreFarmGeek/diplomat">diplomat</a> - Ruby library to query Consul's KV-store and services directory
</li>
<li>
<a href="https://www.npmjs.com/package/consul">node-consul</a> - Node.js client for the Consul HTTP API
</li>
<li>
<a href="https://www.nuget.org/packages/Consul">Consul.NET</a> - C# client for the Consul HTTP API
</li>
<li>
<a href="https://metacpan.org/pod/Consul">Consul</a> - Perl client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/Drawaes/CondenserDotNet">CondenserDotNet</a> - C# an opinionated API for .NET that provides higher level functionality for services using the HTTP API
</li>
</ul>

24
website/source/api/operator.html.md Normal file
View File

@ -0,0 +1,24 @@
---
layout: api
page_title: Operator - HTTP API
sidebar_current: api-operator
description: |-
The /operator endpoints provide cluster-level tools for Consul operators,
such as interacting with the Raft subsystem.
---
# Operator HTTP Endpoint
The `/operator` endpoints provide cluster-level tools for Consul operators,
such as interacting with the Raft subsystem. For a CLI to perform these
operations manually, please see the documentation for the
[`consul operator`](/docs/commands/operator.html) command.
If ACLs are enabled then a token with operator privileges may be required in
order to use this interface. See the [ACL](/docs/internals/acl.html#operator)
internals guide for more information.
See the [Outage Recovery](/docs/guides/outage.html) guide for some examples of
how these capabilities are used.
Please choose a sub-section in the navigation for more information.

364
website/source/api/operator/area.html.md Normal file
View File

@ -0,0 +1,364 @@
---
layout: api
page_title: Network Areas - Operator - HTTP API
sidebar_current: api-operator-area
description: |-
The /operator/area endpoints expose the network tomography information via
Consul's HTTP API.
---
# Network Areas - Operator HTTP API
The `/operator/area` endpoints expose the network tomography information via
Consul's HTTP API.
~> **Enterprise Only!** This API endpoint and functionality only exists in
Consul Enterprise. This is not present in the open source version of Consul.
The network area functionality described here is available only in
[Consul Enterprise](https://www.hashicorp.com/consul.html) version 0.8.0 and
later. Network areas are operator-defined relationships between servers in two
different Consul datacenters.
Unlike Consul's WAN feature, network areas use just the server RPC port for
communication, and relationships can be made between independent pairs of
datacenters, so not all servers need to be fully connected. This allows for
complex topologies among Consul datacenters like hub/spoke and more general
trees.
Please see the [Network Areas Guide](/docs/guides/areas.html) for more details.
## Create Network Area
This endpoint creates a new network area and returns its ID if it is created
successfully.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `POST` | `/operator/area` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ---------------- |
| `NO` | `none` | `operator:write` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
- `PeerDatacenter` `(string: <required>)` - Specifes the name of the Consul
datacenter that will be joined the Consul servers in the current datacenter to
form the area. Only one area is allowed for each possible `PeerDatacenter`,
and a datacenter cannot form an area with itself.
- `RetryJoin` `(array<string>: nil)`- Specifies a list of Consul servers to
attempt to join. Servers can be given as `IP`, `IP:port`, `hostname`, or
`hostname:port`. Consul will spawn a background task that tries to
periodically join the servers in this list and will run until a join succeeds.
If this list is not supplied, joining can be done with a call to the
[join endpoint](#area-join) once the network area is created.
### Sample Payload
```json
{
"PeerDatacenter": "dc2",
"RetryJoin": [ "10.1.2.3", "10.1.2.4", "10.1.2.5" ]
}
```
### Sample Request
```text
$ curl \
--request POST \
--data @payload.json \
https://consul.rocks/v1/operator/area
```
### Sample Response
```json
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"
}
```
## List Network Areas
This endpoint lists all network areas.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/operator/area` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `YES` | `all` | `operator:read` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/operator/area
```
### Sample Response
```json
[
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"PeerDatacenter": "dc2",
"RetryJoin": ["10.1.2.3", "10.1.2.4", "10.1.2.5"]
}
]
```
## List Specific Network Area
This endpoint lists a specific network area.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/operator/area/:uuid` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `YES` | `all` | `operator:read` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to list. This
is specified as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/operator/area/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
### Sample Response
```json
[
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"PeerDatacenter": "dc2",
"RetryJoin": ["10.1.2.3", "10.1.2.4", "10.1.2.5"]
}
]
```
## Delete Network Area
This endpoint deletes a specific network area.
| Method | Path | Produces |
| -------- | ---------------------------- | -------------------------- |
| `DELETE` | `/operator/area/:uuid` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ---------------- |
| `NO` | `none` | `operator:write` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to delete. This
is specified as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
### Sample Request
```text
$ curl \
--request DELETE \
https://consul.rocks/v1/operator/area/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
## Join Network Area
This endpoint attempts to join the given Consul servers into a specific network
area.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/operator/area/:uuid/join` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ---------------- |
| `NO` | `none` | `operator:write` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to join. This
is specified as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
### Sample Palyoad
```json
["10.1.2.3", "10.1.2.4", "10.1.2.5"]
```
This can be provided as `IP`, `IP:port`, `hostname`, or `hostname:port`.
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/operator/area/8f246b77-f3e1-ff88-5b48-8ec93abf3e05/join
```
### Sample Response
```json
[
{
"Address": "10.1.2.3",
"Joined": true,
"Error": ""
},
{
"Address": "10.1.2.4",
"Joined": true,
"Error": ""
},
{
"Address": "10.1.2.5",
"Joined": true,
"Error": ""
}
]
```
- `Address` has the address requested to join.
- `Joined` will be `true` if the Consul server at the given address was
successfully joined into the network area. Otherwise, this will be `false` and
`Error` will have a human-readable message about why the join didn't succeed.
## List Network Area Members
This endpoint provides a listing of the Consul servers present in a specific
network area.
| Method | Path | Produces |
| ------ | ------------------------------ | -------------------------- |
| `GET` | `/operator/area/:uuid/members` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `operator:read` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the area to list. This
is specified as part of the URL.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as a URL query
parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/operator/area/8f246b77-f3e1-ff88-5b48-8ec93abf3e05/members
```
### Sample Response
```json
[
{
"ID": "afc5d95c-1eee-4b46-b85b-0efe4c76dd48",
"Name": "node-2.dc1",
"Addr": "127.0.0.2",
"Port": 8300,
"Datacenter": "dc1",
"Role": "server",
"Build": "0.8.0",
"Protocol": 2,
"Status": "alive",
"RTT": 256478
},
]
```
- `ID` is the node ID of the server.
- `Name` is the node name of the server, with its datacenter appended.
- `Addr` is the IP address of the node.
- `Port` is the server RPC port of the node.
- `Datacenter` is the node's Consul datacenter.
- `Role` is always "server" since only Consul servers can participate in network
areas.
- `Build` has the Consul version running on the node.
- `Protocol` is the [protocol version](/docs/upgrading.html#protocol-versions)
being spoken by the node.
- `Status` is the current health status of the node, as determined by the
network area distributed failure detector. This will be "alive", "leaving",
"left", or "failed". A "failed" status means that other servers are not able
to probe this server over its server RPC interface.
- `RTT` is an estimated network round trip time from the server answering the
query to the given server, in nanoseconds. This is computed using [network
coordinates](/docs/internals/coordinates.html).

237
website/source/api/operator/autopilot.html.md Normal file
View File

@ -0,0 +1,237 @@
---
layout: api
page_title: Autopilot - Operator - HTTP API
sidebar_current: api-operator-autopilot
description: |-
The /operator/autopilot endpoints allow for automatic operator-friendly
management of Consul servers including cleanup of dead servers, monitoring
the state of the Raft cluster, and stable server introduction.
---
# Autopilot Operator HTTP API
The `/operator/autopilot` endpoints allow for automatic operator-friendly
management of Consul servers including cleanup of dead servers, monitoring
the state of the Raft cluster, and stable server introduction.
Please see the [Autopilot Guide](/docs/guides/autopilot.html) for more details.
## Read Configuration
This endpoint retrieves its latest Autopilot configuration.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/operator/autopilot/configuration` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `operator:read` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query string.
- `stale` `(bool: false)` - If the cluster does not currently have a leader an
error will be returned. You can use the `?stale` query parameter to read the
Raft configuration from any of the Consul servers.
### Sample Request
```text
$ curl \
https://consul.rocks/operator/autopilot/configuration
```
### Sample Response
```json
{
"CleanupDeadServers": true,
"LastContactThreshold": "200ms",
"MaxTrailingLogs": 250,
"ServerStabilizationTime": "10s",
"RedundancyZoneTag": "",
"DisableUpgradeMigration": false,
"CreateIndex": 4,
"ModifyIndex": 4
}
```
For more information about the Autopilot configuration options, see the
[agent configuration section](/docs/agent/options.html#autopilot).
## Update Configuration
This endpoint updates the Autopilot configuration of the cluster.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/operator/autopilot/configuration` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ---------------- |
| `NO` | `none` | `opreator:write` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query string.
- `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. The update will
only happen if the given index matches the `ModifyIndex` of the configuration
at the time of writing.
- `CleanupDeadServers` `(bool: true)` - Specifies automatic removal of dead
server nodes periodically and whenever a new server is added to the cluster.
- `LastContactThreshold` `(string: "200ms")` - Specifies the maximum amount of
time a server can go without contact from the leader before being considered
unhealthy. Must be a duration value such as `10s`.
- `MaxTrailingLogs` `(int: 250)` specifies the maximum number of log entries
that a server can trail the leader by before being considered unhealthy.
- `ServerStabilizationTime` `(string: "10s")` - Specifies the minimum amount of
time a server must be stable in the 'healthy' state before being added to the
cluster. Only takes effect if all servers are running Raft protocol version 3
or higher. Must be a duration value such as `30s`.
- `RedundancyZoneTag` `(string: "")` controls the node-meta key to use when
Autopilot is separating servers into zones for redundancy. Only one server in
each zone can be a voting member at one time. If left blank, this feature will
be disabled.
- `DisableUpgradeMigration` `(bool: false)` - Disables Autopilot's upgrade
migration strategy in Consul Enterprise of waiting until enough
newer-versioned servers have been added to the cluster before promoting any of
them to voters.
### Sample Payload
```json
{
"CleanupDeadServers": true,
"LastContactThreshold": "200ms",
"MaxTrailingLogs": 250,
"ServerStabilizationTime": "10s",
"RedundancyZoneTag": "",
"DisableUpgradeMigration": false,
"CreateIndex": 4,
"ModifyIndex": 4
}
```
## Read Health
This endpoint queries the health of the autopilot status.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/operator/autopilot/health` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `opreator:read` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query string.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/operator/autopilot/health
```
### Sample response
```json
{
"Healthy": true,
"FailureTolerance": 0,
"Servers": [
{
"ID": "e349749b-3303-3ddf-959c-b5885a0e1f6e",
"Name": "node1",
"Address": "127.0.0.1:8300",
"SerfStatus": "alive",
"Version": "0.7.4",
"Leader": true,
"LastContact": "0s",
"LastTerm": 2,
"LastIndex": 46,
"Healthy": true,
"Voter": true,
"StableSince": "2017-03-06T22:07:51Z"
},
{
"ID": "e36ee410-cc3c-0a0c-c724-63817ab30303",
"Name": "node2",
"Address": "127.0.0.1:8205",
"SerfStatus": "alive",
"Version": "0.7.4",
"Leader": false,
"LastContact": "27.291304ms",
"LastTerm": 2,
"LastIndex": 46,
"Healthy": true,
"Voter": false,
"StableSince": "2017-03-06T22:18:26Z"
}
]
}
```
- `Healthy` is whether all the servers are currently healthy.
- `FailureTolerance` is the number of redundant healthy servers that could be
fail without causing an outage (this would be 2 in a healthy cluster of 5
servers).
- `Servers` holds detailed health information on each server:
- `ID` is the Raft ID of the server.
- `Name` is the node name of the server.
- `Address` is the address of the server.
- `SerfStatus` is the SerfHealth check status for the server.
- `Version` is the Consul version of the server.
- `Leader` is whether this server is currently the leader.
- `LastContact` is the time elapsed since this server's last contact with the leader.
- `LastTerm` is the server's last known Raft leader term.
- `LastIndex` is the index of the server's last committed Raft log entry.
- `Healthy` is whether the server is healthy according to the current Autopilot configuration.
- `Voter` is whether the server is a voting member of the Raft cluster.
- `StableSince` is the time this server has been in its current `Healthy` state.

219
website/source/api/operator/keyring.html.md Normal file
View File

@ -0,0 +1,219 @@
---
layout: api
page_title: Keyring - Operator - HTTP API
sidebar_current: api-operator-keyring
description: |-
The /operator/keyring endpoints allow for management of the gossip encryption
keyring.
---
# Keyring Operator HTTP API
The `/operator/keyring` endpoints allow for management of the gossip encryption
keyring. Please see the [Gossip Protocol Guide](/docs/internals/gossip.html) for
more details on the gossip protocol and its use.
## List Gossip Encryption Keys
This endpoint lists the gossip encryption keys installed on both the WAN and LAN
rings of every known datacenter.
If ACLs are enabled, the client will need to supply an ACL Token with `keyring`
read privileges.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/operator/keyring` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------- |
| `NO` | `none` | `keyring:read` |
### Parameters
- `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
non-zero value will cause nodes to relay their responses through this many
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
This is specified as part of the URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/operator/keyring
```
### Sample Response
```json
[
{
"WAN": true,
"Datacenter": "dc1",
"Keys": {
"0eK8RjnsGC/+I1fJErQsBA==": 1,
"G/3/L4yOw3e5T7NTvuRi9g==": 1,
"z90lFx3sZZLtTOkutXcwYg==": 1
},
"NumNodes": 1
},
{
"WAN": false,
"Datacenter": "dc1",
"Keys": {
"0eK8RjnsGC/+I1fJErQsBA==": 1,
"G/3/L4yOw3e5T7NTvuRi9g==": 1,
"z90lFx3sZZLtTOkutXcwYg==": 1
},
"NumNodes": 1
}
]
```
- `WAN` is true if the block refers to the WAN ring of that datacenter (rather
than LAN).
- `Datacenter` is the datacenter the block refers to.
- `Keys` is a map of each gossip key to the number of nodes it's currently
installed on.
- `NumNodes` is the total number of nodes in the datacenter.
## Add New Gossip Encryption Key
This endpoint installs a new gossip encryption key into the cluster.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `POST` | `/operator/keyring` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `keyring:write` |
### Parameters
- `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
non-zero value will cause nodes to relay their responses through this many
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
This is specified as part of the URL as a query parameter.
- `Key` `(string: <required>)` - Specifies the encryption key to install into
the cluster.
### Sample Payload
```json
{
"Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
}
```
### Sample Request
```text
$ curl \
--request POST \
--data @payload.json \
https://consul.rocks/v1/operator/keyring
```
## Change Primary Gossip Encryption Key
This endpoint changes the primary gossip encryption key. The key must already be
installed before this operation can succeed.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/operator/keyring` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `keyring:write` |
### Parameters
- `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
non-zero value will cause nodes to relay their responses through this many
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
This is specified as part of the URL as a query parameter.
- `Key` `(string: <required>)` - Specifies the encryption key to begin using as
primary into the cluster.
### Sample Payload
```json
{
"Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
}
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/operator/keyring
```
## Delete Gossip Encryption Key
This endpoint removes a gossip encryption key from the cluster. This operation
may only be performed on keys which are not currently the primary key.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/operator/keyring` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `keyring:write` |
### Parameters
- `relay-factor` `(int: 0)` - Specifies the relay factor. Setting this to a
non-zero value will cause nodes to relay their responses through this many
randomly-chosen other nodes in the cluster. The maximum allowed value is `5`.
This is specified as part of the URL as a query parameter.
- `Key` `(string: <required>)` - Specifies the encryption key to delete.
### Sample Payload
```json
{
"Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
}
```
### Sample Request
```text
$ curl \
--request DELETE \
--data @payload.json \
https://consul.rocks/v1/operator/keyring
```

143
website/source/api/operator/raft.html.md Normal file
View File

@ -0,0 +1,143 @@
---
layout: api
page_title: Raft - Operator - HTTP API
sidebar_current: api-operator-raft
description: |-
The /operator/raft endpoints provide tools for management of Raft the
consensus subsystem and cluster quorum.
---
# Raft Operator HTTP API
The `/operator/raft` endpoints provide tools for management of Raft the
consensus subsystem and cluster quorum.
Please see the [Consensus Protocol Guide](/docs/internals/consensus.html) for
more information about Raft consensus protocol and its use.
## Read Configuration
This endpoint reads the current raft configuration.
| Method | Path | Produces |
| ------ | ------------------------------ | -------------------------- |
| `GET` | `/operator/raft/configuration` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `operator:read` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query string.
- `stale` `(bool: false)` - If the cluster does not currently have a leader an
error will be returned. You can use the `?stale` query parameter to read the
Raft configuration from any of the Consul servers.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/operator/raft/configuration
```
### Sample Response
```json
{
"Servers": [
{
"ID": "127.0.0.1:8300",
"Node": "alice",
"Address": "127.0.0.1:8300",
"Leader": true,
"Voter": true
},
{
"ID": "127.0.0.2:8300",
"Node": "bob",
"Address": "127.0.0.2:8300",
"Leader": false,
"Voter": true
},
{
"ID": "127.0.0.3:8300",
"Node": "carol",
"Address": "127.0.0.3:8300",
"Leader": false,
"Voter": true
}
],
"Index": 22
}
```
- `Servers` is has information about the servers in the Raft peer configuration:
- `ID` is the ID of the server. This is the same as the `Address` in Consul
0.7 but may be upgraded to a GUID in a future version of Consul.
- `Node` is the node name of the server, as known to Consul, or "(unknown)" if
the node is stale and not known.
- `Address` is the IP:port for the server.
- `Leader` is either "true" or "false" depending on the server's role in the
Raft configuration.
- `Voter` is "true" or "false", indicating if the server has a vote in the
Raft configuration. Future versions of Consul may add support for non-voting
servers.
- `Index` is the Raft corresponding to this configuration. The latest
configuration may not yet be committed if changes are in flight.
## Delete Raft Peer
This endpoint removes the Consul server with given address from the Raft
configuration.
There are rare cases where a peer may be left behind in the Raft configuration
even though the server is no longer present and known to the cluster. This
endpoint can be used to remove the failed server so that it is no longer affects
the Raft quorum.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
write privileges.
| Method | Path | Produces |
| -------- | ---------------------------- | -------------------------- |
| `DELETE` | `/operator/raft/peer` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ---------------- |
| `NO` | `none` | `operator:write` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query string.
- `id|address` `(string: <required>)` - Specifies the ID or address (IP:port) of the raft peer to remove.
### Sample Request
```text
$ curl \
--request DELETE \
https://consul.rocks/v1/operator/raft/peer?address=1.2.3.4:5678
```

593
website/source/api/query.html.md Normal file
View File

@ -0,0 +1,593 @@
---
layout: api
page_title: Prepared Queries - HTTP API
sidebar_current: api-query
description: |-
The /query endpoints manage and execute prepared queries in Consul.
---
# Prepared Query HTTP Endpoint
The `/query` endpoints create, update, destroy, and execute prepared queries.
Prepared queries allow you to register a complex service query and then execute
it later via its ID or name to get a set of healthy nodes that provide a given
service. This is particularly useful in combination with Consul's
[DNS Interface](/docs/agent/dns.html) as it allows for much richer queries than
would be possible given the limited entry points exposed by DNS.
See the [Prepared Query ACLs](/docs/internals/acl.html#prepared_query_acls)
internals guide for more details about how prepared query policies work.
### Prepared Query Templates
Consul 0.6.4 and later support prepared query templates. These are created
similar to static templates, except with some additional fields and features.
Here is an example prepared query template:
```json
{
"Template": {
"Type": "name_prefix_match",
"Regexp": "^geo-db-(.*?)-([^\\-]+?)$"
}
}
```
The `Template` structure configures a prepared query as a template instead of a
static query. It has two fields:
- `Type` is the query type, which must be `name_prefix_match`. This means that
the template will apply to any query lookup with a name whose prefix matches
the `Name` field of the template. In this example, any query for `geo-db` will
match this query. Query templates are resolved using a longest prefix match,
so it's possible to have high-level templates that are overridden for specific
services. Static queries are always resolved first, so they can also override
templates.
- `Regexp` is an optional regular expression which is used to extract fields
from the entire name, once this template is selected. In this example, the
regular expression takes the first item after the "-" as the database name and
everything else after as a tag. See the
[RE2](https://github.com/google/re2/wiki/Syntax) reference for syntax of this
regular expression.
All other fields of the query have the same meanings as for a static query,
except that several interpolation variables are available to dynamically
populate the query before it is executed. All of the string fields inside the
`Service` structure are interpolated, with the following variables available:
- `${name.full}` has the entire name that was queried. For example, a DNS lookup
for `geo-db-customer-primary.query.consul` in the example above would set this
variable to `geo-db-customer-primary`.
- `${name.prefix}` has the prefix that matched. This would always be `geo-db`
for the example above.
- `${name.suffix}` has the suffix after the prefix. For example, a DNS lookup
for `geo-db-customer-primary.query.consul` in the example above would set this
variable to `-customer-primary`.
- `${match(N)}` returns the regular expression match at the given index N. The 0
index will have the entire match, and >0 will have the results of each match
group. For example, a DNS lookup for `geo-db-customer-primary.query.consul` in
the example above with a `Regexp` field set to `^geo-db-(.*?)-([^\-]+?)$`
would return `geo-db-customer-primary` for `${match(0)}`, `customer` for
`${match(1)}`, and `primary` for `${match(2)}`. If the regular expression
doesn't match, or an invalid index is given, then `${match(N)}` will return an
empty string.
Using templates, it is possible to apply prepared query behaviors to many
services with a single template. Here's an example template that matches any
query and applies a failover policy to it:
```json
{
"Name": "",
"Template": {
"Type": "name_prefix_match"
},
"Service": {
"Service": "${name.full}",
"Failover": {
"NearestN": 3
}
}
}
```
This will match any lookup for `*.query.consul` and will attempt to find the
service locally, and otherwise attempt to find that service in the next three
closest datacenters. If ACLs are enabled, a catch-all template like this with
an empty `Name` requires an ACL token that can write to any query prefix. Also,
only a single catch-all template can be registered at any time.
## Create Prepared Query
This endpoint creates a new prepared query and returns its ID if it is created
successfully.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/query` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------- |
| `NO` | `none` | `query:write` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `Name` `(string: "")` - Specifies an optional friendly name that can be used
to execute a query instead of using its ID.
- `Session` `(string: "")` - Specifies the ID of an existing session. This
provides a way to automatically remove a prepared query when the given session
is invalidated. If not given the prepared query must be manually removed when
no longer needed.
- `Token` `(string: "")` - Specifies the ACL token to use each time the query is
executed. This allows queries to be executed by clients with lesser or even no
ACL Token, so this should be used with care. The token itself can only be seen
by clients with a management token. If the `Token` field is left blank or
omitted, the client's ACL Token will be used to determine if they have access
to the service being queried. If the client does not supply an ACL Token, the
anonymous token will be used.
- `Near` `(string: "")` - Specifies a node to sort near based on distance
sorting using [Network Coordinates](/docs/internals/coordinates.html). The
nearest instance to the specified node will be returned first, and subsequent
nodes in the response will be sorted in ascending order of estimated
round-trip times. If the node given does not exist, the nodes in the response
will be shuffled. Using `_agent` is supported, and will automatically return
results nearest the agent servicing the request. If unspecified, the response
will be shuffled by default.
- `Service` `(Service: <required>)` - Specifies the structure to define the query's behavior.
- `Service` `(string: <required>)` - Specifies the name of the service to
query.
- `Failover` contains two fields, both of which are optional, and determine
what happens if no healthy nodes are available in the local datacenter when
the query is executed. It allows the use of nodes in other datacenters with
very little configuration.
- `NearestN` `(int: 0)` - Specifies that the query will be forwarded to up
to `NearestN` other datacenters based on their estimated network round
trip time using [Network Coordinates](/docs/internals/coordinates.html)
from the WAN gossip pool. The median round trip time from the server
handling the query to the servers in the remote datacenter is used to
determine the priority.
- `Datacenters` `(array<string>: nil)` - Specifies a fixed list of remote
datacenters to forward the query to if there are no healthy nodes in the
local datacenter. Datacenters are queried in the order given in the
list. If this option is combined with `NearestN`, then the `NearestN`
queries will be performed first, followed by the list given by
`Datacenters`. A given datacenter will only be queried one time during a
failover, even if it is selected by both `NearestN` and is listed in
`Datacenters`.
- `OnlyPassing` `(bool: false)` - Specifies the behavior of the query's health
check filtering. If this is set to false, the results will include nodes
with checks in the passing as well as the warning states. If this is set to
true, only nodes with checks in the passing state will be returned.
- `Tags` `(array<string>: nil)` - Specifies a list of service tags to filter
the query results. For a service to pass the tag filter it must have *all*
of the required tags, and *none* of the excluded tags (prefixed with `!`).
- `NodeMeta` `(map<string|string>: nil)` - Specifies a list of user-defined
key/value pairs that will be used for filtering the query results to nodes
with the given metadata values present.
- `DNS` `(DNS: nil)` - Specifies DNS configuration
- `TTL` `(string: "")` - Specifies the TTL duration when query results are
served over DNS. If this is specified, it will take precedence over any
Consul agent-specific configuration.
### Sample Payload
```json
{
"Name": "my-query",
"Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Token": "",
"Service": {
"Service": "redis",
"Failover": {
"NearestN": 3,
"Datacenters": ["dc1", "dc2"]
},
"Near": "node1",
"OnlyPassing": false,
"Tags": ["primary", "!experimental"],
"NodeMeta": {"instance_type": "m3.large"}
},
"DNS": {
"TTL": "10s"
}
}
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/query
```
### Sample Response
```json
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"
}
```
## Read Prepared Query
This endpoint returns a list of all prepared queries.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/query` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `query:read` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/query
```
### Sample Response
```json
[
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"Name": "my-query",
"Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Token": "<hidden>",
"Service": {
"Service": "redis",
"Failover": {
"NearestN": 3,
"Datacenters": ["dc1", "dc2"]
},
"OnlyPassing": false,
"Tags": ["primary", "!experimental"],
"NodeMeta": {"instance_type": "m3.large"}
},
"DNS": {
"TTL": "10s"
},
"RaftIndex": {
"CreateIndex": 23,
"ModifyIndex": 42
}
}
]
```
### Update Prepared Query
This endpoint updates an existing prepared query. If no query exists by the
given ID, an error is returned.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/query/:uuid` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------- |
| `NO` | `none` | `query:write` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the query to update.
This is required and is specified as part of the URL path.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
The body is the same as is used to create a prepared query. Please see above for
more information.
### Sample Response
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/query/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
## Read Prepared Query
This endpoint reads an existing prepared query. If no query exists by the
given ID, an error is returned.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/query/:uuid` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `query:read` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the query to read.
This is required and is specified as part of the URL path.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/query/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
### Sample Response
The returned response is the same as the list of prepared queries above, only
with a single item present.
## Delete Prepared Query
This endpoint deletes an existing prepared query. If no query exists by the
given ID, an error is returned.
| Method | Path | Produces |
| --------- | ---------------------------- | -------------------------- |
| `DELETE` | `/query/:uuid` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------- |
| `NO` | `none` | `query:write` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the query to delete.
This is required and is specified as part of the URL path.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
### Sample Request
```text
$ curl \
--request DELETE \
https://consul.rocks/v1/query/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
## Execute Prepared Query
This endpoint executes an existing prepared query. If no query exists by the
given ID, an error is returned.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/query/:uuid/execute` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `depends`<sup>1</sup> |
<sup>1</sup> If an ACL Token was bound to the query when it was defined then it
will be used when executing the request. Otherwise, the client's supplied ACL
Token will be used.
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the query to execute.
This is required and is specified as part of the URL path. This can also be
the name of an existing prepared query, or a name that matches a prefix name
for a prepared query template.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `near` `(string: "")` - Specifies to sort the resulting list in ascending
order based on the estimated round trip time from that node. Passing
`?near=_agent` will use the agent's node for the sort. If this is not present,
the default behavior will shuffle the nodes randomly each time the query is
executed.
- `limit` `(int: 0)` - Limit the size of the list to the given number of nodes.
This is applied after any sorting or shuffling.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/query/8f246b77-f3e1-ff88-5b48-8ec93abf3e05/execute?near=_agent
```
### Sample Response
```json
{
"Service": "redis",
"Nodes": [
{
"Node": {
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Address": "10.1.10.12",
"TaggedAddresses": {
"lan": "10.1.10.12",
"wan": "10.1.10.12"
},
"NodeMeta": {"instance_type": "m3.large"}
},
"Service": {
"ID": "redis",
"Service": "redis",
"Tags": null,
"Port": 8000
},
"Checks": [
{
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
},
{
"Node": "foobar",
"CheckID": "serfHealth",
"Name": "Serf Health Status",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "",
"ServiceName": ""
}
],
"DNS": {
"TTL": "10s"
},
"Datacenter": "dc3",
"Failovers": 2
}]
}
```
- `Nodes` contains the list of healthy nodes providing the given service, as
specified by the constraints of the prepared query.
- `Service` has the service name that the query was selecting. This is useful
for context in case an empty list of nodes is returned.
- `DNS` has information used when serving the results over DNS. This is just a
copy of the structure given when the prepared query was created.
- `Datacenter` has the datacenter that ultimately provided the list of nodes and
`Failovers` has the number of remote datacenters that were queried while
executing the query. This provides some insight into where the data came from.
This will be zero during non-failover operations where there were healthy
nodes found in the local datacenter.
## Explain Prepared Query
This endpoint generates a fully-rendered query for a given name, post
interpolation.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/query/:uuid/explain` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `query:read` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the query to explain.
This is required and is specified as part of the URL path. This can also be
the name of an existing prepared query, or a name that matches a prefix name
for a prepared query template.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/query/8f246b77-f3e1-ff88-5b48-8ec93abf3e05/explain
```
### Sample Response
```json
{
"Query": {
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"Name": "my-query",
"Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Token": "<hidden>",
"Name": "geo-db",
"Template": {
"Type": "name_prefix_match",
"Regexp": "^geo-db-(.*?)-([^\\-]+?)$"
},
"Service": {
"Service": "mysql-customer",
"Failover": {
"NearestN": 3,
"Datacenters": ["dc1", "dc2"]
},
"OnlyPassing": true,
"Tags": ["primary"],
"NodeMeta": {"instance_type": "m3.large"}
}
}
}
```

338
website/source/api/session.html.md Normal file
View File

@ -0,0 +1,338 @@
---
layout: api
page_title: Session - HTTP API
sidebar_current: api-session
description: |-
The /session endpoints create, destroy, and query sessions in Consul.
---
# Session HTTP Endpoint
The `/session` endpoints create, destroy, and query sessions in Cosul.
## Create Session
This endpoint initializes a new session. Sessions must be associated with a
node and may be associated with any number of checks.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/session/create` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `session:write` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended.
- `LockDelay` `(string: "15s")` - Specifies the duration for the lock delay.
- `Node` `(string: "<agent>")` - Specifies the name of the node. This must refer
to a node that is already registered.
- `Name` `(string: "")` - Specifies a human-readable name for the session.
- `Checks` `(array<string>: nil)` - specifies a list of associated health
checks. It is highly recommended that, if you override this list, you include
the default `serfHealth`.
- `Behavior` `(string: "release")` - Controls the behavior to take when a
session is invalidated. Valid values are:
- `release` - causes any locks that are held to be released
- `delete` - causes an locks that are held to be deleted
- `TTL` `(string: "")` - Specifies the number of seconds (between 10s and
86400s). If provided, the session is invalidated if it is not renewed before
the TTL expires. The lowest practical TTL should be used to keep the number of
managed sessions low. When locks are forcibly expired, such as during a leader
election, sessions may not be reaped for up to double this TTL, so long TTL
values (> 1 hour) should be avoided.
### Sample Payload
```json
{
"LockDelay": "15s",
"Name": "my-service-lock",
"Node": "foobar",
"Checks": ["a", "b", "c"],
"Behavior": "release",
"TTL": "30s"
}
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/session/create
```
### Sample Response
```javascript
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
```
- `ID` - the ID of the created session
## Delete Session
This endpoint destroys the session with the given name. If the session UUID is
malformed, an error is returned. If the session UUID does not exist or already
expired, a 200 is still returned (the operation is idempotent).
| Method | Path | Produces |
| :----- | :--------------------------- | -------------------------- |
| `PUT` | `/session/destroy/:uuid` | `application/json` |
Even though the Content-Type is `application/json`, the response is
either a literal `true` or `false`, indicating of whether the destroy was
successful.
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `session:write` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the session to destroy.
This is required and is specified as part of the URL path.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended.
### Sample Request
```text
$ curl \
--request PUT
https://consul.rocks/v1/session/destroy/adf4238a-882b-9ddc-4a9d-5b6758e4159e
```
### Sample Response
```json
true
```
## Read Session
This endpoint returns the requested session information.
| Method | Path | Produces |
| :----- | :--------------------------- | -------------------------- |
| `GET` | `/session/info/:uuid` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------- |
| `YES` | `all` | `session:read` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the session to read.
This is required and is specified as part of the URL path.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/session/info/adf4238a-882b-9ddc-4a9d-5b6758e4159e
```
### Sample Response
```json
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449
}
]
```
If the session does not exist, `null` is returned instead of a JSON list.
## List Sessions for Node
This endpoint returns the active sessions for a given node.
| Method | Path | Produces |
| :----- | :--------------------------- | -------------------------- |
| `GET` | `/session/node/:node` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------- |
| `YES` | `all` | `session:read` |
### Parameters
- `node` `(string: <required>)` - Specifies the name or ID of the node to query.
This is required and is specified as part of the URL path.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/session/node/node-abcd1234
```
### Sample Response
```json
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449
},
]
```
## List Sessions
This endpoint returns the list of active sessions.
| Method | Path | Produces |
| :----- | :--------------------------- | -------------------------- |
| `GET` | `/session/list` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------- |
| `YES` | `all` | `session:read` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended.
### Sample Request
```text
$ curl \
https://consul.rocks/v1/session/list
```
### Sample Response
```json
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449
},
]
```
## Renew Session
This endpoint renews the given session. This is used with sessions that have a
TTL, and it extends the expiration by the TTL.
| Method | Path | Produces |
| :----- | :--------------------------- | -------------------------- |
| `PUT` | `/session/renew/:uuid` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | --------------- |
| `NO` | `none` | `session:write` |
### Parameters
- `uuid` `(string: <required>)` - Specifies the UUID of the session to renew.
This is required and is specified as part of the URL path.
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter. Using this across datacenters is not recommended.
### Sample Request
```text
$ curl \
--request PUT \
https://consul.rocks/v1/session/renew/adf4238a-882b-9ddc-4a9d-5b6758e4159e
```
### Sample Response
```json
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449,
"Behavior": "release",
"TTL": "15s"
}
]
```
-> **Note:** Consul may return a TTL value higher than the one specified during session creation. This indicates the server is under high load and is requesting clients renew less often.

115
website/source/api/snapshot.html.md Normal file
View File

@ -0,0 +1,115 @@
---
layout: api
page_title: Snapshot - HTTP API
sidebar_current: api-snapshot
description: |-
The /snapshot endpoints save and restore Consul's server state for disaster
recovery.
---
# Snapshot HTTP Endpoint
The `/snapshot` endpoints save and restore the state of the Consul
servers for disaster recovery. Snapshots include all state managed by Consul's
Raft [consensus protocol](/docs/internals/consensus.html).
## Generate Snapshot
This endpoint generates and returns an atomic, point-in-time snapshot of the
Consul server state.
Snapshots are exposed as gzipped tar archives which internally contain the Raft
metadata required to restore, as well as a binary serialized version of the
Consul server state. The contents are covered internally by SHA-256 hashes.
These hashes are verified during snapshot restore operations. The structure of
the archive is internal to Consul and not intended to be used other than for
restore operations. The archives are not designed to be modified before a
restore.
| Method | Path | Produces |
| :----- | :--------------------------- | -------------------------- |
| `GET` | `/snapshot` | `200 application/x-gzip` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `default,stale` | `management` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default
to the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `stale` `(bool: false)` - Specifies that any follower may reply. By default
requests are forwarded to the leader. Followers may be faster to respond, but
may have stale data. To support bounding the acceptable staleness of
snapshots, responses provide the `X-Consul-LastContact` header containing the
time in milliseconds that a server was last contacted by the leader node. The
`X-Consul-KnownLeader` header also indicates if there is a known leader. These
can be used by clients to gauge the staleness of a snapshot and take
appropriate action. The stale mode is particularly useful for taking a
snapshot of a cluster in a failed state with no current leader.
### Sample Request
With a custom datacenter:
```text
$ curl https://consul.rocks/v1/snapshot?dc=my-datacenter
```
### Sample Response
```text
<gzipped tarball ...>
```
In addition to the Consul standard stale-related headers, the `X-Consul-Index`
header will contain the index at which the snapshot took place.
## Restore Snapshot
This endpoint restores a point-in-time snapshot of the Consul server state.
Restores involve a potentially dangerous low-level Raft operation that is not
designed to handle server failures during a restore. This operation is primarily
intended to be used when recovering from a disaster, restoring into a fresh
cluster of Consul servers.
The body of the request should be a snapshot archive returned from a previous
call to the `GET` method.
| Method | Path | Produces |
| :----- | :--------------------------- | ----------------------------- |
| `PUT` | `/snapshot` | `200 text/plain (empty body)` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `management` |
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default
to the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
### Sample Request
```text
$ curl \
--request PUT \
--data-binary @snapshot \
https://consul.rocks/v1/snapshot
```
~> Some tools default to www/encoded uploads. Consul expects the snapshot to be
in pure binary form.

80
website/source/api/status.html.md Normal file
View File

@ -0,0 +1,80 @@
---
layout: api
page_title: Status - HTTP API
sidebar_current: api-status
description: |-
The /status endpoints return information about the status of the Consul
cluster. This information is generally very low level and not often useful for
clients.
---
# Status HTTP API
The `/status` endpoints return information about the status of the Consul
cluster. This information is generally very low level and not often useful for
clients.
## Get Raft Leader
This endpoint returns the Raft leader for the datacenter in which the agent is
running.
| Method | Path | Produces |
| :----- | :--------------------------- | ---------------------- |
| `GET` | `/status/leader` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `none` |
### Sample Request
```text
$ curl https://consul.rocks/v1/status/leader
```
### Sample Response
```json
"10.1.10.12:8300"
```
## List Raft Peers
This endpoint retrieves the Raft peers for the datacenter in which the the agent
is running. This list of peers is strongly consistent and can be useful in
determining when a given server has successfully joined the cluster.
| Method | Path | Produces |
| :----- | :--------------------------- | ---------------------- |
| `GET` | `/status/peers` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `none` | `none` |
### Sample Request
```text
$ curl https://consul.rocks/v1/status/peers
```
### Sample Response
```json
[
"10.1.10.12:8300",
"10.1.10.11:8300",
"10.1.10.10:8300"
]
```

164
website/source/api/txn.markdown Normal file
View File

@ -0,0 +1,164 @@
---
layout: api
page_title: Transaction - HTTP API
sidebar_current: api-txn
description: |-
The /txn endpoints manage updates or fetches of multiple keys inside a single,
atomic transaction.
---
# Transactions HTTP API
The `/txn` endpoints manage updates or fetches of multiple keys inside a single,
atomic transaction. It is important to note that each datacenter has its own KV
store, and there is no built-in replication between datacenters.
## Create Transaction
This endpoint permits submitting a list of operations to apply to the KV store
inside of a transaction. If any operation fails, the transaction is rolled back
and none of the changes are applied.
If the transaction does not contain any write operations then it will be
fast-pathed internally to an endpoint that works like other reads, except that
blocking queries are not currently supported. In this mode, you may supply the
`?stale` or `?consistent` query parameters with the request to control
consistency. To support bounding the acceptable staleness of data, read-only
transaction responses provide the `X-Consul-LastContact` header containing the
time in milliseconds that a server was last contacted by the leader node. The
`X-Consul-KnownLeader` header also indicates if there is a known leader. These
won't be present if the transaction contains any write operations, and any
consistency query parameters will be ignored, since writes are always managed by
the leader via the Raft consensus protocol.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/txn` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `all`<sup>1</sup> | `key:read,key:write`<sup>2</sup> |
<sup>1</sup> For read-only transactions
<br>
<sup>2</sup> The ACL required depends on the operations in the transaction.
### Parameters
- `dc` `(string: "")` - Specifies the datacenter to query. This will default
to the datacenter of the agent being queried. This is specified as part of the
URL as a query parameter.
- `KV` is the only available operation type, though other types may be added in the future.
- `Verb` `(string: <required>)` - Specifies the type of operation to perform.
Please see the table below for available verbs.
- `Key` `(string: <required>)` - Specifies the full path of the entry.
- `Value` `(string: "")` - Specifies a **base64-encoded** blob of data. Values
cannot be larger than 512kB.
- `Flags` `(int: 0)` - Specifies an opaque unsigned integer that can be
attached to each entry. Clients can choose to use this however makes sense
for their application.
- `Index` `(int: 0)` - Specifies an index. See the table below for more
information.
- `Session` `(string: "")` - Specifies a session. See the table below for more
information.
### Sample Payload
The body of the request should be a list of operations to perform inside the
atomic transaction. Up to 64 operations may be present in a single transaction.
```javascript
[
{
"KV": {
"Verb": "<verb>",
"Key": "<key>",
"Value": "<Base64-encoded blob of data>",
"Flags": <flags>,
"Index": <index>,
"Session": "<session id>"
}
}
]
```
### Sample Request
```text
$ curl \
--request PUT \
--data @payload.json \
https://consul.rocks/v1/txn
```
### Sample Response
If the transaction can be processed, a status code of 200 will be returned if it
was successfully applied, or a status code of 409 will be returned if it was
rolled back. If either of these status codes are returned, the response will
look like this:
```javascript
{
"Results": [
{
"KV": {
"LockIndex": <lock index>,
"Key": "<key>",
"Flags": <flags>,
"Value": "<Base64-encoded blob of data, or null>",
"CreateIndex": <index>,
"ModifyIndex": <index>
}
}
],
"Errors": [
{
"OpIndex": <index of failed operation>,
"What": "<error message for failed operation>"
},
]
}
```
- `Results` has entries for some operations if the transaction was successful.
To save space, the `Value` will be `null` for any `Verb` other than "get" or
"get-tree". Like the `/v1/kv/<key>` endpoint, `Value` will be Base64-encoded
if it is present. Also, no result entries will be added for verbs that delete
keys.
- `Errors` has entries describing which operations failed if the transaction was
rolled back. The `OpIndex` gives the index of the failed operation in the
transaction, and `What` is a string with an error message about why that
operation failed.
### Table of Operations
The following table summarizes the available verbs and the fields that apply to
that operation ("X" means a field is required and "O" means it is optional):
| Verb | Operation | Key | Value | Flags | Index | Session |
| --------------- | -------------------------------------------- | :--: | :---: | :---: | :---: | :-----: |
| `set` | Sets the `Key` to the given `Value` | `x` | `x` | `o` | | |
| `cas` | Sets, but with CAS semantics | `x` | `x` | `o` | `x` | |
| `lock` | Lock with the given `Session` | `x` | `x` | `o` | | `x` |
| `unlock` | Unlock with the given `Session` | `x` | `x` | `o` | | `x` |
| `get` | Get the key, fails if it does not exist | `x` | | | | |
| `get-tree` | Gets all keys with the prefix | `x` | | | | |
| `check-index` | Fail if modify index != index | `x` | | | `x` | |
| `check-session` | Fail if not locked by session | `x` | | | | `x` |
| `delete` | Delete the key | `x` | | | | |
| `delete-tree` | Delete all keys with a prefix | `x` | | | | |
| `delete-cas` | Delete, but with CAS semantics | `x` | | | `x` | |

4
website/source/docs/agent/checks.html.markdown
View File

@ -62,8 +62,8 @@ There are five different kinds of checks:
can periodically `PUT` a status update to the HTTP endpoint; if the app fails, the TTL will
expire and the health check enters a critical state. The endpoints used to
update health information for a given check are the
[pass endpoint](https://www.consul.io/docs/agent/http/agent.html#agent_check_pass)
and the [fail endpoint](https://www.consul.io/docs/agent/http/agent.html#agent_check_fail).
[pass endpoint](https://www.consul.io/api/agent.html#agent_check_pass)
and the [fail endpoint](https://www.consul.io/api/agent.html#agent_check_fail).
TTL checks also persist
their last known status to disk. This allows the Consul agent to restore the
last known status of the check across restarts. Persisted check status is

4
website/source/docs/agent/dns.html.markdown
View File

@ -185,11 +185,11 @@ The `datacenter` is optional, and if not provided, the datacenter of this Consul
agent is assumed.
The `query or name` is the ID or given name of an existing
[Prepared Query](/docs/agent/http/query.html). These behave like standard service
[Prepared Query](/api/query.html). These behave like standard service
queries but provide a much richer set of features, such as filtering by multiple
tags and automatically failing over to look for services in remote datacenters if
no healthy nodes are available in the local datacenter. Consul 0.6.4 and later also
added support for [prepared query templates](/docs/agent/http/query.html#templates)
added support for [prepared query templates](/api/query.html#templates)
which can match names using a prefix match, allowing one template to apply to
potentially many services.

112
website/source/docs/agent/http.html.markdown
View File

@ -1,112 +0,0 @@
---
layout: "docs"
page_title: "HTTP API"
sidebar_current: "docs-agent-http"
description: |-
The main interface to Consul is a RESTful HTTP API. The API can be used to perform CRUD operations on nodes, services, checks, configuration, and more. The endpoints are versioned to enable changes without breaking backwards compatibility.
---
# HTTP API
The main interface to Consul is a RESTful HTTP API. The API can be used to perform CRUD
operations on nodes, services, checks, configuration, and more. The endpoints are versioned
to enable changes without breaking backwards compatibility.
Each endpoint manages a different aspect of Consul:
* [acl](http/acl.html) - Access Control Lists
* [agent](http/agent.html) - Consul Agent
* [catalog](http/catalog.html) - Nodes and Services
* [coordinate](http/coordinate.html) - Network Coordinates
* [event](http/event.html) - User Events
* [health](http/health.html) - Health Checks
* [kv](http/kv.html) - Key/Value Store
* [operator](http/operator.html) - Consul Operator Tools
* [query](http/query.html) - Prepared Queries
* [session](http/session.html) - Sessions
* [snapshot](http/snapshot.html) - Consul Snapshots for Disaster Recovery
* [status](http/status.html) - Consul System Status
Each of these is documented in detail at the links above. Consul also has a number
of internal APIs which are purposely undocumented and subject to change.
## Blocking Queries
Certain endpoints support a feature called a "blocking query." A blocking query
is used to wait for a potential change using long polling.
Not all endpoints support blocking, but those that do are clearly designated in the
documentation. Any endpoint that supports blocking will also set the HTTP header
`X-Consul-Index`, a unique identifier representing the current state of the
requested resource. On subsequent requests for this resource, the client can set the `index`
query string parameter to the value of `X-Consul-Index`, indicating that the client wishes
to wait for any changes subsequent to that index.
In addition to `index`, endpoints that support blocking will also honor a `wait`
parameter specifying a maximum duration for the blocking request. This is limited to
10 minutes. If not set, the wait time defaults to 5 minutes. This value can be specified
in the form of "10s" or "5m" (i.e., 10 seconds or 5 minutes, respectively). A small random
amount of additional wait time is added to the supplied maximum `wait` time to spread out
the wake up time of any concurrent requests. This adds up to `wait / 16` additional time
to the maximum duration.
A critical note is that the return of a blocking request is **no guarantee** of a change. It
is possible that the timeout was reached or that there was an idempotent write that does
not affect the result of the query.
## <a id="consistency"></a>Consistency Modes
Most of the read query endpoints support multiple levels of consistency. Since no policy will
suit all clients' needs, these consistency modes allow the user to have the ultimate say in
how to balance the trade-offs inherent in a distributed system.
The three read modes are:
* default - If not specified, the default is strongly consistent in almost all cases. However,
there is a small window in which a new leader may be elected during which the old leader may
service stale values. The trade-off is fast reads but potentially stale values. The condition
resulting in stale reads is hard to trigger, and most clients should not need to worry about
this case. Also, note that this race condition only applies to reads, not writes.
* consistent - This mode is strongly consistent without caveats. It requires
that a leader verify with a quorum of peers that it is still leader. This
introduces an additional round-trip to all server nodes. The trade-off is
increased latency due to an extra round trip. Most clients should not use this
unless they cannot tolerate a stale read.
* stale - This mode allows any server to service the read regardless of whether
it is the leader. This means reads can be arbitrarily stale; however, results are generally
consistent to within 50 milliseconds of the leader. The trade-off is very fast and
scalable reads with a higher likelihood of stale values. Since this mode allows reads without
a leader, a cluster that is unavailable will still be able to respond to queries.
To switch these modes, either the `stale` or `consistent` query parameters
should be provided on requests. It is an error to provide both.
To support bounding the acceptable staleness of data, responses provide the `X-Consul-LastContact`
header containing the time in milliseconds that a server was last contacted by the leader node.
The `X-Consul-KnownLeader` header also indicates if there is a known leader. These can be used
by clients to gauge the staleness of a result and take appropriate action.
## Formatted JSON Output
By default, the output of all HTTP API requests is minimized JSON. If the client passes `pretty`
on the query string, formatted JSON will be returned.
## ACLs
Several endpoints in Consul use or require ACL tokens to operate. An agent
can be configured to use a default token in requests using the `acl_token`
configuration option. However, the token can also be specified per-request
by using the `X-Consul-Token` request header or the `token` querystring
parameter. The request header takes precedence over the default token, and
the querystring parameter takes precedence over everything.
## <a id="translate_header"></a>Translated Addresses
Consul 0.7 added the ability to translate addresses in HTTP response based on the configuration
setting for [`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs). In order to
allow clients to know if address translation is in effect, the `X-Consul-Translate-Addresses`
header will be added if translation is enabled, and will have a value of `true`. If translation
is not enabled then this header will not be present.

223
website/source/docs/agent/http/acl.html.markdown
View File

@ -1,223 +0,0 @@
---
layout: "docs"
page_title: "ACLs (HTTP)"
sidebar_current: "docs-agent-http-acl"
description: >
The ACL endpoints are used to create, update, destroy, and query ACL tokens.
---
# ACL HTTP Endpoint
The ACL endpoints are used to create, update, destroy, and query ACL tokens.
The following endpoints are supported:
* [`/v1/acl/create`](#acl_create): Creates a new token with a given policy
* [`/v1/acl/update`](#acl_update): Updates the policy of a token
* [`/v1/acl/destroy/<id>`](#acl_destroy): Destroys a given token
* [`/v1/acl/info/<id>`](#acl_info): Queries the policy of a given token
* [`/v1/acl/clone/<id>`](#acl_clone): Creates a new token by cloning an existing token
* [`/v1/acl/list`](#acl_list): Lists all the active tokens
* [`/v1/acl/replication`](#acl_replication_status): Checks status of ACL replication
### <a name="acl_create"></a> /v1/acl/create
The `create` endpoint is used to make a new token. A token has a name,
a type, and a set of ACL rules.
The `Name` property is opaque to Consul. To aid human operators, it should
be a meaningful indicator of the ACL's purpose.
Type is either `client` or `management`. A management token is comparable
to a root user and has the ability to perform any action including
creating, modifying, and deleting ACLs.
By contrast, a client token can only perform actions as permitted by the
rules associated. Client tokens can never manage ACLs. Given this limitation,
only a management token can be used to make requests to the `/v1/acl/create`
endpoint.
In any Consul cluster, only a single datacenter is authoritative for ACLs, so
all requests are automatically routed to that datacenter regardless
of the agent to which the request is made.
The create endpoint supports a JSON request body with the `PUT`. The request
body may take the form:
```javascript
{
"Name": "my-app-token",
"Type": "client",
"Rules": ""
}
```
None of the fields are mandatory. In fact, no body needs to be `PUT` if the
defaults are to be used. The `Name` and `Rules` fields default to being
blank, and the `Type` defaults to "client".
The `ID` field may be provided, and if omitted a random UUID will be generated.
The security of the ACL system depends on the difficulty of guessing the token.
Tokens should not be generated in a predictable manner or with too little entropy.
The format of the `Rules` property is [documented here](/docs/internals/acl.html).
A successful response body will return the `ID` of the newly created ACL, like so:
```javascript
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
```
### <a name="acl_update"></a> /v1/acl/update
The update endpoint is used to modify the policy for a given ACL token. It
is very similar to the create endpoint; however, instead of generating a new
token ID, the `ID` field must be provided. As with [`/v1/acl/create`](#acl_create),
requests to this endpoint must be made with a management token. If the ID does not
exist, the ACL will be inserted. In this sense, create and update are identical.
In any Consul cluster, only a single datacenter is authoritative for ACLs, so
all requests are automatically routed to that datacenter regardless
of the agent to which the request is made.
The update endpoint requires a JSON request body to the `PUT`. The request
body may look like:
```javascript
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Name": "my-app-token-updated",
"Type": "client",
"Rules": "# New Rules",
}
```
Only the `ID` field is mandatory. The other fields provide defaults: the
`Name` and `Rules` fields default to being blank, and `Type` defaults to "client".
The format of `Rules` is [documented here](/docs/internals/acl.html).
### <a name="acl_destroy"></a> /v1/acl/destroy/\<id\>
The destroy endpoint must be hit with a `PUT`. This endpoint destroys the ACL
token identified by the `id` portion of the path.
The request is automatically routed to the authoritative ACL datacenter.
Requests to this endpoint must be made with a management token.
### <a name="acl_info"></a> /v1/acl/info/\<id\>
The info endpoint must be hit with a `GET`. This endpoint returns the ACL
token information identified by the `id` portion of the path.
It returns a JSON body like this:
```javascript
[
{
"CreateIndex": 3,
"ModifyIndex": 3,
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"Name": "Client Token",
"Type": "client",
"Rules": "..."
}
]
```
If the ACL is not found, null is returned instead of a JSON list.
### <a name="acl_clone"></a> /v1/acl/clone/\<id\>
The clone endpoint must be hit with a `PUT`. It clones the ACL identified
by the `id` portion of the path and returns a new token `ID`. This allows
a token to serve as a template for others, making it simple to generate new
tokens without complex rule management.
The request is automatically routed to the authoritative ACL datacenter.
Requests to this endpoint must be made with a management token.
As with `create`, a successful response body will return the `ID` of the newly
created ACL, like so:
```javascript
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
```
### <a name="acl_list"></a> /v1/acl/list
The list endpoint must be hit with a `GET`. It lists all the active
ACL tokens. This is a privileged endpoint and requires a
management token.
It returns a JSON body like this:
```javascript
[
{
"CreateIndex": 3,
"ModifyIndex": 3,
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"Name": "Client Token",
"Type": "client",
"Rules": "..."
},
...
]
```
### <a name="acl_replication_status"></a> /v1/acl/replication
Available in Consul 0.7 and later, the endpoint must be hit with a
`GET` and returns the status of the [ACL replication](/docs/internals/acl.html#replication)
process in the datacenter. This is intended to be used by operators, or by
automation checking the health of ACL replication.
By default, the datacenter of the agent is queried; however, the `dc` can be provided
using the `?dc=` query parameter.
It returns a JSON body like this:
```javascript
{
"Enabled": true,
"Running": true,
"SourceDatacenter": "dc1",
"ReplicatedIndex": 1976,
"LastSuccess": "2016-08-05T06:28:58Z",
"LastError": "2016-08-05T06:28:28Z"
}
```
`Enabled` reports whether ACL replication is enabled for the datacenter.
`Running` reports whether the ACL replication process is running. The process
may take approximately 60 seconds to begin running after a leader election occurs.
`SourceDatacenter` is the authoritative ACL datacenter that ACLs are being
replicated from, and will match the
[`acl_datacenter`](/docs/agent/options.html#acl_datacenter) configuration.
`ReplicatedIndex` is the last index that was successfully replicated. You can
compare this to the `X-Consul-Index` header returned by the [`/v1/acl/list`](#acl_list)
endpoint to determine if the replication process has gotten all available
ACLs. Replication runs as a background process approximately every 30
seconds, and that local updates are rate limited to 100 updates/second, so so it
may take several minutes to perform the initial sync of a large set of ACLs.
After the initial sync, replica lag should be on the order of about 30 seconds.
`LastSuccess` is the UTC time of the last successful sync operation.
Since ACL replication is done with a blocking query, this may not update
for up to 5 minutes if there have been no ACL changes to replicate. A
zero value of "0001-01-01T00:00:00Z" will be present if no sync has been
successful.
`LastError` is the UTC time of the last error encountered during a sync operation.
If this time is later than `LastSuccess`, you can assume the replication process
is not in a good state. A zero value of "0001-01-01T00:00:00Z" will be present if
no sync has resulted in an error.
Please see the [ACL replication](/docs/internals/acl.html#replication)
section of the internals guide for more details.

562
website/source/docs/agent/http/agent.html.markdown
View File

@ -1,562 +0,0 @@
---
layout: "docs"
page_title: "Agent (HTTP)"
sidebar_current: "docs-agent-http-agent"
description: >
The Agent endpoints are used to interact with the local Consul agent.
---
# Agent HTTP Endpoint
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.
The following endpoints are supported:
* [`/v1/agent/checks`](#agent_checks) : Returns the checks the local agent is managing
* [`/v1/agent/services`](#agent_services) : Returns the services the local agent is managing
* [`/v1/agent/members`](#agent_members) : Returns the members as seen by the local serf agent
* [`/v1/agent/self`](#agent_self) : Returns the local node configuration
* [`/v1/agent/reload`](#agent_reload) : Causes the local agent to reload its configuration
* [`/v1/agent/maintenance`](#agent_maintenance) : Manages node maintenance mode
* [`/v1/agent/monitor`](#agent_monitor) : Streams logs from the local agent
* [`/v1/agent/join/<address>`](#agent_join) : Triggers the local agent to join a node
* [`/v1/agent/leave`](#agent_leave): Triggers the local agent to gracefully shutdown and leave the cluster
* [`/v1/agent/force-leave/<node>`](#agent_force_leave): Forces removal of a node
* [`/v1/agent/check/register`](#agent_check_register) : Registers a new local check
* [`/v1/agent/check/deregister/<checkID>`](#agent_check_deregister) : Deregisters a local check
* [`/v1/agent/check/pass/<checkID>`](#agent_check_pass) : Marks a local check as passing
* [`/v1/agent/check/warn/<checkID>`](#agent_check_warn) : Marks a local check as warning
* [`/v1/agent/check/fail/<checkID>`](#agent_check_fail) : Marks a local check as critical
* [`/v1/agent/check/update/<checkID>`](#agent_check_update) : Updates a local check
* [`/v1/agent/service/register`](#agent_service_register) : Registers a new local service
* [`/v1/agent/service/deregister/<serviceID>`](#agent_service_deregister) : Deregisters a local service
* [`/v1/agent/service/maintenance/<serviceID>`](#agent_service_maintenance) : Manages service maintenance mode
### <a name="agent_checks"></a> /v1/agent/checks
This endpoint is used to return all the checks that are registered with
the local agent. These checks were either provided through configuration files
or added dynamically using the HTTP API. It is important to note that the checks
known by the agent may be different from those reported by the Catalog. This is usually
due to changes being made while there is no leader elected. The agent performs active
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations everything will
be in sync within a few seconds.
This endpoint is hit with a `GET` and returns a JSON body like this:
```javascript
{
"service:redis": {
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
}
}
```
### <a name="agent_services"></a> /v1/agent/services
This endpoint is used to return all the services that are registered with
the local agent. These services were either provided through configuration files
or added dynamically using the HTTP API. It is important to note that the services
known by the agent may be different from those reported by the Catalog. This is usually
due to changes being made while there is no leader elected. The agent performs active
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations everything will
be in sync within a few seconds.
This endpoint is hit with a `GET` and returns a JSON body like this:
```javascript
{
"redis": {
"ID": "redis",
"Service": "redis",
"Tags": null,
"Address": "",
"Port": 8000
}
}
```
### <a name="agent_members"></a> /v1/agent/members
This endpoint is used to return 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`.
For agents running in server mode, providing a `?wan=1` query parameter returns
the list of WAN members instead of the LAN members returned by default.
This endpoint is hit with a `GET` and returns a JSON body like:
```javascript
[
{
"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
}
]
```
### <a name="agent_self"></a> /v1/agent/self
This endpoint is used to return the configuration and member information of the local agent under the `Config` key.
Consul 0.7.0 and later also includes a snapshot of various operating statistics under the `Stats` key. These statistics are intended to help human operators for debugging and may change over time, so this part of the interface should not be consumed programmatically.
Consul 0.7.3 and later also includes a block of user-defined node metadata values under the `Meta` key. These are arbitrary key/value pairs defined in the [node meta](/docs/agent/options.html#_node_meta) section of the agent configuration.
It returns a JSON body like this:
```javascript
{
"Config": {
"Bootstrap": true,
"Server": true,
"Datacenter": "dc1",
"DataDir": "/tmp/consul",
"DNSRecursor": "",
"DNSRecursors": [],
"Domain": "consul.",
"LogLevel": "INFO",
"NodeID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"NodeName": "foobar",
"ClientAddr": "127.0.0.1",
"BindAddr": "0.0.0.0",
"AdvertiseAddr": "10.1.10.12",
"Ports": {
"DNS": 8600,
"HTTP": 8500,
"RPC": 8400,
"SerfLan": 8301,
"SerfWan": 8302,
"Server": 8300
},
"LeaveOnTerm": false,
"SkipLeaveOnInt": false,
"StatsiteAddr": "",
"Protocol": 1,
"EnableDebug": false,
"VerifyIncoming": false,
"VerifyOutgoing": false,
"CAFile": "",
"CertFile": "",
"KeyFile": "",
"StartJoin": [],
"UiDir": "",
"PidFile": "",
"EnableSyslog": false,
"RejoinAfterLeave": false
},
"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",
}
}
```
### <a name="agent_reload"></a> /v1/agent/reload
Added in Consul 0.7.2, this endpoint is hit with a `PUT` and is used to instruct
the agent to reload its configuration. Any errors encountered during this process
will be 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.
The return code is 200 on success.
### <a name="agent_maintenance"></a> /v1/agent/maintenance
The node maintenance endpoint is hit with a PUT and is used to place 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 `?enable` flag is required. Acceptable values are either `true` (to enter
maintenance mode) or `false` (to resume normal operation).
The `?reason` flag is optional. If provided, its value should be 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.
The return code is 200 on success.
### <a name="agent_monitor"></a> /v1/agent/monitor
Added in Consul 0.7.2, This endpoint is hit with a GET and will stream logs from the
local agent until the connection is closed.
The `?loglevel` flag is optional. If provided, its value should be a text string
containing a log level to filter on, such as `info`. If no loglevel is provided,
`info` will be used as a default.
The return code is 200 on success.
### <a name="agent_join"></a> /v1/agent/join/\<address\>
This endpoint is hit with a `GET` and is used to instruct the agent to attempt to
connect to a given address. For agents running in server mode, providing a `?wan=1`
query parameter causes the agent to attempt to join using the WAN pool.
The return code is 200 on success.
### <a name="agent_leave"></a> /v1/agent/leave
Added in Consul 0.7.2, this endpoint is hit with a `PUT` and is used to trigger 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 return code is 200 on success.
### <a name="agent_force_leave"></a> /v1/agent/force-leave/\<node\>
This endpoint is hit with a `PUT` and is used to instruct 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.
The endpoint always returns 200.
### <a name="agent_check_register"></a> /v1/agent/check/register
The register endpoint is used to add a new check to the local agent.
There is more documentation on checks [here](/docs/agent/checks.html).
Checks may be of script, HTTP, TCP, or TTL type. The agent is responsible for
managing the status of the check and keeping the Catalog in sync.
The register endpoint expects a JSON request body to be `PUT`. The request
body must look like:
```javascript
{
"ID": "mem",
"Name": "Memory utilization",
"Notes": "Ensure we don't oversubscribe memory",
"DeregisterCriticalServiceAfter": "90m",
"Script": "/usr/local/bin/check_mem.py",
"DockerContainerID": "f972c95ebf0e",
"Shell": "/bin/bash",
"HTTP": "http://example.com",
"TCP": "example.com:22",
"Interval": "10s",
"TTL": "15s",
"TLSSkipVerify": true
}
```
The `Name` field is mandatory, as is one of `Script`, `HTTP`, `TCP` or `TTL`.
`Script`, `TCP` and `HTTP` also require that `Interval` be set.
If an `ID` is not provided, it is set to `Name`. You cannot have duplicate
`ID` entries per agent, so it may be necessary to provide an `ID`.
The `Notes` field is not used internally by Consul and is meant to be human-readable.
In Consul 0.7 and later, checks that are associated with a service may also contain
an optional `DeregisterCriticalServiceAfter` field, which is a timeout in the same Go
time format as `Interval` and `TTL`. If a check is in the critical state for more than
this configured value, then its associated service (and all of its associated checks)
will automatically be deregistered. The minimum timeout is 1 minute, and the
process that reaps critical services runs every 30 seconds, so it may take slightly
longer than the configured timeout to trigger the deregistration. This should
generally be configured with a timeout that's much, much longer than any expected
recoverable outage for the given service.
If a `Script` is provided, the check type is a script, and Consul will
evaluate the script every `Interval` to update the status.
If a `DockerContainerID` is provided, the check is a Docker check, and Consul will
evaluate the script every `Interval` in the given container using the specified
`Shell`. Note that `Shell` is currently only supported for Docker checks.
An `HTTP` check will perform an HTTP `GET` request against the value of
`HTTP` (expected to be a URL) every `Interval`. If the response is any
`2xx` code, the check is `passing`. If the response is `429 Too Many
Requests`, the check is `warning`. Otherwise, the check is `critical`.
HTTP checks also support SSL. By default, a valid SSL certificate is
expected. Certificate verification can be controlled using the
`TLSSkipVerify`.
If `TLSSkipVerify` is set to `true`, certificate verification will be
disabled. By default, certificate verification is enabled.
A `TCP` check will perform an TCP connection attempt against the value of `TCP`
(expected to be an IP or hostname plus port combination) every `Interval`. If the
connection attempt is successful, the check is `passing`. If the connection
attempt is unsuccessful, the check is `critical`. In the case of a hostname
that resolves to both IPv4 and IPv6 addresses, an attempt will be made to both
addresses, and the first successful connection attempt will result in a
successful check.
If a `TTL` type is used, then the TTL update endpoint must be used
periodically to update the state of the check.
The `ServiceID` field can be provided to associate the registered check with an
existing service provided by the agent.
The `Status` field can be provided to specify the initial state of the health
check.
This endpoint supports [ACL tokens](/docs/internals/acl.html). If the query
string includes a `?token=<token-id>`, the registration will use the provided
token to authorize the request. The token is also persisted in the agent's
local configuration to enable periodic
[anti-entropy](/docs/internals/anti-entropy.html) syncs and seamless agent
restarts.
The return code is 200 on success.
### <a name="agent_check_deregister"></a> /v1/agent/check/deregister/\<checkId\>
This endpoint is used to remove a check from the local agent.
The `CheckID` must be passed on the path. The agent will take care
of deregistering the check from the Catalog.
The return code is 200 on success.
### <a name="agent_check_pass"></a> /v1/agent/check/pass/\<checkId\>
This endpoint is used with a check that is of the [TTL type](/docs/agent/checks.html).
When this endpoint is accessed via a `GET`, the status of the check is set to `passing`
and the TTL clock is reset.
The optional `?note=` query parameter can be used to associate a
human-readable message with the status of the check. This will be passed
through to the check's `Output` field in the check endpoints.
The return code is 200 on success.
### <a name="agent_check_warn"></a> /v1/agent/check/warn/\<checkId\>
This endpoint is used with a check that is of the [TTL type](/docs/agent/checks.html).
When this endpoint is accessed via a `GET`, the status of the check is set to `warning`,
and the TTL clock is reset.
The optional `?note=` query parameter can be used to associate a
human-readable message with the status of the check. This will be passed
through to the check's `Output` field in the check endpoints.
The return code is 200 on success.
### <a name="agent_check_fail"></a> /v1/agent/check/fail/\<checkId\>
This endpoint is used with a check that is of the [TTL
type](/docs/agent/checks.html). When this endpoint is accessed via a
`GET`, the status of the check is set to `critical`, and the TTL clock is
reset.
The optional `?note=` query parameter can be used to associate a
human-readable message with the status of the check. This will be passed
through to the check's `Output` field in the check endpoints.
The return code is 200 on success.
### <a name="agent_check_update"></a> /v1/agent/check/update/\<checkId\>
This endpoint is used with a check that is of the [TTL type](/docs/agent/checks.html).
When this endpoint is accessed with a `PUT`, the status and output of the check are
updated and the TTL clock is reset.
This endpoint expects a JSON request body to be put. The request body must look like:
```javascript
{
"Status": "passing",
"Output": "curl reported a failure:\n\n..."
}
```
The `Status` field is mandatory, and must be set to `passing`,
`warning`, or `critical`.
`Output` is an optional field that will associate a human-readable
message with the status of the check, such as the output of the checking
script or process. This will be truncated if it exceeds 4KB in size.
This will be passed through to the check's `Output` field in the check
endpoints.
The return code is 200 on success.
### <a name="agent_service_register"></a> /v1/agent/service/register
The register endpoint is used to add a new service, with an optional
health check, to the local agent. There is more documentation on
services [here](/docs/agent/services.html). The agent is responsible
for managing the status of its local services, and for sending updates
about its local services to the servers to keep the global Catalog in
sync.
The register endpoint expects a JSON request body to be `PUT`. The request
body must look like:
```javascript
{
"ID": "redis1",
"Name": "redis",
"Tags": [
"primary",
"v1"
],
"Address": "127.0.0.1",
"Port": 8000,
"EnableTagOverride": false,
"Check": {
"DeregisterCriticalServiceAfter": "90m",
"Script": "/usr/local/bin/check_redis.py",
"HTTP": "http://localhost:5000/health",
"Interval": "10s",
"TTL": "15s"
}
}
```
The `Name` field is mandatory. If an `ID` is not provided, it is set to
`Name`. You cannot have duplicate `ID` entries per agent, so it may be
necessary to provide an ID in the case of a collision.
`Tags`, `Address`, `Port`, `Check` and `EnableTagOverride` are optional.
If `Address` is not provided or left empty, then the agent's address will be used
as the address for the service during DNS queries. When querying for services using
HTTP endpoints such as [service health](/docs/agent/http/health.html#health_service)
or [service catalog](/docs/agent/http/catalog.html#catalog_service) and encountering
an empty `Address` field for a service, use the `Address` field of the agent node
associated with that instance of the service, which is returned alongside the service
information.
If `Check` is provided, only one of `Script`, `HTTP`, `TCP` or `TTL`
should be specified. `Script` and `HTTP` also require `Interval`. The
created check will be named `service:<ServiceId>`. The `Status` field
can be provided to specify the initial state of the health check.
In Consul 0.7 and later, checks that are associated with a service may
also contain an optional `DeregisterCriticalServiceAfter` field, which
is a timeout in the same [Go time format](https://golang.org/pkg/time/)
as `Interval` and `TTL`. If a check is in the critical state for more
than this configured value, then its associated service (and all of its
associated checks) will automatically be deregistered. The minimum
timeout is 1 minute, and the process that reaps critical services runs
every 30 seconds, so it may take slightly longer than the configured
timeout to trigger the deregistration. This should generally be
configured with a timeout that is much, much longer than any expected
recoverable outage for the given service.
There is more information about checks [here](/docs/agent/checks.html).
The `EnableTagOverride` option can be specified to disable the
anti-entropy feature for this service's tags. If `EnableTagOverride` is
set to `true` then external agents can update this service in the
[catalog](/docs/agent/http/catalog.html) and modify the tags. Subsequent
local sync operations by this agent will ignore the updated tags. For
instance, if an external agent modified both the tags and the port for
this service and `EnableTagOverride` was set to `true` then after the
next sync cycle the service's port would revert to the original value
but the tags would maintain the updated value. As a counter example, if
an external agent modified both the tags and port for this service and
`EnableTagOverride` was set to `false` then after the next sync cycle
the service's port _and_ the tags would revert to the original value and
all modifications would be lost.
It's important to note that this applies only to the locally registered
service. If you have multiple nodes all registering the same service
their `EnableTagOverride` configuration and all other service
configuration items are independent of one another. Updating the tags
for the service registered on one node is independent of the same
service (by name) registered on another node. If `EnableTagOverride` is
not specified the default value is `false`. See [anti-entropy
syncs](/docs/internals/anti-entropy.html) for more info.
This endpoint supports [ACL tokens](/docs/internals/acl.html). If the query
string includes a `?token=<token-id>`, the registration will use the provided
token to authorize the request. The token is also persisted in the agent's
local configuration to enable periodic
[anti-entropy](/docs/internals/anti-entropy.html) syncs and seamless agent
restarts.
The return code is 200 on success.
### <a name="agent_service_deregister"></a> /v1/agent/service/deregister/\<serviceId\>
The deregister endpoint is used to remove a service from the local agent.
The `ServiceID` must be passed after the slash. The agent will take care
of deregistering the service with the Catalog. If there is an associated
check, that is also deregistered.
The return code is 200 on success.
### <a name="agent_service_maintenance"></a> /v1/agent/service/maintenance/\<serviceId\>
The service maintenance endpoint allows placing a given service into
"maintenance mode". During maintenance mode, the service 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 maintenance endpoint expects a `PUT` request.
The `?enable` flag is required. Acceptable values are either `true` (to enter
maintenance mode) or `false` (to resume normal operation).
The `?reason` flag is optional. If provided, its value should be a text string
explaining the reason for placing the service into maintenance mode. This is simply
to aid human operators. If no reason is provided, a default value will be used instead.
The return code is 200 on success.

376
website/source/docs/agent/http/catalog.html.markdown
View File

@ -1,376 +0,0 @@
---
layout: "docs"
page_title: "Catalog (HTTP)"
sidebar_current: "docs-agent-http-catalog"
description: >
The Catalog is the endpoint used to register and deregister nodes,
services, and checks. It also provides query endpoints.
---
# Catalog HTTP Endpoint
The Catalog is the endpoint used to register and deregister nodes,
services, and checks. It also provides query endpoints.
The following endpoints are supported:
* [`/v1/catalog/register`](#catalog_register) : Registers a new node, service, or check
* [`/v1/catalog/deregister`](#catalog_deregister) : Deregisters a node, service, or check
* [`/v1/catalog/datacenters`](#catalog_datacenters) : Lists known datacenters
* [`/v1/catalog/nodes`](#catalog_nodes) : Lists nodes in a given DC
* [`/v1/catalog/services`](#catalog_services) : Lists services in a given DC
* [`/v1/catalog/service/<service>`](#catalog_service) : Lists the nodes in a given service
* [`/v1/catalog/node/<node>`](#catalog_node) : Lists the services provided by a node
The `nodes` and `services` endpoints support blocking queries and
tunable consistency modes.
### <a name="catalog_register"></a> /v1/catalog/register
The register endpoint is a low-level mechanism for registering or updating
entries in the catalog. It is usually preferable to instead use the
[agent endpoints](agent.html) for registration as they are simpler and perform
[anti-entropy](/docs/internals/anti-entropy.html).
The register endpoint expects a JSON request body to be `PUT`. The request
body must look something like:
```javascript
{
"Datacenter": "dc1",
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Address": "192.168.10.10",
"TaggedAddresses": {
"lan": "192.168.10.10",
"wan": "10.0.10.10"
},
"NodeMeta": {
"somekey": "somevalue"
},
"Service": {
"ID": "redis1",
"Service": "redis",
"Tags": [
"primary",
"v1"
],
"Address": "127.0.0.1",
"Port": 8000
},
"Check": {
"Node": "foobar",
"CheckID": "service:redis1",
"Name": "Redis health check",
"Notes": "Script based health check",
"Status": "passing",
"ServiceID": "redis1"
}
}
```
The behavior of the endpoint depends on what keys are provided. The endpoint
requires `Node` and `Address` to be provided while `Datacenter` will be defaulted
to match that of the agent. If only those are provided, the endpoint will register
the node with the catalog. `TaggedAddresses` can be used in conjunction with the
[`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs) configuration
option and the `wan` address. The `lan` address was added in Consul 0.7 to help find
the LAN address if address translation is enabled. The `ID` field was added in Consul
0.7.3 and is optional, but if supplied must be in the form of a hex string, 36
characters long. This is a unique identifier for this node across all time, even if
the node name or address changes.
The `Meta` block was added in Consul 0.7.3 to enable associating arbitrary metadata
key/value pairs with a node for filtering purposes. For more information on node metadata,
see the [node meta](/docs/agent/options.html#_node_meta) section of the configuration page.
If the `Service` key is provided, the service will also be registered. If
`ID` is not provided, it will be defaulted to the value of the `Service.Service` property.
Only one service with a given `ID` may be present per node. The service `Tags`, `Address`,
and `Port` fields are all optional.
If the `Check` key is provided, a health check will also be registered. The register API manipulates the health check entry in the Catalog, but it does not setup
the script, TTL, or HTTP check to monitor the node's health. To truly enable a new
health check, the check must either be provided in agent configuration or set via
the [agent endpoint](agent.html).
The `CheckID` can be omitted and will default to the value of `Name`. As with `Service.ID`,
the `CheckID` must be unique on this node. `Notes` is an opaque field that is meant to
hold human-readable text. If a `ServiceID` is provided that matches the `ID`
of a service on that node, the check is treated as a service level health
check, instead of a node level health check. The `Status` must be one of `passing`, `warning`, or `critical`.
Multiple checks can be provided by replacing `Check` with `Checks` and sending
an array of `Check` objects.
It is important to note that `Check` does not have to be provided with `Service`
and vice versa. A catalog entry can have either, neither, or both.
The endpoint supports the use of ACL tokens using the ?token= query parameter
or the `X-Consul-Token` request header.
If the API call succeeds, a 200 status code is returned.
### <a name="catalog_deregister"></a> /v1/catalog/deregister
The deregister endpoint is a low-level mechanism for directly removing
entries from the Catalog. It is usually preferable to instead use the
[agent endpoints](agent.html) for deregistration as they are simpler and perform
[anti-entropy](/docs/internals/anti-entropy.html).
The deregister endpoint expects a JSON request body to be `PUT`. The request
body must look like one of the following:
```javascript
{
"Datacenter": "dc1",
"Node": "foobar",
}
```
```javascript
{
"Datacenter": "dc1",
"Node": "foobar",
"CheckID": "service:redis1"
}
```
```javascript
{
"Datacenter": "dc1",
"Node": "foobar",
"ServiceID": "redis1",
}
```
The behavior of the endpoint depends on what keys are provided. The endpoint
requires `Node` to be provided while `Datacenter` will be defaulted
to match that of the agent. If only `Node` is provided, the node and
all associated services and checks are deleted. If `CheckID` is provided, only
that check is removed. If `ServiceID` is provided, the
service and its associated health check (if any) are removed.
The endpoint supports the use of ACL tokens using the ?token= query parameter
or the `X-Consul-Token` request header.
If the API call succeeds a 200 status code is returned.
### <a name="catalog_datacenters"></a> /v1/catalog/datacenters
This endpoint is hit with a `GET` and is used to return all the
datacenters that are known by the Consul server.
The datacenters will be sorted in ascending order based on the
estimated median round trip time from the server to the servers
in that datacenter.
It returns a JSON body like this:
```javascript
["dc1", "dc2"]
```
This endpoint does not require a cluster leader and
will succeed even during an availability outage. Therefore, it can be
used as a simple check to see if any Consul servers are routable.
### <a name="catalog_nodes"></a> /v1/catalog/nodes
This endpoint is hit with a `GET` and returns the nodes registered
in a given DC. By default, the datacenter of the agent is queried;
however, the `dc` can be provided using the `?dc=` query parameter.
Adding the optional `?near=` parameter with a node name will sort
the node list in ascending order based on the estimated round trip
time from that node. Passing `?near=_agent` will use the agent's
node for the sort.
In Consul 0.7.3 and later, the optional `?node-meta=` parameter can be
provided with a desired node metadata key/value pair of the form `key:value`.
This parameter can be specified multiple times, and will filter the results to
nodes with the specified key/value pair(s).
It returns a JSON body like this:
```javascript
[
{
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "baz",
"Address": "10.1.10.11",
"TaggedAddresses": {
"lan": "10.1.10.11",
"wan": "10.1.10.11"
},
"Meta": {
"instance_type": "t2.medium"
}
},
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"Node": "foobar",
"Address": "10.1.10.12",
"TaggedAddresses": {
"lan": "10.1.10.11",
"wan": "10.1.10.12"
},
"Meta": {
"instance_type": "t2.large"
}
}
]
```
This endpoint supports blocking queries and all consistency modes.
The endpoint supports the use of ACL tokens using the ?token= query parameter
or the `X-Consul-Token` request header.
### <a name="catalog_services"></a> /v1/catalog/services
This endpoint is hit with a `GET` and returns the services registered
in a given DC. By default, the datacenter of the agent is queried;
however, the `dc` can be provided using the `?dc=` query parameter.
In Consul 0.7.3 and later, the optional `?node-meta=` parameter can be
provided with a desired node metadata key/value pair of the form `key:value`.
This parameter can be specified multiple times, and will filter the results to
services on nodes with the specified key/value pair(s).
It returns a JSON body like this:
```javascript
{
"consul": [],
"redis": [],
"postgresql": [
"primary",
"secondary"
]
}
```
The keys are the service names, and the array values provide all known
tags for a given service.
This endpoint supports blocking queries and all consistency modes.
The endpoint supports the use of ACL tokens using the ?token= query parameter
or the `X-Consul-Token` request header.
### <a name="catalog_service"></a> /v1/catalog/service/\<service\>
This endpoint is hit with a `GET` and returns the nodes providing a service
in a given DC. By default, the datacenter of the agent is queried;
however, the `dc` can be provided using the `?dc=` query parameter.
The service being queried must be provided on the path. By default
all nodes in that service are returned. However, the list can be filtered
by tag using the `?tag=` query parameter.
Adding the optional `?near=` parameter with a node name will sort
the node list in ascending order based on the estimated round trip
time from that node. Passing `?near=_agent` will use the agent's
node for the sort.
In Consul 0.7.3 and later, the optional `?node-meta=` parameter can be
provided with a desired node metadata key/value pair of the form `key:value`.
This parameter can be specified multiple times, and will filter the results to
service entries on nodes with the specified key/value pair(s).
It returns a JSON body like this:
```javascript
[
{
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Address": "192.168.10.10",
"TaggedAddresses": {
"lan": "192.168.10.10",
"wan": "10.0.10.10"
},
"Meta": {
"instance_type": "t2.medium"
}
"CreateIndex": 51,
"ModifyIndex": 51,
"ServiceAddress": "172.17.0.3",
"ServiceEnableTagOverride": false,
"ServiceID": "32a2a47f7992:nodea:5000",
"ServiceName": "foobar",
"ServicePort": 5000,
"ServiceTags": [
"tacos"
]
}
]
```
The returned fields are as follows:
- `Address`: IP address of the Consul node on which the service is registered
- `TaggedAddresses`: List of explicit LAN and WAN IP addresses for the agent
- `Meta`: Added in Consul 0.7.3, a list of user-defined metadata key/value pairs for the node
- `CreateIndex`: Internal index value representing when the service was created
- `ModifyIndex`: Last index that modified the service
- `Node`: Node name of the Consul node on which the service is registered
- `ServiceAddress`: IP address of the service host — if empty, node address should be used
- `ServiceEnableTagOverride`: Whether service tags can be overridden on this service
- `ServiceID`: A unique service instance identifier
- `ServiceName`: Name of the service
- `ServicePort`: Port number of the service
- `ServiceTags`: List of tags for the service
This endpoint supports blocking queries and all consistency modes.
The endpoint supports the use of ACL tokens using the ?token= query parameter
or the `X-Consul-Token` request header.
### <a name="catalog_node"></a> /v1/catalog/node/\<node\>
This endpoint is hit with a `GET` and returns the node's registered services.
By default, the datacenter of the agent is queried;
however, the `dc` can be provided using the `?dc=` query parameter.
The node being queried must be provided on the path.
It returns a JSON body like this:
```javascript
{
"Node": {
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Address": "10.1.10.12",
"TaggedAddresses": {
"lan": "10.1.10.12",
"wan": "10.1.10.12"
},
"Meta": {
"instance_type": "t2.medium"
}
},
"Services": {
"consul": {
"ID": "consul",
"Service": "consul",
"Tags": null,
"Port": 8300
},
"redis": {
"ID": "redis",
"Service": "redis",
"Tags": [
"v1"
],
"Port": 8000
}
}
}
```
This endpoint supports blocking queries and all consistency modes.
The endpoint supports the use of ACL tokens using the ?token= query parameter
or the `X-Consul-Token` request header.

83
website/source/docs/agent/http/coordinate.html.markdown
View File

@ -1,83 +0,0 @@
---
layout: "docs"
page_title: "Coordinate (HTTP)"
sidebar_current: "docs-agent-http-coordinate"
description: >
The Coordinate endpoint is used to query for the network coordinates for
nodes in the local datacenter as well as Consul servers in the local
datacenter and remote datacenters.
---
# Coordinate HTTP Endpoint
The Coordinate endpoint is used to query for the network coordinates for nodes
in the local datacenter as well as Consul servers in the local datacenter and
remote datacenters.
See the [Network Coordinates](/docs/internals/coordinates.html) internals guide
for more information on how these coordinates are computed, and for details on
how to perform calculations with them.
The following endpoints are supported:
* [`/v1/coordinate/datacenters`](#coordinate_datacenters) : Queries for WAN coordinates of Consul servers
* [`/v1/coordinate/nodes`](#coordinate_nodes) : Queries for LAN coordinates of Consul nodes
### <a name="coordinate_datacenters"></a> /v1/coordinate/datacenters
This endpoint is hit with a `GET` and returns the WAN network coordinates for
all Consul servers, organized by DCs.
It returns a JSON body like this:
```javascript
[
{
"Datacenter": "dc1",
"AreaID": "WAN",
"Coordinates": [
{
"Node": "agent-one",
"Coord": {
"Adjustment": 0,
"Error": 1.5,
"Height": 0,
"Vec": [0,0,0,0,0,0,0,0]
}
}
]
}
]
```
This endpoint serves data out of the server's local Serf data, so its results may
vary as requests are handled by different servers in the cluster. In Consul
Enterprise, this will include coordinates for user-added network areas as well,
as indicated by the `AreaID`. Coordinates are only compatible within the same
area.
This endpoint does not support blocking queries or any consistency modes.
### <a name=""coordinate_nodes></a> /v1/coordinate/nodes
This endpoint is hit with a `GET` and returns the LAN network coordinates for
all nodes in a given DC. By default, the datacenter of the agent is queried;
however, the `dc` can be provided using the `?dc=` query parameter.
It returns a JSON body like this:
```javascript
[
{
"Node": "agent-one",
"Coord": {
"Adjustment": 0,
"Error": 1.5,
"Height": 0,
"Vec": [0,0,0,0,0,0,0,0]
}
}
]
```
This endpoint supports blocking queries and all consistency modes.

103
website/source/docs/agent/http/event.html.markdown
View File

@ -1,103 +0,0 @@
---
layout: "docs"
page_title: "Events (HTTP)"
sidebar_current: "docs-agent-http-event"
description: >
The Event endpoints are used to fire new events and to query the
available events
---
# Event HTTP Endpoint
The Event endpoints are used to fire new events and to query the available
events.
The following endpoints are supported:
* [`/v1/event/fire/<name>`](#event_fire): Fires a new user event
* [`/v1/event/list`](#event_list): Lists the most recent events an agent has seen.
### <a name="event_fire"></a> /v1/event/fire/\<name\>
The fire endpoint is used to trigger a new user event. A user event
needs a `name`, provided on the path. The endpoint also supports several
optional parameters on the query string.
By default, the agent's local datacenter is used, but another datacenter
can be specified using the `?dc=` query parameter.
The fire endpoint expects a `PUT` request with an optional body.
The body contents are opaque to Consul and become the "payload"
of the event. Names starting with the `_` prefix should be considered
reserved for Consul's internal use.
The `?node=`, `?service=`, and `?tag=` query parameters may optionally
be provided. They respectively provide a regular expression to filter
by node name, service, and service tags.
The return code is 200 on success, along with a body like:
```javascript
{
"ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c",
"Name": "deploy",
"Payload": null,
"NodeFilter": "",
"ServiceFilter": "",
"TagFilter": "",
"Version": 1,
"LTime": 0
}
```
The `ID` field uniquely identifies the newly fired event.
### <a name="event_list"></a> /v1/event/list
This endpoint is hit with a `GET` and returns the most recent
events known by the agent. As a consequence of how the
[event command](/docs/commands/event.html) works, each agent
may have a different view of the events. Events are broadcast using
the [gossip protocol](/docs/internals/gossip.html), so
they have no global ordering nor do they make a promise of delivery.
Additionally, each node applies the `node`, `service` and `tag` filters
locally before storing the event. This means the events at each agent
may be different depending on their configuration.
This endpoint allows for filtering on events by name by providing
the `?name=` query parameter.
To support [watches](/docs/agent/watches.html), this endpoint supports
blocking queries. However, the semantics of this endpoint are slightly
different. Most blocking queries provide a monotonic index and block
until a newer index is available. This can be supported as a consequence
of the total ordering of the [consensus protocol](/docs/internals/consensus.html).
With gossip, there is no ordering, and instead `X-Consul-Index` maps
to the newest event that matches the query.
In practice, this means the index is only useful when used against a
single agent and has no meaning globally. Because Consul defines
the index as being opaque, clients should not be expecting a natural
ordering either.
Agents only buffer the most recent entries. The current buffer size is
256, but this value could change in the future.
It returns a JSON body like this:
```javascript
[
{
"ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c",
"Name": "deploy",
"Payload": "MTYwOTAzMA==",
"NodeFilter": "",
"ServiceFilter": "",
"TagFilter": "",
"Version": 1,
"LTime": 19
},
...
]
```

233
website/source/docs/agent/http/health.html.markdown
View File

@ -1,233 +0,0 @@
---
layout: "docs"
page_title: "Health Checks (HTTP)"
sidebar_current: "docs-agent-http-health"
description: >
The Health endpoints are used to query health-related information.
---
# Health HTTP Endpoint
The Health endpoints are used to query health-related information. They are provided separately
from the Catalog since users may prefer not to use the optional health checking mechanisms.
Additionally, some of the query results from the Health endpoints are filtered while the Catalog
endpoints provide the raw entries.
The following endpoints are supported:
* [`/v1/health/node/<node>`](#health_node): Returns the health info of a node
* [`/v1/health/checks/<service>`](#health_checks): Returns the checks of a service
* [`/v1/health/service/<service>`](#health_service): Returns the nodes and health info of a service
* [`/v1/health/state/<state>`](#health_state): Returns the checks in a given state
All of the health endpoints support blocking queries and all consistency modes.
### <a name="health_node"></a> /v1/health/node/\<node\>
This endpoint is hit with a `GET` and returns the checks specific to the node
provided on the path. By default, the datacenter of the agent is queried;
however, the `dc` can be provided using the `?dc=` query parameter.
It returns a JSON body like this:
```javascript
[
{
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"CheckID": "serfHealth",
"Name": "Serf Health Status",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "",
"ServiceName": ""
},
{
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
}
]
```
In this case, we can see there is a system level check (that is, a check with
no associated `ServiceID`) as well as a service check for Redis. The `serfHealth` check
is special in that it is automatically present on every node. When a node
joins the Consul cluster, it is part of a distributed failure detection
provided by Serf. If a node fails, it is detected and the status is automatically
changed to `critical`.
This endpoint supports blocking queries and all consistency modes.
### <a name="health_checks"></a> /v1/health/checks/\<service\>
This endpoint is hit with a `GET` and returns the checks associated with
the service provided on the path. By default, the datacenter of the agent is queried;
however, the `dc` can be provided using the `?dc=` query parameter.
Adding the optional `?near=` parameter with a node name will sort
the node list in ascending order based on the estimated round trip
time from that node. Passing `?near=_agent` will use the agent's
node for the sort.
In Consul 0.7.3 and later, the optional `?node-meta=` parameter can be
provided with a desired node metadata key/value pair of the form `key:value`.
This parameter can be specified multiple times, and will filter the results to
health checks on nodes with the specified key/value pair(s).
It returns a JSON body like this:
```javascript
[
{
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
}
]
```
This endpoint supports blocking queries and all consistency modes.
### <a name="health_service"></a> /v1/health/service/\<service\>
This endpoint is hit with a `GET` and returns the nodes providing
the service indicated on the path. By default, the datacenter of the agent is queried;
however, the `dc` can be provided using the `?dc=` query parameter.
Adding the optional `?near=` parameter with a node name will sort
the node list in ascending order based on the estimated round trip
time from that node. Passing `?near=_agent` will use the agent's
node for the sort.
By default, all nodes matching the service are returned. The list can be filtered
by tag using the `?tag=` query parameter.
Providing the `?passing` query parameter, added in Consul 0.2, will
filter results to only nodes with all checks in the `passing` state.
This can be used to avoid extra filtering logic on the client side.
In Consul 0.7.3 and later, the optional `?node-meta=` parameter can be
provided with a desired node metadata key/value pair of the form `key:value`.
This parameter can be specified multiple times, and will filter the results to
nodes with the specified key/value pair(s).
This endpoint is very similar to the `/v1/catalog/service` endpoint; however, this
endpoint automatically returns the status of the associated health check
as well as any system level health checks. This allows a client to avoid
sending traffic to nodes that are failing health tests or reporting warnings.
Users can also build in support for dynamic load balancing and other features
by incorporating the use of health checks.
It returns a JSON body like this:
```javascript
[
{
"Node": {
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Address": "10.1.10.12",
"TaggedAddresses": {
"lan": "10.1.10.12",
"wan": "10.1.10.12"
},
"Meta": {
"instance_type": "t2.medium"
}
},
"Service": {
"ID": "redis",
"Service": "redis",
"Tags": null,
"Address": "10.1.10.12",
"Port": 8000
},
"Checks": [
{
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
},
{
"Node": "foobar",
"CheckID": "serfHealth",
"Name": "Serf Health Status",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "",
"ServiceName": ""
}
]
}
]
```
This endpoint supports blocking queries and all consistency modes.
### <a name="health_state"></a> /v1/health/state/\<state\>
This endpoint is hit with a `GET` and returns the checks in the
state provided on the path. By default, the datacenter of the agent is queried;
however, the `dc` can be provided using the `?dc=` query parameter.
Adding the optional `?near=` parameter with a node name will sort
the node list in ascending order based on the estimated round trip
time from that node. Passing `?near=_agent` will use the agent's
node for the sort.
In Consul 0.7.3 and later, the optional `?node-meta=` parameter can be
provided with a desired node metadata key/value pair of the form `key:value`.
This parameter can be specified multiple times, and will filter the results to
health checks on nodes with the specified key/value pair(s).
The supported states are `any`, `passing`, `warning`, or `critical`.
The `any` state is a wildcard that can be used to return all checks.
It returns a JSON body like this:
```javascript
[
{
"Node": "foobar",
"CheckID": "serfHealth",
"Name": "Serf Health Status",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "",
"ServiceName": ""
},
{
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
}
]
```
This endpoint supports blocking queries and all consistency modes.

378
website/source/docs/agent/http/kv.html.markdown
View File

@ -1,378 +0,0 @@
---
layout: "docs"
page_title: "Key/Value Store (HTTP)"
sidebar_current: "docs-agent-http-kv"
description: >
The KV endpoints are used to access Consul's simple key/value store, useful for storing
service configuration or other metadata.
---
# Key/Value Store Endpoints
The KV endpoints are used to access Consul's simple key/value store, useful for storing
service configuration or other metadata.
The following endpoints are supported:
* [`/v1/kv/<key>`](#single): Manages updates of individual keys, deletes of individual
keys or key prefixes, and fetches of individual keys or key prefixes
* [`/v1/txn`](#txn): Manages updates or fetches of multiple keys inside a single,
atomic transaction
### <a name="single"></a> /v1/kv/&lt;key&gt;
This endpoint manages updates of individual keys, deletes of individual keys or key
prefixes, and fetches of individual keys or key prefixes. The `GET`, `PUT` and
`DELETE` methods are all supported.
By default, the datacenter of the agent is queried; however, the `dc` can be provided
using the `?dc=` query parameter. It is important to note that each datacenter has
its own KV store, and there is no built-in replication between datacenters. If you
are interested in replication between datacenters, look at the
[Consul Replicate project](https://github.com/hashicorp/consul-replicate).
The KV endpoint supports the use of ACL tokens using the `?token=` query parameter.
#### GET Method
When using the `GET` method, Consul will return the specified key.
If the `?recurse` query parameter is provided, it will return
all keys with the given prefix.
This endpoint supports blocking queries and all consistency modes.
Each object will look like:
```javascript
[
{
"CreateIndex": 100,
"ModifyIndex": 200,
"LockIndex": 200,
"Key": "zip",
"Flags": 0,
"Value": "dGVzdA==",
"Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
]
```
`CreateIndex` is the internal index value that represents
when the entry was created.
`ModifyIndex` is the last index that modified this key. This index corresponds
to the `X-Consul-Index` header value that is returned in responses, and it can
be used to establish blocking queries by setting the `?index` query parameter.
You can even perform blocking queries against entire subtrees of the KV store:
if `?recurse` is provided, the returned `X-Consul-Index` corresponds
to the latest `ModifyIndex` within the prefix, and a blocking query using that
`?index` will wait until any key within that prefix is updated.
`LockIndex` is the number of times this key has successfully been acquired in
a lock. If the lock is held, the `Session` key provides the session that owns
the lock.
`Key` is simply the full path of the entry.
`Flags` is an opaque unsigned integer that can be attached to each entry. Clients
can choose to use this however makes sense for their application.
`Value` is a Base64-encoded blob of data.
-> **Note:** Values cannot be larger than 512kB.
It is possible to list just keys without their values by using the `?keys` query
parameter. This will return a list of the keys under the given prefix. The optional
`?separator=` can be used to list only up to a given separator.
For example, listing `/web/` with a `/` separator may return:
```javascript
[
"/web/bar",
"/web/foo",
"/web/subdir/"
]
```
Using the key listing method may be suitable when you do not need
the values or flags or want to implement a key-space explorer.
If the `?raw` query parameter is used with a non-recursive `GET`,
the response is just the raw value of the key, without any
encoding.
If no entries are found, a 404 code is returned.
#### PUT method
When using the `PUT` method, Consul expects the request body to be the
value corresponding to the key. There are a number of query parameters that can
be used with a `PUT` request:
* `?flags=<num>` : This can be used to specify an unsigned value between
`0` and `(2^64)-1`. Clients can choose to use this however makes sense for their application.
* `?cas=<index>` : This flag is used to turn the `PUT` into a Check-And-Set
operation. This is very useful as a building block for more complex
synchronization primitives. If the index is 0, Consul will only
put the key if it does not already exist. If the index is non-zero,
the key is only set if the index matches the `ModifyIndex` of that key.
* `?acquire=<session>` : This flag is used to turn the `PUT` into a lock acquisition
operation. This is useful as it allows leader election to be built on top
of Consul. If the lock is not held and the session is valid, this increments
the `LockIndex` and sets the `Session` value of the key in addition to updating
the key contents. A key does not need to exist to be acquired. If the lock is
already held by the given session, then the `LockIndex` is not incremented but
the key contents are updated. This lets the current lock holder update the key
contents without having to give up the lock and reacquire it.
* `?release=<session>` : This flag is used to turn the `PUT` into a lock release
operation. This is useful when paired with `?acquire=` as it allows clients to
yield a lock. This will leave the `LockIndex` unmodified but will clear the associated
`Session` of the key. The key must be held by this session to be unlocked.
The return value is either `true` or `false`. If `false` is returned,
the update has not taken place.
#### DELETE method
The `DELETE` method can be used to delete a single key or all keys sharing
a prefix. There are a few query parameters that can be used with a
`DELETE` request:
* `?recurse` : This is used to delete all keys which have the specified prefix.
Without this, only a key with an exact match will be deleted.
* `?cas=<index>` : This flag is used to turn the `DELETE` into a Check-And-Set
operation. This is very useful as a building block for more complex
synchronization primitives. Unlike `PUT`, the index must be greater than 0
for Consul to take any action: a 0 index will not delete the key. If the index
is non-zero, the key is only deleted if the index matches the `ModifyIndex` of that key.
### <a name="txn"></a> /v1/txn
Available in Consul 0.7 and later, this endpoint manages updates or fetches of
multiple keys inside a single, atomic transaction. Only the `PUT` method is supported.
By default, the datacenter of the agent receives the transaction; however, the `dc`
can be provided using the `?dc=` query parameter. It is important to note that each
datacenter has its own KV store, and there is no built-in replication between
datacenters. If you are interested in replication between datacenters, look at the
[Consul Replicate project](https://github.com/hashicorp/consul-replicate).
The transaction endpoint supports the use of ACL tokens using the `?token=` query
parameter.
#### PUT Method
The `PUT` method lets you submit a list of operations to apply to the key/value store
inside a transaction. If any operation fails, the transaction will be rolled back and
none of the changes will be applied.
If the transaction doesn't contain any write operations then it will be
fast-pathed internally to an endpoint that works like other reads,
except that blocking queries are not currently supported. In this mode,
you may supply the `?stale` or `?consistent` query parameters with the
request to control consistency. To support bounding the acceptable
staleness of data, read-only transaction responses provide the
`X-Consul-LastContact` header containing the time in milliseconds that a
server was last contacted by the leader node. The
`X-Consul-KnownLeader` header also indicates if there is a known leader.
These won't be present if the transaction contains any write operations,
and any consistency query parameters will be ignored, since writes are
always managed by the leader via the Raft consensus protocol.
The body of the request should be a list of operations to perform inside the atomic
transaction. Up to 64 operations may be present in a single transaction. Operations
look like this:
```javascript
[
{
"KV": {
"Verb": "<verb>",
"Key": "<key>",
"Value": "<Base64-encoded blob of data>",
"Flags": <flags>,
"Index": <index>,
"Session": "<session id>"
}
},
...
]
```
`KV` is the only available operation type, though other types of operations may be added
in future versions of Consul to be mixed with key/value operations. The following fields
are available:
* `Verb` is the type of operation to perform. Please see the table below for
available verbs.
* `Key` is simply the full path of the entry.
* `Value` is a Base64-encoded blob of data. Values cannot be larger than
512kB.
* `Flags` is an opaque unsigned integer that can be attached to each entry. Clients
can choose to use this however makes sense for their application.
* `Index` and `Session` are used for locking, unlocking, and check-and-set operations.
Please see the table below for details on how they are used.
The following table summarizes the available verbs and the fields that apply to that
operation ("X" means a field is required and "O" means it is optional):
<table class="table table-bordered table-striped">
<tr>
<th>Verb</th>
<th>Operation</th>
<th>Key</th>
<th>Value</th>
<th>Flags</th>
<th>Index</th>
<th>Session</th>
</tr>
<tr>
<td>set</td>
<td>Sets the `Key` to the given `Value`.</td>
<td align="center">X</td>
<td align="center">X</td>
<td align="center">O</td>
<td align="center"></td>
<td align="center"></td>
</tr>
<tr>
<td>cas</td>
<td>Sets the `Key` to the given `Value` with check-and-set semantics. The `Key` will only be set if its current modify index matches the supplied `Index`.</td>
<td align="center">X</td>
<td align="center">X</td>
<td align="center">O</td>
<td align="center">X</td>
<td align="center"></td>
</tr>
<tr>
<td>lock</td>
<td>Locks the `Key` with the given `Session`. The `Key` will only obtain the lock if the `Session` is valid, and no other session has it locked.</td>
<td align="center">X</td>
<td align="center">X</td>
<td align="center">O</td>
<td align="center"></td>
<td align="center">X</td>
</tr>
<tr>
<td>unlock</td>
<td>Unlocks the `Key` with the given `Session`. The `Key` will only release the lock if the `Session` is valid and currently has it locked.</td>
<td align="center">X</td>
<td align="center">X</td>
<td align="center">O</td>
<td align="center"></td>
<td align="center">X</td>
</tr>
<tr>
<td>get</td>
<td>Gets the `Key` during the transaction. This fails the transaction if the `Key` doesn't exist. The key may not be present in the results if ACLs do not permit it to be read.</td>
<td align="center">X</td>
<td align="center"></td>
<td align="center"></td>
<td align="center"></td>
<td align="center"></td>
</tr>
<tr>
<td>get-tree</td>
<td>Gets all keys with a prefix of `Key` during the transaction. This does not fail the transaction if the `Key` doesn't exist. Not all keys may be present in the results if ACLs do not permit them to be read.</td>
<td align="center">X</td>
<td align="center"></td>
<td align="center"></td>
<td align="center"></td>
<td align="center"></td>
</tr>
<tr>
<td>check-index</td>
<td>Fails the transaction if `Key` does not have a modify index equal to `Index`.</td>
<td align="center">X</td>
<td align="center"></td>
<td align="center"></td>
<td align="center">X</td>
<td align="center"></td>
</tr>
<tr>
<td>check-session</td>
<td>Fails the transaction if `Key` is not currently locked by `Session`.</td>
<td align="center">X</td>
<td align="center"></td>
<td align="center"></td>
<td align="center"></td>
<td align="center">X</td>
</tr>
<tr>
<td>delete</td>
<td>Deletes the `Key`.</td>
<td align="center">X</td>
<td align="center"></td>
<td align="center"></td>
<td align="center"></td>
<td align="center"></td>
</tr>
<tr>
<td>delete-tree</td>
<td>Deletes all keys with a prefix of`Key`.</td>
<td align="center">X</td>
<td align="center"></td>
<td align="center"></td>
<td align="center"></td>
<td align="center"></td>
</tr>
<tr>
<td>delete-cas</td>
<td>Deletes the `Key` with check-and-set semantics. The `Key` will only be deleted if its current modify index matches the supplied `Index`.</td>
<td align="center">X</td>
<td align="center"></td>
<td align="center"></td>
<td align="center">X</td>
<td align="center"></td>
</tr>
</table>
If the transaction can be processed, a status code of 200 will be returned if it
was successfully applied, or a status code of 409 will be returned if it was rolled
back. If either of these status codes are returned, the response will look like this:
```javascript
{
"Results": [
{
"KV": {
"LockIndex": <lock index>,
"Key": "<key>",
"Flags": <flags>,
"Value": "<Base64-encoded blob of data, or null>",
"CreateIndex": <index>,
"ModifyIndex": <index>
}
},
...
],
"Errors": [
{
"OpIndex": <index of failed operation>,
"What": "<error message for failed operation>"
},
...
]
}
```
`Results` has entries for some operations if the transaction was successful. To save
space, the `Value` will be `null` for any `Verb` other than "get" or "get-tree". Like
the `/v1/kv/<key>` endpoint, `Value` will be Base64-encoded if it is present. Also,
no result entries will be added for verbs that delete keys.
`Errors` has entries describing which operations failed if the transaction was rolled
back. The `OpIndex` gives the index of the failed operation in the transaction, and
`What` is a string with an error message about why that operation failed.
If any other status code is returned, such as 400 or 500, then the body of the response
will simply be an unstructured error message about what happened.

701
website/source/docs/agent/http/operator.html.markdown
View File

@ -1,701 +0,0 @@
---
layout: "docs"
page_title: "Operator (HTTP)"
sidebar_current: "docs-agent-http-operator"
description: >
The operator endpoint provides cluster-level tools for Consul operators.
---
# Operator HTTP Endpoint
The Operator endpoint provides cluster-level tools for Consul operators, such
as interacting with the Raft subsystem. This was added in Consul 0.7.
~> Use this interface with extreme caution, as improper use could lead to a Consul
outage and even loss of data.
If ACLs are enabled then a token with operator privileges may be required in
order to use this interface. See the [ACL](/docs/internals/acl.html#operator)
internals guide for more information.
See the [Outage Recovery](/docs/guides/outage.html) guide for some examples of how
these capabilities are used. For a CLI to perform these operations manually, please
see the documentation for the [`consul operator`](/docs/commands/operator.html)
command.
The following types of endpoints are supported:
* [Autopilot](#autopilot): Automatically manage Consul servers
* [Keyring](#keyring): Manage gossip encryption keyring
* [Network Areas](#network-areas): Manage network areas (Enterprise-only)
* [Raft](#raft): Manage Raft consensus subsystem
Not all endpoints support blocking queries and all consistency modes,
see details in the sections below.
The operator endpoints support the use of ACL Tokens. See the
[ACL](/docs/internals/acl.html#operator) internals guide for more information.
## Autopilot
Autopilot is a set of new features added in Consul 0.8 to allow for automatic
operator-friendly management of Consul servers. Please see the
[Autopilot Guide](/docs/guides/autopilot.html) for more details.
The following endpoints are supported:
* [`/v1/operator/autopilot/configuration`](#autopilot-configuration): Read or update Autopilot configuration
* [`/v1/operator/autopilot/health`](#autopilot-health): Read server health as determined by Autopilot
### <a name="autopilot-configuration"></a> /v1/operator/autopilot/configuration
Available in Consul 0.8.0 and later, the autopilot configuration endpoint supports the
`GET` and `PUT` methods.
This endpoint supports the use of ACL tokens using either the `X-CONSUL-TOKEN`
header or the `?token=` query parameter.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
#### GET Method
When using the `GET` method, the request will be forwarded to the cluster
leader to retrieve its latest Autopilot configuration.
If the cluster doesn't currently have a leader an error will be returned. You
can use the `?stale` query parameter to read the Raft configuration from any
of the Consul servers.
If ACLs are enabled, the client will need to supply an ACL Token with
[`operator`](/docs/internals/acl.html#operator) read privileges.
A JSON body is returned that looks like this:
```javascript
{
"CleanupDeadServers": true,
"LastContactThreshold": "200ms",
"MaxTrailingLogs": 250,
"ServerStabilizationTime": "10s",
"RedundancyZoneTag": "",
"DisableUpgradeMigration": false,
"CreateIndex": 4,
"ModifyIndex": 4
}
```
For more information about the Autopilot configuration options, see the agent configuration section
[here](/docs/agent/options.html#autopilot).
#### PUT Method
Using the `PUT` method, this endpoint will update the Autopilot configuration
of the cluster.
The `?cas=<index>` can optionally be specified to update the configuration as a
Check-And-Set operation. The update will only happen if the given index matches
the `ModifyIndex` of the configuration at the time of writing.
If ACLs are enabled, the client will need to supply an ACL Token with
[`operator`](/docs/internals/acl.html#operator) write privileges.
The `PUT` method expects a JSON request body to be submitted. The request
body must look like:
```javascript
{
"CleanupDeadServers": true,
"LastContactThreshold": "200ms",
"MaxTrailingLogs": 250,
"ServerStabilizationTime": "10s",
"RedundancyZoneTag": "",
"DisableUpgradeMigration": false,
"CreateIndex": 4,
"ModifyIndex": 4
}
```
For more information about the Autopilot configuration options, see the agent configuration section
[here](/docs/agent/options.html#autopilot).
The return code will indicate success or failure.
### <a name="autopilot-health"></a> /v1/operator/autopilot/health
Available in Consul 0.8.0 and later, the autopilot health endpoint supports the
`GET` method.
This endpoint supports the use of ACL tokens using either the `X-CONSUL-TOKEN`
header or the `?token=` query parameter.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
#### GET Method
When using the `GET` method, the request will be forwarded to the cluster
leader to retrieve its latest Autopilot configuration.
If ACLs are enabled, the client will need to supply an ACL Token with
[`operator`](/docs/internals/acl.html#operator) read privileges.
A JSON body is returned that looks like this:
```javascript
{
"Healthy": true,
"FailureTolerance": 0,
"Servers": [
{
"ID": "e349749b-3303-3ddf-959c-b5885a0e1f6e",
"Name": "node1",
"Address": "127.0.0.1:8300",
"SerfStatus": "alive",
"Version": "0.7.4",
"Leader": true,
"LastContact": "0s",
"LastTerm": 2,
"LastIndex": 46,
"Healthy": true,
"Voter": true,
"StableSince": "2017-03-06T22:07:51Z"
},
{
"ID": "e36ee410-cc3c-0a0c-c724-63817ab30303",
"Name": "node2",
"Address": "127.0.0.1:8205",
"SerfStatus": "alive",
"Version": "0.7.4",
"Leader": false,
"LastContact": "27.291304ms",
"LastTerm": 2,
"LastIndex": 46,
"Healthy": true,
"Voter": false,
"StableSince": "2017-03-06T22:18:26Z"
}
]
}
```
`Healthy` is whether all the servers are currently heathly.
`FailureTolerance` is the number of redundant healthy servers that could be fail
without causing an outage (this would be 2 in a healthy cluster of 5 servers).
The `Servers` list holds detailed health information on each server:
- `ID` is the Raft ID of the server.
- `Name` is the node name of the server.
- `Address` is the address of the server.
- `SerfStatus` is the SerfHealth check status for the server.
- `Version` is the Consul version of the server.
- `Leader` is whether this server is currently the leader.
- `LastContact` is the time elapsed since this server's last contact with the leader.
- `LastTerm` is the server's last known Raft leader term.
- `LastIndex` is the index of the server's last committed Raft log entry.
- `Healthy` is whether the server is healthy according to the current Autopilot configuration.
- `Voter` is whether the server is a voting member of the Raft cluster.
- `StableSince` is the time this server has been in its current `Healthy` state.
## Keyring
The keyring endpoint allows management of the gossip encryption keyring. See
the [Gossip Protocol Guide](/docs/internals/gossip.html) for more details on the
gossip protocol and its use.
The following endpoint is supported:
* [`/v1/operator/keyring`](#keyring-endpoint): Operate on the gossip keyring
### <a name="keyring-endpoint"></a> /v1/operator/keyring
Available in Consul 0.7.2 and later, the keyring endpoint supports the
`GET`, `POST`, `PUT` and `DELETE` methods.
This endpoint supports the use of ACL tokens using either the `X-CONSUL-TOKEN`
header or the `?token=` query parameter.
Added in Consul 0.7.4, this endpoint supports the `?relay-factor=` query parameter.
See the [Keyring Command](/docs/commands/keyring.html#_relay_factor) for more details.
#### GET Method
Using the `GET` method, this endpoint will list the gossip encryption keys
installed on both the WAN and LAN rings of every known datacenter. There is more
information on gossip encryption available
[here](/docs/agent/encryption.html#gossip-encryption).
If ACLs are enabled, the client will need to supply an ACL Token with
[`keyring`](/docs/internals/acl.html#keyring) read privileges.
A JSON body is returned that looks like this:
```javascript
[
{
"WAN": true,
"Datacenter": "dc1",
"Keys": {
"0eK8RjnsGC/+I1fJErQsBA==": 1,
"G/3/L4yOw3e5T7NTvuRi9g==": 1,
"z90lFx3sZZLtTOkutXcwYg==": 1
},
"NumNodes": 1
},
{
"WAN": false,
"Datacenter": "dc1",
"Keys": {
"0eK8RjnsGC/+I1fJErQsBA==": 1,
"G/3/L4yOw3e5T7NTvuRi9g==": 1,
"z90lFx3sZZLtTOkutXcwYg==": 1
},
"NumNodes": 1
}
]
```
`WAN` is true if the block refers to the WAN ring of that datacenter (rather than
LAN).
`Datacenter` is the datacenter the block refers to.
`Keys` is a map of each gossip key to the number of nodes it's currently installed
on.
`NumNodes` is the total number of nodes in the datacenter.
#### POST Method
Using the `POST` method, this endpoint will install a new gossip encryption key
into the cluster. There is more information on gossip encryption available
[here](/docs/agent/encryption.html#gossip-encryption).
The `POST` method expects a JSON request body to be submitted. The request
body must look like:
```javascript
{
"Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
}
```
The `Key` field is mandatory and provides the encryption key to install into the
cluster.
If ACLs are enabled, the client will need to supply an ACL Token with
[`keyring`](/docs/internals/acl.html#keyring) write privileges.
The return code will indicate success or failure.
#### PUT Method
Using the `PUT` method, this endpoint will change the primary gossip encryption
key. The key must already be installed before this operation can succeed. There
is more information on gossip encryption available
[here](/docs/agent/encryption.html#gossip-encryption).
The `PUT` method expects a JSON request body to be submitted. The request
body must look like:
```javascript
{
"Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
}
```
The `Key` field is mandatory and provides the primary encryption key to begin
using.
If ACLs are enabled, the client will need to supply an ACL Token with
[`keyring`](/docs/internals/acl.html#keyring) write privileges.
The return code will indicate success or failure.
#### DELETE Method
Using the `DELETE` method, this endpoint will remove a gossip encryption key from
the cluster. This operation may only be performed on keys which are not currently
the primary key. There is more information on gossip encryption available
[here](/docs/agent/encryption.html#gossip-encryption).
The `DELETE` method expects a JSON request body to be submitted. The request
body must look like:
```javascript
{
"Key": "3lg9DxVfKNzI8O+IQ5Ek+Q=="
}
```
The `Key` field is mandatory and provides the encryption key to remove from the
cluster.
If ACLs are enabled, the client will need to supply an ACL Token with
[`keyring`](/docs/internals/acl.html#keyring) write privileges.
The return code will indicate success or failure.
## Network Areas
~> The network area functionality described here is available only in
[Consul Enterprise](https://www.hashicorp.com/consul.html) version 0.8.0 and later.
Consul Enterprise version supports network areas, which are operator-defined relationships
between servers in two different Consul datacenters.
Unlike Consul's WAN feature, network areas use just the server RPC port for communication,
and relationships can be made between independent pairs of datacenters, so not all servers
need to be fully connected. This allows for complex topologies among Consul datacenters like
hub/spoke and more general trees.
See the [Network Areas Guide](/docs/guides/areas.html) for more details.
The following endpoints are supported:
* [`/v1/operator/area`](#area-general): Create a new area or list areas
* [`/v1/operator/area/<id>`](#area-specific): Delete an area
* [`/v1/operator/area/<id>/join`](#area-join): Join Consul servers into an area
* [`/v1/operator/area/<id>/members`](#area-members): List Consul servers in an area
### <a name="area-general"></a> /v1/operator/area
The general network area endpoint supports the `POST` and `GET` methods.
#### POST Method
When using the `POST` method, Consul will create a new network area and return
its ID if it is created successfully.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
write privileges.
The create operation expects a JSON request body that defines the network area,
like this example:
```javascript
{
"PeerDatacenter": "dc2",
"RetryJoin": [ "10.1.2.3", "10.1.2.4", "10.1.2.5" ]
}
```
`PeerDatacenter` is required and is the name of the Consul datacenter that will
be joined the Consul servers in the current datacenter to form the area. Only
one area is allowed for each possible `PeerDatacenter`, and a datacenter cannot
form an area with itself.
`RetryJoin` is a list of Consul servers to attempt to join. Servers can be given
as `IP`, `IP:port`, `hostname`, or `hostname:port`. Consul will spawn a background
task that tries to periodically join the servers in this list and will run until a
join succeeds. If this list isn't supplied, joining can be done with a call to the
[join endpoint](#area-join) once the network area is created.
The return code is 200 on success and the ID of the created network area is returned
in a JSON body:
```javascript
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"
}
```
#### GET Method
When using the `GET` method, Consul will provide a listing of all network areas.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter. This endpoint supports blocking
queries and all consistency modes.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
read privileges.
This returns a JSON list of network areas, which looks like:
```javascript
[
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"PeerDatacenter": "dc2",
"RetryJoin": [ "10.1.2.3", "10.1.2.4", "10.1.2.5" ]
},
...
]
```
### <a name="area-specific"></a> /v1/operator/area/\<id\>
The specific network area endpoint supports the `GET` and `DELETE` methods.
#### GET Method
When using the `GET` method, Consul will provide a listing of a specific
network area.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter. This endpoint supports blocking
queries and all consistency modes.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
read privileges.
This returns a JSON list with a single network area, which looks like:
```javascript
[
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"PeerDatacenter": "dc2",
"RetryJoin": [ "10.1.2.3", "10.1.2.4", "10.1.2.5" ]
}
]
```
#### Delete Method
When using the `DELETE` method, Consul will delete a specific network area.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
write privileges.
### <a name="area-join"></a> /v1/operator/area/\<id\>/join
The network area join endpoint supports the `PUT` method.
#### PUT Method
When using the `PUT` method, Consul will attempt to join the given Consul servers
into a specific network area.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
write privileges.
The create operation expects a JSON request body with a list of Consul servers to
join, like this example:
```javascript
[ "10.1.2.3", "10.1.2.4", "10.1.2.5" ]
```
Servers can be given as `IP`, `IP:port`, `hostname`, or `hostname:port`.
The return code is 200 on success a JSON response will be returned with a summary
of the join results:
```javascript
[
{
"Address": "10.1.2.3",
"Joined": true,
"Error", ""
},
{
"Address": "10.1.2.4",
"Joined": true,
"Error", ""
},
{
"Address": "10.1.2.5",
"Joined": true,
"Error", ""
}
]
```
`Address` has the address requested to join.
`Joined` will be `true` if the Consul server at the given address was successfully
joined into the network area. Otherwise, this will be `false` and `Error` will have
a human-readable message about why the join didn't succeed.
### <a name="area-members"></a> /v1/operator/area/\<id\>/members
The network area members endpoint supports the `GET` method.
#### GET Method
When using the `GET` method, Consul will provide a listing of the Consul servers
present in a specific network area.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with `operator`
read privileges.
This returns a JSON list with details about the Consul servers present in the network
area, like this:
```javascript
[
{
"ID": "afc5d95c-1eee-4b46-b85b-0efe4c76dd48",
"Name": "node-2.dc1",
"Addr": "127.0.0.2",
"Port": 8300,
"Datacenter": "dc1",
"Role": "server",
"Build": "0.8.0",
"Protocol": 2,
"Status": "alive",
"RTT": 256478
},
...
]
```
`ID` is the node ID of the server.
`Name` is the node name of the server, with its datacenter appended.
`Addr` is the IP address of the node.
`Port` is the server RPC port of the node.
`Datacenter` is the node's Consul datacenter.
`Role` is always "server" since only Consul servers can participate in network
areas.
`Build` has the Consul version running on the node.
`Protocol` is the [protocol version](/docs/upgrading.html#protocol-versions) being
spoken by the node.
`Status` is the current health status of the node, as determined by the network
area distributed failure detector. This will be "alive", "leaving", "left", or
"failed". A "failed" status means that other servers are not able to probe this
server over its server RPC interface.
`RTT` is an estimated network round trip time from the server answering the query
to the given server, in nanoseconds. This is computed using
[network coordinates](/docs/internals/coordinates.html).
## Raft
The Raft endpoint provides tools for Management of Raft the consensus subsystem
and cluster quorum. See the [Consensus Protocol Guide](/docs/internals/consensus.html)
for more information about Raft consensus protocol and its use.
The following endpoints are supported:
* [`/v1/operator/raft/configuration`](#raft-configuration): Inspect the Raft configuration
* [`/v1/operator/raft/peer`](#raft-peer): Remove a server from the Raft configuration
### <a name="raft-configuration"></a> /v1/operator/raft/configuration
The Raft configuration endpoint supports the `GET` method.
#### GET Method
When using the `GET` method, the request will be forwarded to the cluster
leader to retrieve its latest Raft peer configuration.
If the cluster doesn't currently have a leader an error will be returned. You
can use the `?stale` query parameter to read the Raft configuration from any
of the Consul servers.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with
[`operator`](/docs/internals/acl.html#operator) read privileges.
A JSON body is returned that looks like this:
```javascript
{
"Servers": [
{
"ID": "127.0.0.1:8300",
"Node": "alice",
"Address": "127.0.0.1:8300",
"Leader": true,
"Voter": true
},
{
"ID": "127.0.0.2:8300",
"Node": "bob",
"Address": "127.0.0.2:8300",
"Leader": false,
"Voter": true
},
{
"ID": "127.0.0.3:8300",
"Node": "carol",
"Address": "127.0.0.3:8300",
"Leader": false,
"Voter": true
}
],
"Index": 22
}
```
The `Servers` array has information about the servers in the Raft peer
configuration:
`ID` is the ID of the server. This is the same as the `Address` in Consul 0.7
but may be upgraded to a GUID in a future version of Consul.
`Node` is the node name of the server, as known to Consul, or "(unknown)" if
the node is stale and not known.
`Address` is the IP:port for the server.
`Leader` is either "true" or "false" depending on the server's role in the
Raft configuration.
`Voter` is "true" or "false", indicating if the server has a vote in the Raft
configuration. Future versions of Consul may add support for non-voting servers.
The `Index` value is the Raft corresponding to this configuration. The latest configuration may not yet be committed if changes are in flight.
### <a name="raft-peer"></a> /v1/operator/raft/peer
The Raft peer endpoint supports the `DELETE` method.
#### DELETE Method
Using the `DELETE` method, this endpoint will remove the Consul server with
given address from the Raft configuration.
There are rare cases where a peer may be left behind in the Raft configuration
even though the server is no longer present and known to the cluster. This
endpoint can be used to remove the failed server so that it is no longer
affects the Raft quorum.
Either an `?id=` or `?address=` query parameter is required and should be set to the
peer ID or `IP:port` respectively for the server to remove. The port number is usually
8300, unless configured otherwise. Nothing is required in the body of the request.
By default, the datacenter of the agent is targeted; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with
[`operator`](/docs/internals/acl.html#operator) write privileges.
The return code will indicate success or failure.

518
website/source/docs/agent/http/query.html.markdown
View File

@ -1,518 +0,0 @@
---
layout: "docs"
page_title: "Prepared Queries (HTTP)"
sidebar_current: "docs-agent-http-query"
description: >
The Query endpoints are used to manage and execute prepared queries.
---
# Prepared Query HTTP Endpoint
The Prepared Query endpoints are used to create, update, destroy, and execute
prepared queries.
Prepared queries allow you to register a complex service query and then execute
it later via its ID or name to get a set of healthy nodes that provide a given
service. This is particularly useful in combination with Consul's
[DNS Interface](/docs/agent/dns.html) as it allows for much richer queries than
would be possible given the limited entry points exposed by DNS.
Consul 0.6.4 and later also supports prepared query templates. Templates are
defined in a similar way to regular prepared queries but instead of applying to
just a single query name, they can respond to names starting with a configured
prefix. The service name being queried is computed using the matched prefix
and/or a regular expression. This provides a powerful tool that lets you apply
the features of prepared queries to a range (or potentially all) services with a
small number of templates. Details about prepared query templates are covered
[below](#templates).
The following endpoints are supported:
* [`/v1/query`](#general): Creates a new prepared query or lists
all prepared queries
* [`/v1/query/<query>`](#specific): Updates, fetches, or deletes
a prepared query
* [`/v1/query/<query or name>/execute`](#execute): Executes a
prepared query by its ID or optional name
* [`/v1/query/<query or name>/explain`](#explain): Provides information about
how a prepared query will be executed by its ID or optional name
Not all endpoints support blocking queries and all consistency modes,
see details in the sections below.
The query endpoints support the use of ACL Tokens. Prepared queries have some
special handling of ACL Tokens that are called out where applicable with the
details of each endpoint.
See the [Prepared Query ACLs](/docs/internals/acl.html#prepared_query_acls)
internals guide for more details about how prepared query policies work.
### <a name="general"></a> /v1/query
The general query endpoint supports the `POST` and `GET` methods.
#### POST Method
When using the `POST` method, Consul will create a new prepared query and return
its ID if it is created successfully.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with `query`
write privileges for the `Name` of the query being created.
The create operation expects a JSON request body that defines the prepared
query, like this example:
```javascript
{
"Name": "my-query",
"Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Token": "",
"Service": {
"Service": "redis",
"Failover": {
"NearestN": 3,
"Datacenters": ["dc1", "dc2"]
},
"Near": "node1",
"OnlyPassing": false,
"Tags": ["primary", "!experimental"],
"NodeMeta": {"instance_type": "m3.large"}
},
"DNS": {
"TTL": "10s"
}
}
```
Only the `Service` field inside the `Service` structure is mandatory, all other
fields will take their default values if they are not included.
`Name` is an optional friendly name that can be used to execute a query instead
of using its ID.
`Session` provides a way to automatically remove a prepared query when the
given session is invalidated. This is optional, and if not given the prepared
query must be manually removed when no longer needed.
<a name="token"></a>
`Token`, if specified, is a captured ACL Token that is reused as the ACL Token
every time the query is executed. This allows queries to be executed by clients
with lesser or even no ACL Token, so this should be used with care. The token
itself can only be seen by clients with a management token. If the `Token`
field is left blank or omitted, the client's ACL Token will be used to determine
if they have access to the service being queried. If the client does not supply
an ACL Token, the anonymous token will be used.
Consul version 0.6.3 and earlier would automatically capture the ACL
Token for use in the future when prepared queries were executed and would
execute with the same privileges as the definer of the prepared query. Older
queries wishing to obtain the new behavior will need to be updated to remove
their captured `Token` field. Capturing ACL Tokens is analogous to
[PostgreSQL’s SECURITY DEFINER](http://www.postgresql.org/docs/current/static/sql-createfunction.html)
attribute which can be set on functions. This change in effect moves Consul
from using `SECURITY DEFINER` to `SECURITY INVOKER` by default for
new Prepared Queries.
<a name="near"></a>
`Near` allows specifying a particular node to sort near based on distance
sorting using [Network Coordinates](/docs/internals/coordinates.html). The
nearest instance to the specified node will be returned first, and subsequent
nodes in the response will be sorted in ascending order of estimated round-trip
times. If the node given does not exist, the nodes in the response will
be shuffled. Using the magic `_agent` value is supported, and will automatically
return results nearest the agent servicing the request. If unspecified, the
response will be shuffled by default. This was added in Consul 0.7.
The set of fields inside the `Service` structure define the query's behavior.
`Service` is the name of the service to query. This is required.
`Failover` contains two fields, both of which are optional, and determine what
happens if no healthy nodes are available in the local datacenter when the query
is executed. It allows the use of nodes in other datacenters with very little
configuration.
If `NearestN` is set to a value greater than zero, then the query
will be forwarded to up to `NearestN` other datacenters based on their estimated
network round trip time using [Network Coordinates](/docs/internals/coordinates.html)
from the WAN gossip pool. The median round trip time from the server handling the
query to the servers in the remote datacenter is used to determine the priority.
The default value is zero. All Consul servers must be running version 0.6.0 or
above in order for this feature to work correctly. If any servers are not running
the required version of Consul they will be considered last since they won't have
any available network coordinate information.
`Datacenters` contains a fixed list of remote datacenters to forward the query
to if there are no healthy nodes in the local datacenter. Datacenters are queried
in the order given in the list. If this option is combined with `NearestN`, then
the `NearestN` queries will be performed first, followed by the list given by
`Datacenters`. A given datacenter will only be queried one time during a failover,
even if it is selected by both `NearestN` and is listed in `Datacenters`. The
default value is an empty list.
`OnlyPassing` controls the behavior of the query's health check filtering. If
this is set to false, the results will include nodes with checks in the passing
as well as the warning states. If this is set to true, only nodes with checks
in the passing state will be returned. The default value is false.
`Tags` provides a list of service tags to filter the query results. For a service
to pass the tag filter it must have *all* of the required tags, and *none* of the
excluded tags (prefixed with `!`). The default value is an empty list, which does
no tag filtering.
`NodeMeta` provides a list of user-defined key/value pairs that will be used for
filtering the query results to nodes with the given metadata values present. This
was added in Consul 0.7.3.
`TTL` in the `DNS` structure is a duration string that can use `s` as a
suffix for seconds. It controls how the TTL is set when query results are served
over DNS. If this isn't specified, then the Consul agent configuration for the given
service will be used (see [DNS Caching](/docs/guides/dns-cache.html)). If this is
specified, it will take precedence over any Consul agent-specific configuration.
If no TTL is specified here or at the Consul agent level, then the TTL will
default to 0.
The return code is 200 on success and the ID of the created query is returned in
a JSON body:
```javascript
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"
}
```
<a name="templates"><b>Prepared Query Templates</b></a>
Consul 0.6.4 and later also support prepared query templates. These are
created similar to static templates, except with some additional fields
and features. Here's an example:
```javascript
{
"Name": "geo-db",
"Template": {
"Type": "name_prefix_match",
"Regexp": "^geo-db-(.*?)-([^\\-]+?)$"
},
"Service": {
"Service": "mysql-${match(1)}",
"Failover": {
"NearestN": 3,
"Datacenters": ["dc1", "dc2"]
},
"OnlyPassing": true,
"Tags": ["${match(2)}"],
"NodeMeta": {"instance_type": "m3.large"}
}
}
```
The new `Template` structure configures a prepared query as a template instead of a
static query. It has two fields:
`Type` is the query type, which must be `name_prefix_match`. This means that the
template will apply to any query lookup with a name whose prefix matches the `Name`
field of the template. In this example, any query for `geo-db` will match this
query. Query templates are resolved using a longest prefix match, so it's possible
to have high-level templates that are overridden for specific services. Static
queries are always resolved first, so they can also override templates.
`Regexp` is an optional regular expression which is used to extract fields from the
entire name, once this template is selected. In this example, the regular expression
takes the first item after the "-" as the database name and everything else after as
a tag. See the [RE2](https://github.com/google/re2/wiki/Syntax) reference for syntax
of this regular expression.
All other fields of the query have the same meanings as for a static query, except
that several interpolation variables are available to dynamically populate the query
before it is executed. All of the string fields inside the `Service` structure are
interpolated, with the following variables available:
`${name.full}` has the entire name that was queried. For example, a DNS lookup for
`geo-db-customer-primary.query.consul` in the example above would set this variable to
`geo-db-customer-primary`.
`${name.prefix}` has the prefix that matched. This would always be `geo-db` for
the example above.
`${name.suffix}` has the suffix after the prefix. For example, a DNS lookup for
`geo-db-customer-primary.query.consul` in the example above would set this variable to
`-customer-primary`.
`${match(N)}` returns the regular expression match at the given index N.
The 0 index will have the entire match, and >0 will have the results of
each match group. For example, a DNS lookup for
`geo-db-customer-primary.query.consul` in the example above with a
`Regexp` field set to `^geo-db-(.*?)-([^\-]+?)$` would return
`geo-db-customer-primary` for `${match(0)}`, `customer` for
`${match(1)}`, and `primary` for `${match(2)}`. If the regular
expression doesn't match, or an invalid index is given, then
`${match(N)}` will return an empty string.
See the [query explain](#explain) endpoint which is useful for testing interpolations
and determining which query is handling a given name.
Using templates it's possible to apply prepared query behaviors to many services
with a single template. Here's an example template that matches any query and
applies a failover policy to it:
```javascript
{
"Name": "",
"Template": {
"Type": "name_prefix_match"
},
"Service": {
"Service": "${name.full}",
"Failover": {
"NearestN": 3
}
}
}
```
This will match any lookup for `*.query.consul` and will attempt to find the
service locally, and otherwise attempt to find that service in the next three
closest datacenters. If ACLs are enabled, a catch-all template like this with
an empty `Name` requires an ACL token that can write to any query prefix. Also,
only a single catch-all template can be registered at any time.
#### GET Method
When using the `GET` method, Consul will provide a listing of all prepared queries.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter. This endpoint supports blocking
queries and all consistency modes.
If ACLs are enabled, then the client will only see prepared queries for which their
token has `query` read privileges. A management token will be able to see all
prepared queries. Tokens will be redacted and displayed as `<hidden>` unless a
management token is used.
This returns a JSON list of prepared queries, which looks like:
```javascript
[
{
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"Name": "my-query",
"Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Token": "<hidden>",
"Service": {
"Service": "redis",
"Failover": {
"NearestN": 3,
"Datacenters": ["dc1", "dc2"]
},
"OnlyPassing": false,
"Tags": ["primary", "!experimental"],
"NodeMeta": {"instance_type": "m3.large"}
},
"DNS": {
"TTL": "10s"
},
"RaftIndex": {
"CreateIndex": 23,
"ModifyIndex": 42
}
}
]
```
### <a name="specific"></a> /v1/query/\<query\>
The query-specific endpoint supports the `GET`, `PUT`, and `DELETE` methods. The
\<query\> argument is the ID of an existing prepared query.
#### PUT Method
The `PUT` method allows an existing prepared query to be updated.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with `query`
write privileges for the `Name` of the query being updated.
The body is the same as is used to create a prepared query, as described above.
If the API call succeeds, a 200 status code is returned.
#### GET Method
The `GET` method allows an existing prepared query to be fetched.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter. This endpoint supports blocking
queries and all consistency modes.
The returned response is the same as the list of prepared queries above,
only with a single item present. If the query does not exist then a 404
status code will be returned.
If ACLs are enabled, then the client will only see prepared queries for which their
token has `query` read privileges. A management token will be able to see all
prepared queries. Tokens will be redacted and displayed as `<hidden>` unless a
management token is used.
#### DELETE Method
The `DELETE` method is used to delete a prepared query.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with `query`
write privileges for the `Name` of the query being deleted.
No body is required as part of this request.
If the API call succeeds, a 200 status code is returned.
### <a name="execute"></a> /v1/query/\<query or name\>/execute
The query execute endpoint supports only the `GET` method and is used to
execute a prepared query. The \<query or name\> argument is the ID or name
of an existing prepared query, or a name that matches a prefix name for a
[prepared query template](#templates).
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter. This endpoint does not support
blocking queries, but it does support all consistency modes.
Adding the optional `?near=` parameter with a node name will sort the resulting
list in ascending order based on the estimated round trip time from that node.
Passing `?near=_agent` will use the agent's node for the sort. If this is not
present, the default behavior will shuffle the nodes randomly each time the
query is executed. Passing this option will override the built-in
<a href="#near">near parameter</a> of a prepared query, if present.
An optional `?limit=` parameter can be used to limit the size of the list to
the given number of nodes. This is applied after any sorting or shuffling.
If an ACL Token was bound to the query when it was defined then it will be used
when executing the request. Otherwise, the client's supplied ACL Token will be
used.
No body is required as part of this request.
If the query does not exist then a 404 status code will be returned. Otherwise,
a JSON body will be returned like this:
```javascript
{
"Service": "redis",
"Nodes": [
{
"Node": {
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Address": "10.1.10.12",
"TaggedAddresses": {
"lan": "10.1.10.12",
"wan": "10.1.10.12"
},
"NodeMeta": {"instance_type": "m3.large"}
},
"Service": {
"ID": "redis",
"Service": "redis",
"Tags": null,
"Port": 8000
},
"Checks": [
{
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
},
{
"Node": "foobar",
"CheckID": "serfHealth",
"Name": "Serf Health Status",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "",
"ServiceName": ""
}
],
"DNS": {
"TTL": "10s"
},
"Datacenter": "dc3",
"Failovers": 2
}]
}
```
The `Nodes` section contains the list of healthy nodes providing the given
service, as specified by the constraints of the prepared query.
`Service` has the service name that the query was selecting. This is useful
for context in case an empty list of nodes is returned.
`DNS` has information used when serving the results over DNS. This is just a
copy of the structure given when the prepared query was created.
`Datacenter` has the datacenter that ultimately provided the list of nodes
and `Failovers` has the number of remote datacenters that were queried
while executing the query. This provides some insight into where the data
came from. This will be zero during non-failover operations where there
were healthy nodes found in the local datacenter.
### <a name="explain"></a> /v1/query/\<query or name\>/explain
The query explain endpoint supports only the `GET` method and is used to see
a fully-rendered query for a given name. This is especially useful for finding
which [prepared query template](#templates) matches a given name, and what the
final query looks like after interpolation.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter. This endpoint does not support
blocking queries, but it does support all consistency modes.
If ACLs are enabled, then the client will only see prepared queries for which their
token has `query` read privileges. A management token will be able to see all
prepared queries. Tokens will be redacted and displayed as `<hidden>` unless a
management token is used.
If the query does not exist then a 404 status code will be returned. Otherwise,
a JSON body will be returned like this:
```javascript
{
"Query": {
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
"Name": "my-query",
"Session": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"Token": "<hidden>",
"Name": "geo-db",
"Template": {
"Type": "name_prefix_match",
"Regexp": "^geo-db-(.*?)-([^\\-]+?)$"
},
"Service": {
"Service": "mysql-customer",
"Failover": {
"NearestN": 3,
"Datacenters": ["dc1", "dc2"]
},
"OnlyPassing": true,
"Tags": ["primary"],
"NodeMeta": {"instance_type": "m3.large"}
}
}
```
Even though this query is a template, it is shown with its `Service`
fields interpolated based on the example query name `geo-db-customer-primary`.

202
website/source/docs/agent/http/session.html.markdown
View File

@ -1,202 +0,0 @@
---
layout: "docs"
page_title: "Sessions (HTTP)"
sidebar_current: "docs-agent-http-sessions"
description: >
The Session endpoints are used to create, destroy, and query sessions.
---
# Session HTTP Endpoint
The Session endpoints are used to create, destroy, and query sessions.
The following endpoints are supported:
* [`/v1/session/create`](#session_create): Creates a new session
* [`/v1/session/destroy/<session>`](#session_destroy): Destroys a given session
* [`/v1/session/info/<session>`](#session_info): Queries a given session
* [`/v1/session/node/<node>`](#session_node): Lists sessions belonging to a node
* [`/v1/session/list`](#session_list): Lists all active sessions
* [`/v1/session/renew`](#session_renew): Renews a TTL-based session
All of the read session endpoints support blocking queries and all consistency modes.
### <a name="session_create"></a> /v1/session/create
The create endpoint is used to initialize a new session.
There is more documentation on sessions [here](/docs/internals/sessions.html).
Sessions must be associated with a node and may be associated with any number of checks.
The create endpoint expects a JSON request body to be `PUT`. The request
body must look like:
```javascript
{
"LockDelay": "15s",
"Name": "my-service-lock",
"Node": "foobar",
"Checks": ["a", "b", "c"],
"Behavior": "release",
"TTL": "0s"
}
```
None of the fields are mandatory, and in fact no body needs to be PUT
if the defaults are to be used.
By default, the agent's local datacenter is used; another datacenter
can be specified using the `?dc=` query parameter. However, it is not recommended
to use cross-datacenter sessions.
`LockDelay` can be specified as a duration string using an `s` suffix for
seconds. The default is 15s.
`Node` must refer to a node that is already registered, if specified. By default,
the agent's own node name is used.
`Name` can be used to provide a human-readable name for the Session.
`Checks` is used to provide a list of associated health checks. It is highly recommended
that, if you override this list, you include the default `serfHealth`.
`Behavior` can be set to either `release` or `delete`. This controls
the behavior when a session is invalidated. By default, this is `release`,
causing any locks that are held to be released. Changing this to `delete`
causes any locks that are held to be deleted. `delete` is useful for creating ephemeral
key/value entries.
The `TTL` field is a duration string, and like `LockDelay` it can use `s` as
a suffix for seconds. If specified, it must be between 10s and 86400s currently.
When provided, the session is invalidated if it is not renewed before the TTL
expires. The lowest practical TTL should be used to keep the number of managed
sessions low. When locks are forcibly expired, such as during a leader election,
sessions may not be reaped for up to double this TTL, so long TTL values (>1 hour)
should be avoided. See the [session internals page](/docs/internals/sessions.html)
for more documentation of this feature.
The return code is 200 on success and returns the ID of the created session:
```javascript
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
```
### <a name="session_destroy"></a> /v1/session/destroy/\<session\>
The destroy endpoint is hit with a `PUT` and destroys the given session.
By default, the local datacenter is used, but the `?dc=` query parameter
can be used to specify the datacenter.
The session being destroyed must be provided on the path.
The return code is 200 on success.
### <a name="session_info"></a> /v1/session/info/\<session\>
This endpoint is hit with a `GET` and returns the requested session information
within a given datacenter. By default, the datacenter of the agent is queried;
however, the `dc` can be provided using the `?dc=` query parameter.
The session being queried must be provided on the path.
It returns a JSON body like this:
```javascript
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449
}
]
```
If the session is not found, null is returned instead of a JSON list.
This endpoint supports blocking queries and all consistency modes.
### <a name="session_node"></a> /v1/session/node/\<node\>
This endpoint is hit with a `GET` and returns the active sessions
for a given node and datacenter. By default, the datacenter of the agent is queried;
however, the `dc` can be provided using the `?dc=` query parameter.
The node being queried must be provided on the path.
It returns a JSON body like this:
```javascript
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449
},
...
]
```
This endpoint supports blocking queries and all consistency modes.
### <a name="session_list"></a> /v1/session/list
This endpoint is hit with a `GET` and returns the active sessions
for a given datacenter. By default, the datacenter of the agent is queried;
however, the `dc` can be provided using the `?dc=` query parameter.
It returns a JSON body like this:
```javascript
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449
},
...
]
```
This endpoint supports blocking queries and all consistency modes.
### <a name="session_renew"></a> /v1/session/renew/\<session\>
The renew endpoint is hit with a `PUT` and renews the given session.
This is used with sessions that have a TTL, and it extends the
expiration by the TTL. By default, the local datacenter is used, but the `?dc=`
query parameter can be used to specify the datacenter.
The session being renewed must be provided on the path.
The return code is 200 on success. The response JSON body looks like this:
```javascript
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449
"Behavior": "release",
"TTL": "15s"
}
]
```
The response body includes the current session.
-> **Note:** Consul MAY return a TTL value higher than the one specified during session creation. This indicates the server is under high load and is requesting clients renew less often.

94
website/source/docs/agent/http/snapshot.html.markdown
View File

@ -1,94 +0,0 @@
---
layout: "docs"
page_title: "Consul Snapshots (HTTP)"
sidebar_current: "docs-agent-http-snapshots"
description: >
The Snapshot endpoints are used to save and restore Consul's server state for disaster recovery.
---
# Snapshot HTTP Endpoint
The Snapshot endpoints are used to save and restore the state of the Consul
servers for disaster recovery. Snapshots include all state managed by Consul's
Raft [consensus protocol](/docs/internals/consensus.html), including:
* Key/Value Entries
* Service Catalog
* Prepared Queries
* Sessions
* ACLs
Available in Consul 0.7.1 and later, these endpoints allow for atomic,
point-in-time snapshots of the above data in a format that can be saved
externally. Snapshots can then be used to restore the server state into a fresh
cluster of Consul servers in the event of a disaster.
The following endpoints are supported:
* [`/v1/snapshot`](#snapshot): Save and restore Consul server state
These endpoints do not support blocking queries. Saving snapshots uses the
consistent mode by default and stale mode is supported.
The endpoints support the use of ACL Tokens. Because snapshots contain all
server state, including ACLs, a management token is required to perform snapshot
operations if ACLs are enabled.
### <a name="snapshot"></a> /v1/snapshot
The snapshot endpoint supports the `GET` and `PUT` methods.
#### GET Method
When using the `GET` method, Consul will perform an atomic, point-in-time
snapshot of the Consul server state.
Snapshots are exposed as gzipped tar archives which internally contain the Raft
metadata required to restore, as well as a binary serialized version of the Consul
server state. The contents are covered internally by SHA-256 hashes. These hashes
are verified during snapshot restore operations. The structure of the archive is
internal to Consul and not intended to be used other than for restore operations.
In particular, the archives are not designed to be modified before a restore.
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the `?dc=` query parameter.
By default, snapshots use consistent mode which means the request is internally
forwarded to the cluster leader, and leadership is checked before performing the
snapshot. If `stale` is specified using the `?stale` query parameter, then any
server can handle the request and the results may be arbitrarily stale. To support
bounding the acceptable staleness of snapshots, responses provide the `X-Consul-LastContact`
header containing the time in milliseconds that a server was last contacted by
the leader node. The `X-Consul-KnownLeader` header also indicates if there is a
known leader. These can be used by clients to gauge the staleness of a snapshot
and take appropriate action. The stale mode is particularly useful for taking a
snapshot of a cluster in a failed state with no current leader.
If ACLs are enabled, the client will need to supply an ACL Token with management
privileges.
The return code is 200 on success, and the snapshot will be returned in the body
as a gzipped tar archive. In addition to the stale-related headers described above,
the `X-Consul-Index` header will also be set to the index at which the snapshot took
place.
#### PUT Method
When using the `PUT` method, Consul will atomically restore a point-in-time
snapshot of the Consul server state.
Restores involve a potentially dangerous low-level Raft operation that is not
designed to handle server failures during a restore. This operation is primarily
intended to be used when recovering from a disaster, restoring into a fresh
cluster of Consul servers.
By default, the datacenter of the agent is targeted; however, the `dc` can be
provided using the `?dc=` query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with management
privileges.
The body of the request should be a snapshot archive returned from a previous call
to the `GET` method.
The return code is 200 on success.

46
website/source/docs/agent/http/status.html.markdown
View File

@ -1,46 +0,0 @@
---
layout: "docs"
page_title: "Status (HTTP)"
sidebar_current: "docs-agent-http-status"
description: >
The Status endpoints are used to get information about the status
of the Consul cluster.
---
# Status HTTP Endpoint
The Status endpoints are used to get information about the status
of the Consul cluster.
Please note: this information is generally very low level
and not often useful for clients.
The following endpoints are supported:
* [`/v1/status/leader`](#status_leader) : Returns the current Raft leader
* [`/v1/status/peers`](#status_peers) : Returns the current Raft peer set
### <a name="status_leader"></a> /v1/status/leader
This endpoint is used to get the Raft leader for the datacenter
in which the agent is running. It returns an address, such as:
```text
"10.1.10.12:8300"
```
### <a name="status_peers"></a> /v1/status/peers
This endpoint retrieves the Raft peers for the datacenter in which the
the agent is running. It returns a list of addresses, such as:
```javascript
[
"10.1.10.12:8300",
"10.1.10.11:8300",
"10.1.10.10:8300"
]
```
This list of peers is strongly consistent and can be useful in determining when
a given server has successfully joined the cluster.

18
website/source/docs/agent/options.html.markdown
View File

@ -296,9 +296,9 @@ will exit with an error at startup.
`adf4238a-882b-9ddc-4a9d-5b6758e4159e`. If this isn't supplied, which is the most common case, then
the agent will generate an identifier at startup and persist it in the <a href="#_data_dir">data directory</a>
so that it will remain the same across agent restarts. This is currently only exposed via
<a href="/docs/agent/http/agent.html#agent_self">/v1/agent/self</a>,
<a href="/docs/agent/http/catalog.html">/v1/catalog</a>, and
<a href="/docs/agent/http/health.html">/v1/health</a> endpoints, but future versions of
<a href="/api/agent.html#agent_self">/v1/agent/self</a>,
<a href="/api/catalog.html">/v1/catalog</a>, and
<a href="/api/health.html">/v1/health</a> endpoints, but future versions of
Consul will use this to better manage cluster changes, especially for Consul servers.
* <a name="_node_meta"></a><a href="#_node_meta">`-node-meta`</a> - Available in Consul 0.7.3 and later,
@ -450,7 +450,7 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
values. If a non-cached ACL is used, "extend-cache" acts like "deny".
* <a name="acl_agent_master_token"></a><a href="#acl_agent_master_token">`acl_agent_master_token`</a> -
Used to access <a href="/docs/agent/http/agent.html">agent endpoints</a> that require agent read
Used to access <a href="/api/agent.html">agent endpoints</a> that require agent read
or write privileges even if Consul servers aren't present to validate any tokens. This should only
be used by operators during outages, regular ACL tokens should normally be used by applications.
This was added in Consul 0.7.2 and is only used when <a href="#acl_enforce_version_8">`acl_enforce_version_8`</a>
@ -1033,11 +1033,11 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
<br>
<br>The following endpoints translate addresses:
<br>
* [`/v1/catalog/nodes`](/docs/agent/http/catalog.html#catalog_nodes)
* [`/v1/catalog/node/<node>`](/docs/agent/http/catalog.html#catalog_node)
* [`/v1/catalog/service/<service>`](/docs/agent/http/catalog.html#catalog_service)
* [`/v1/health/service/<service>`](/docs/agent/http/health.html#health_service)
* [`/v1/query/<query or name>/execute`](/docs/agent/http/query.html#execute)
* [`/v1/catalog/nodes`](/api/catalog.html#catalog_nodes)
* [`/v1/catalog/node/<node>`](/api/catalog.html#catalog_node)
* [`/v1/catalog/service/<service>`](/api/catalog.html#catalog_service)
* [`/v1/health/service/<service>`](/api/health.html#health_service)
* [`/v1/query/<query or name>/execute`](/api/query.html#execute)
* <a name="ui"></a><a href="#ui">`ui`</a> - Equivalent to the [`-ui`](#_ui)
command-line flag.

2
website/source/docs/agent/services.html.markdown
View File

@ -78,7 +78,7 @@ from `1`.
The `enableTagOverride` can optionally be specified to disable the
anti-entropy feature for this service. If `enableTagOverride` is set to
`TRUE` then external agents can update this service in the
[catalog](/docs/agent/http/catalog.html) and modify the tags. Subsequent
[catalog](/api/catalog.html) and modify the tags. Subsequent
local sync operations by this agent will ignore the updated tags. For
example, if an external agent modified both the tags and the port for
this service and `enableTagOverride` was set to `TRUE` then after the next

2
website/source/docs/commands/index.html.markdown
View File

@ -35,7 +35,7 @@ Available commands are:
join Tell Consul agent to join cluster
keygen Generates a new encryption key
keyring Manages gossip layer encryption keys
kv Interact with the key-value store
kv Interact with the KV store
leave Gracefully leaves the Consul cluster and shuts down
lock Execute a command holding a lock
maint Controls node or service maintenance mode

8
website/source/docs/commands/kv.html.markdown
View File

@ -8,13 +8,13 @@ sidebar_current: "docs-commands-kv"
Command: `consul kv`
The `kv` command is used to interact with Consul's key-value store via the
The `kv` command is used to interact with Consul's KV store via the
command line. It exposes top-level commands for inserting, updating, reading,
and deleting from the store. This command is available in Consul 0.7.1 and
later.
The key-value store is also accessible via the
[HTTP API](/docs/agent/http/kv.html).
The KV store is also accessible via the
[HTTP API](/api/kv.html).
## Usage
@ -49,7 +49,7 @@ of the subcommand in the sidebar or one of the links below:
## Basic Examples
To create or update the key named "redis/config/connections" to the value "5" in
Consul's key-value store:
Consul's KV store:
```text
$ consul kv put redis/config/connections 5

4
website/source/docs/commands/kv/delete.html.markdown.erb
View File

@ -8,7 +8,7 @@ sidebar_current: "docs-commands-kv-delete"
Command: `consul kv delete`
The `kv delete` command removes the value from Consul's key-value store at the
The `kv delete` command removes the value from Consul's KV store at the
given path. If no key exists at the path, no action is taken.
## Usage
@ -34,7 +34,7 @@ Usage: `consul kv delete [options] KEY_OR_PREFIX`
## Examples
To remove the value for the key named "redis/config/connections" in the
key-value store:
KV store:
```
$ consul kv delete redis/config/connections

4
website/source/docs/commands/kv/export.html.markdown.erb
View File

@ -8,8 +8,8 @@ sidebar_current: "docs-commands-kv-export"
Command: `consul kv export`
The `kv export` command is used to retrieve key-value pairs for the given
prefix from Consul's key-value store, and write a JSON representation to
The `kv export` command is used to retrieve KV pairs for the given
prefix from Consul's KV store, and write a JSON representation to
stdout. This can be used with the command "consul kv import" to move entire
trees between Consul clusters.

6
website/source/docs/commands/kv/get.html.markdown.erb
View File

@ -8,11 +8,11 @@ sidebar_current: "docs-commands-kv-get"
Command: `consul kv get`
The `kv get` command is used to retrieve the value from Consul's key-value
The `kv get` command is used to retrieve the value from Consul's KV
store at the given key name. If no key exists with that name, an error is
returned. If a key exists with that name but has no data, nothing is returned.
If the name or prefix is omitted, it defaults to "" which is the root of the
key-value store.
KV store.
## Usage
@ -46,7 +46,7 @@ Usage: `consul kv get [options] [KEY_OR_PREFIX]`
## Examples
To retrieve the value for the key named "redis/config/connections" in the
key-value store:
KV store:
```
$ consul kv get redis/config/connections

6
website/source/docs/commands/kv/put.html.markdown.erb
View File

@ -8,7 +8,7 @@ sidebar_current: "docs-commands-kv-put"
Command: `consul kv put`
The `kv put` command writes the data to the given path in the key-value store.
The `kv put` command writes the data to the given path in the KV store.
## Usage
@ -30,7 +30,7 @@ Usage: `consul kv put [options] KEY [DATA]`
* `-cas` - Perform a Check-And-Set operation. Specifying this value also
requires the -modify-index flag to be set. The default value is false.
* `-flags=<int>` - Unsigned integer value to assign to this key-value pair. This
* `-flags=<int>` - Unsigned integer value to assign to this KV pair. This
value is not read by Consul, so clients can use this value however makes sense
for their use case. The default value is 0 (no flags).
@ -49,7 +49,7 @@ Usage: `consul kv put [options] KEY [DATA]`
## Examples
To insert a value of "5" for the key named "redis/config/connections" in the
key-value store:
KV store:
```
$ consul kv put redis/config/connections 5

2
website/source/docs/commands/lock.html.markdown.erb
View File

@ -11,7 +11,7 @@ description: |-
Command: `consul lock`
The `lock` command provides a mechanism for simple distributed locking.
A lock (or semaphore) is created at a given prefix in the Key/Value store,
A lock (or semaphore) is created at a given prefix in the KV store,
and only when held, is a child process invoked. If the lock is lost or
communication is disrupted, the child process is terminated.

2
website/source/docs/commands/operator.html.markdown.erb
View File

@ -23,7 +23,7 @@ if required, so this can be run from any Consul node in a cluster. See the
See the [Outage Recovery](/docs/guides/outage.html) guide for some examples of how
this command is used. For an API to perform these operations programatically,
please see the documentation for the [Operator](/docs/agent/http/operator.html)
please see the documentation for the [Operator](/api/operator.html)
endpoint.
## Usage

2
website/source/docs/commands/snapshot.html.markdown
View File

@ -13,7 +13,7 @@ state of the Consul servers for disaster recovery. These are atomic, point-in-ti
snapshots which include key/value entries, service catalog, prepared queries,
sessions, and ACLs. This command is available in Consul 0.7.1 and later.
Snapshots are also accessible via the [HTTP API](/docs/agent/http/snapshot.html).
Snapshots are also accessible via the [HTTP API](/api/snapshot.html).
## Usage

6
website/source/docs/commands/snapshot/agent.html.markdown.erb
View File

@ -49,7 +49,7 @@ remote storage.
Snapshots can be restored using the
[`consul snapshot restore`](/docs/commands/snapshot/restore.html) command, or
the [HTTP API](/docs/agent/http/snapshot.html).
the [HTTP API](/api/snapshot.html).
If ACLs are enabled, a management token must be supplied in order to perform
snapshot operations.
@ -122,7 +122,7 @@ if desired.
or hours. If 0 is provided, the agent will take a single snapshot and then exit,
which is useful for running snapshots via batch jobs. Defaults to "1h"
* `-lock-key` - A prefix in Consul's key-value store used to coordinate between
* `-lock-key` - A prefix in Consul's KV store used to coordinate between
different instances of the snapshot agent order to only have one active instance
at a time. For highly available operation of the snapshot agent, simply run
multiple instances. All instances must be configured with the same lock key in
@ -205,5 +205,5 @@ leader election or service registration:
$ consul snapshot agent -interval=0
```
Please see the [HTTP API](/docs/agent/http/snapshot.html) documentation for
Please see the [HTTP API](/api/snapshot.html) documentation for
more details about snapshot internals.

2
website/source/docs/commands/snapshot/inspect.html.markdown.erb
View File

@ -43,5 +43,5 @@ Term 2
Version 1
```
Please see the [HTTP API](/docs/agent/http/snapshot.html) documentation for
Please see the [HTTP API](/api/snapshot.html) documentation for
more details about snapshot internals.

2
website/source/docs/commands/snapshot/restore.html.markdown.erb
View File

@ -39,5 +39,5 @@ $ consul snapshot restore backup.snap
Restored snapshot
```
Please see the [HTTP API](/docs/agent/http/snapshot.html) documentation for
Please see the [HTTP API](/api/snapshot.html) documentation for
more details about snapshot internals.

2
website/source/docs/commands/snapshot/save.html.markdown.erb
View File

@ -53,5 +53,5 @@ This is useful for situations where a cluster is in a degraded state and no
leader is available. To target a specific server for a snapshot, you can run
the `consul snapshot save` command on that specific server.
Please see the [HTTP API](/docs/agent/http/snapshot.html) documentation for
Please see the [HTTP API](/api/snapshot.html) documentation for
more details about snapshot internals.

2
website/source/docs/faq.html.markdown
View File

@ -44,7 +44,7 @@ designed to avoid any dependence on those capabilities.
Consul has two important subsystems, the service catalog and the gossip protocol.
The service catalog stores all the nodes, service instances, health check data,
ACLs, and Key/Value information. It is strongly consistent, and replicated
ACLs, and KV information. It is strongly consistent, and replicated
using the [consensus protocol](/docs/internals/consensus.html).
The [gossip protocol](/docs/internals/gossip.html) is used to track which

2
website/source/docs/guides/areas.html.markdown
View File

@ -48,7 +48,7 @@ to via an area (or via the WAN), but future versions of Consul may add routing s
The following can be used to manage network areas:
* [Network Areas HTTP Endpoint](/docs/agent/http/operator.html#network-areas)
* [Network Areas HTTP Endpoint](/api/operator.html#network-areas)
* [Network Areas Operator CLI](/docs/commands/operator/area.html)
## Network Areas and the WAN Gossip Pool

6
website/source/docs/guides/autopilot.html.markdown
View File

@ -26,7 +26,7 @@ The configuration of Autopilot is loaded by the leader from the agent's
bootstrapping the cluster. After bootstrapping, the configuration can
be viewed or modified either via the [`operator autopilot`]
(/docs/commands/operator/autopilot.html) subcommand or the
[`/v1/operator/autopilot/configuration`](/docs/agent/http/operator.html#autopilot-configuration)
[`/v1/operator/autopilot/configuration`](/api/operator.html#autopilot-configuration)
HTTP endpoint:
```
@ -79,7 +79,7 @@ An internal health check runs on the leader to track the stability of servers.
`MaxTrailingLogs`
The status of these health checks can be viewed through the [`/v1/operator/autopilot/health`]
(/docs/agent/http/operator.html#autopilot-health) HTTP endpoint, with a top level
(/api/operator.html#autopilot-health) HTTP endpoint, with a top level
`Healthy` field indicating the overall status of the cluster:
```
@ -169,7 +169,7 @@ to voters and demoting the old servers. After this is finished, the old servers
safely removed from the cluster.
To check the consul version of the servers, either the [autopilot health]
(/docs/agent/http/operator.html#autopilot-health) endpoint or the `consul members`
(/api/operator.html#autopilot-health) endpoint or the `consul members`
command can be used:
```

2
website/source/docs/guides/datacenters.html.markdown
View File

@ -61,7 +61,7 @@ Once the join is complete, the [`members`](/docs/commands/members.html) command
used to verify that all server nodes gossiping over WAN.
We can also verify that both datacenters are known using the
[HTTP Catalog API](/docs/agent/http/catalog.html#catalog_datacenters):
[HTTP Catalog API](/api/catalog.html#catalog_datacenters):
```text
$ curl http://localhost:8500/v1/catalog/datacenters

2
website/source/docs/guides/dns-cache.html.markdown
View File

@ -100,7 +100,7 @@ This sets all lookups to "web.service.consul" to use a 30 second TTL
while lookups to "db.service.consul" or "api.service.consul" will use the
5 second TTL from the wildcard.
[Prepared Queries](/docs/agent/http/query.html) provide an additional
[Prepared Queries](/api/query.html) provide an additional
level of control over TTL. They allow for the TTL to be defined along with
the query, and they can be changed on the fly by updating the query definition.
If a TTL is not configured for a prepared query, then it will fall back to the

2
website/source/docs/guides/external.html.markdown
View File

@ -65,4 +65,4 @@ $ curl -X PUT -d '{"Datacenter": "dc1", "Node": "google"}' http://127.0.0.1:8500
This will deregister the `google` node along with all services it provides.
For more information, please see the [HTTP Catalog API](/docs/agent/http/catalog.html).
For more information, please see the [HTTP Catalog API](/api/catalog.html).

2
website/source/docs/guides/index.html.markdown
View File

@ -36,5 +36,5 @@ The following guides are available:
* [Server Performance](/docs/guides/performance.html) - This guide covers minumum requirements for Consul servers as well as guidelines for running Consul servers in production.
* [Semaphore](/docs/guides/semaphore.html) - This guide covers using the Key/Value store to implement a semaphore.
* [Semaphore](/docs/guides/semaphore.html) - This guide covers using the KV store to implement a semaphore.

8
website/source/docs/guides/leader-election.html.markdown
View File

@ -32,7 +32,7 @@ service/<service name>/leader
We'll abbreviate this pattern as simply `<key>` for the rest of this guide.
The first step is to create a session using the
[Session HTTP API](/docs/agent/http/session.html#session_create):
[Session HTTP API](/api/session.html#session_create):
```text
curl -X PUT -d '{"Name": "dbservice"}' \
@ -48,7 +48,7 @@ This will return a JSON object containing the session ID:
```
The next step is to acquire a session for a given key from this node
using the PUT method on a [KV entry](/docs/agent/http/kv.html) with the
using the PUT method on a [KV entry](/api/kv.html) with the
`?acquire=<session>` query parameter. The `<body>` of the PUT should be a
JSON object representing the local node. This value is opaque to
Consul, but it should contain whatever information clients require to
@ -57,7 +57,7 @@ that contains the node's name and the application's port).
Attempt to `acquire` the `<key>`. This will look something like (note that
`<session>` is the ID returned by the call to
[`/v1/session/create`](/docs/agent/http/session.html#session_create)):
[`/v1/session/create`](/api/session.html#session_create)):
```text
curl -X PUT -d <body> http://localhost:8500/v1/kv/<key>?acquire=<session>
@ -120,7 +120,7 @@ application-dependent information required as a Base64 encoded blob in
the `Value` field.
You can query the
[`/v1/session/info`](/docs/agent/http/session.html#session_info)
[`/v1/session/info`](/api/session.html#session_info)
endpoint to get details about the session:
```text

10
website/source/docs/guides/semaphore.html.markdown
View File

@ -3,13 +3,13 @@ layout: "docs"
page_title: "Semaphore"
sidebar_current: "docs-guides-semaphore"
description: |-
This guide demonstrates how to implement a distributed semaphore using the Consul Key/Value store.
This guide demonstrates how to implement a distributed semaphore using the Consul KV store.
---
# Semaphore
This guide demonstrates how to implement a distributed semaphore using the Consul
Key/Value store. This is useful when you want to coordinate many services while
KV store. This is useful when you want to coordinate many services while
restricting access to certain resources.
~> If you only need mutual exclusion or leader election,
@ -27,7 +27,7 @@ can gracefully handle failures.
Let's imagine we have a set of nodes who are attempting to acquire a slot in the
semaphore. All nodes that are participating should agree on three decisions: the
prefix in the Key/Value store used to coordinate, a single key to use as a lock,
prefix in the KV store used to coordinate, a single key to use as a lock,
and a limit on the number of slot holders.
For the prefix we will be using for coordination, a good pattern is simply:
@ -39,7 +39,7 @@ service/<service name>/lock/
We'll abbreviate this pattern as simply `<prefix>` for the rest of this guide.
The first step is to create a session. This is done using the
[Session HTTP API](/docs/agent/http/session.html#session_create):
[Session HTTP API](/api/session.html#session_create):
```text
curl -X PUT -d '{"Name": "dbservice"}' \
@ -66,7 +66,7 @@ curl -X PUT -d <body> http://localhost:8500/v1/kv/<prefix>/<session>?acquire=<se
```
The `<session>` value is the ID returned by the call to
[`/v1/session/create`](/docs/agent/http/session.html#session_create).
[`/v1/session/create`](/api/session.html#session_create).
`body` can be used to associate a meaningful value with the contender. This is opaque
to Consul but can be useful for human operators.

8
website/source/docs/internals/acl.html.markdown
View File

@ -96,7 +96,7 @@ a large set of ACLs.
If there's a partition or other outage affecting the authoritative datacenter,
and the [`acl_down_policy`](/docs/agent/options.html#acl_down_policy)
is set to "extend-cache", tokens will be resolved during the outage using the
replicated set of ACLs. An [ACL replication status](/docs/agent/http/acl.html#acl_replication_status)
replicated set of ACLs. An [ACL replication status](/api/acl.html#acl_replication_status)
endpoint is available to monitor the health of the replication process.
Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/options.html#acl_ttl)
@ -109,7 +109,7 @@ using a process like this:
1. Enable ACL replication in all datacenters to allow continuation of service
during the migration, and to populate the target datacenter. Verify replication
is healthy and caught up to the current ACL index in the target datacenter
using the [ACL replication status](/docs/agent/http/acl.html#acl_replication_status)
using the [ACL replication status](/api/acl.html#acl_replication_status)
endpoint.
2. Turn down the old authoritative datacenter servers.
3. Rolling restart the servers in the target datacenter and change the
@ -366,7 +366,7 @@ per-token policy is applied to maximize security.
Consul 0.7 added special Consul operator actions which are protected by a new
`operator` ACL policy. The operator actions cover:
* [Operator HTTP endpoint](/docs/agent/http/operator.html)
* [Operator HTTP endpoint](/api/operator.html)
* [Operator CLI command](/docs/commands/operator.html)
If your [`acl_default_policy`](/docs/agent/options.html#acl_default_policy) is
@ -453,7 +453,7 @@ These variations are covered here, with examples:
that is used and known by many clients to provide geo-failover behavior for
a database.
* [Template queries](https://www.consul.io/docs/agent/http/query.html#templates)
* [Template queries](https://www.consul.io/api/query.html#templates)
queries work like static queries with a `Name` defined, except that a catch-all
template with an empty `Name` requires an ACL token that can write to any query
prefix.

10
website/source/docs/internals/coordinates.html.markdown
View File

@ -32,14 +32,14 @@ Network coordinates manifest in several ways inside Consul:
* The [`consul rtt`](/docs/commands/rtt.html) command can be used to query for the
network round trip time between any two nodes.
* The [Catalog endpoints](/docs/agent/http/catalog.html) and
[Health endpoints](/docs/agent/http/health.html) can sort the results of queries based
* The [Catalog endpoints](/api/catalog.html) and
[Health endpoints](/api/health.html) can sort the results of queries based
on the network round trip time from a given node using a "?near=" parameter.
* [Prepared queries](/docs/agent/http/query.html) can automatically fail over services
* [Prepared queries](/api/query.html) can automatically fail over services
to other Consul datacenters based on network round trip times.
* The [Coordinate endpoint](/docs/agent/http/coordinate.html) exposes raw network
* The [Coordinate endpoint](/api/coordinate.html) exposes raw network
coordinates for use in other applications.
Consul uses Serf to manage two different gossip pools, one for the LAN with members
@ -52,7 +52,7 @@ LAN coordinates, and WAN coordinates only make sense with other WAN coordinates.
Computing the estimated network round trip time between any two nodes is simple
once you have their coordinates. Here's a sample coordinate, as returned from the
[Coordinate endpoint](/docs/agent/http/coordinate.html).
[Coordinate endpoint](/api/coordinate.html).
```
"Coord": {

4
website/source/docs/internals/sessions.html.markdown
View File

@ -103,11 +103,11 @@ mechanism by providing a zero delay value.
## K/V Integration
Integration between the Key/Value store and sessions is the primary
Integration between the KV store and sessions is the primary
place where sessions are used. A session must be created prior to use
and is then referred to by its ID.
The Key/Value API is extended to support an `acquire` and `release` operation.
The KV API is extended to support an `acquire` and `release` operation.
The `acquire` operation acts like a Check-And-Set operation except it
can only succeed if there is no existing lock holder (the current lock holder
can re-`acquire`, see below). On success, there is a normal key update, but

2
website/source/docs/upgrade-specific.html.markdown
View File

@ -153,7 +153,7 @@ to upgrade all agents to a newer version of Consul before upgrading to Consul
#### Prepared Query Changes
Consul version 0.7 adds a feature which allows prepared queries to store a
[`Near` parameter](/docs/agent/http/query.html#near) in the query definition
[`Near` parameter](/api/query.html#near) in the query definition
itself. This feature enables using the distance sorting features of prepared
queries without explicitly providing the node to sort near in requests, but
requires the agent servicing a request to send additional information about

61
website/source/downloads_tools.html.erb
View File

@ -32,67 +32,6 @@ description: |-
</li>
</ul>
<h2>Consul SDK</h2>
<p>
These Consul SDK are created and managed by the amazing members of the Consul community:
</p>
<ul>
<li>
<a href="https://github.com/hashicorp/consul/tree/master/api">api</a> - Official Go client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/gmr/consulate">consulate</a> - Python client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/cablehead/python-consul">python-consul</a> - Python client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/vdloo/consul-kv">consul-kv</a> - Python 3 client for the Consul KV-store
</li>
<li>
<a href="https://github.com/sensiolabs/consul-php-sdk">consul-php-sdk</a> - PHP client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/dcarbone/php-consul-api">php-consul-api</a> - GO-like PHP Client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/tolitius/envoy">envoy</a> - Consul Clojure client with watchers and other goodies
</li>
<li>
<a href="https://github.com/hadielmougy/clj-consul-catalog">clj-consul-catalog</a> - Clojure discovery client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/codacy/scala-consul">scala-consul</a> - Scala client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/OrbitzWorldwide/consul-client">consul-client</a> - Java client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/Ecwid/consul-api">consul-api</a> - Java client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/undeadlabs/discovery">discovery</a> - Erlang/OTP client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/xaviershay/consul-client">consul-client</a> - Ruby client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/WeAreFarmGeek/diplomat">diplomat</a> - Ruby library to query Consul's KV-store and services directory
</li>
<li>
<a href="https://www.npmjs.com/package/consul">node-consul</a> - Node.js client for the Consul HTTP API
</li>
<li>
<a href="https://www.nuget.org/packages/Consul">Consul.NET</a> - C# client for the Consul HTTP API
</li>
<li>
<a href="https://metacpan.org/pod/Consul">Consul</a> - Perl client for the Consul HTTP API
</li>
<li>
<a href="https://github.com/Drawaes/CondenserDotNet">CondenserDotNet</a> - C# an opinionated API for .NET that provides higher level functionality for services using the HTTP API
</li>
</ul>
<h2>Community Tools</h2>
<p>
These Consul tools are created and managed by the amazing members of the Consul community:

4
website/source/index.html.erb
View File

@ -1,6 +1,6 @@
---
description: |-
Consul is a highly available and distributed service discovery and key-value
Consul is a highly available and distributed service discovery and KV
store designed with support for the modern data center to make distributed
systems and configuration easy.
---
@ -70,7 +70,7 @@ description: |-
<%= inline_svg "feature-config.svg", width: 85 %>
</div>
<div class="col-sm-9">
<h2>Key/Value Storage</h2>
<h2>KV Storage</h2>
<p>
Flexible key/value store for dynamic configuration, feature flagging,
coordination, leader election and more. Long poll for near-instant

2
website/source/intro/getting-started/checks.html.markdown
View File

@ -21,7 +21,7 @@ At this point, you should have a two-node cluster running.
Similar to a service, a check can be registered either by providing a
[check definition](/docs/agent/checks.html) or by making the
appropriate calls to the [HTTP API](/docs/agent/http/health.html).
appropriate calls to the [HTTP API](/api/health.html).
We will use the check definition approach because, just like with
services, definitions are the most common way to set up checks.

10
website/source/intro/getting-started/kv.html.markdown
View File

@ -1,15 +1,15 @@
---
layout: "intro"
page_title: "Key/Value Data"
page_title: "KV Data"
sidebar_current: "gettingstarted-kv"
description: |-
In addition to providing service discovery and integrated health checking, Consul provides an easy to use Key/Value store. This can be used to hold dynamic configuration, assist in service coordination, build leader election, and enable anything else a developer can think to build.
In addition to providing service discovery and integrated health checking, Consul provides an easy to use KV store. This can be used to hold dynamic configuration, assist in service coordination, build leader election, and enable anything else a developer can think to build.
---
# Key/Value Data
# KV Data
In addition to providing service discovery and integrated health checking,
Consul provides an easy to use Key/Value store. This can be used to hold
Consul provides an easy to use KV store. This can be used to hold
dynamic configuration, assist in service coordination, build leader election,
and enable anything else a developer can think to build.
@ -130,5 +130,5 @@ documentation, please see [Consul KV HTTP API][kv-api] or
Next, we will look at the [web UI](ui.html) options supported by Consul.
[kv-api]: /docs/agent/http/kv.html
[kv-api]: /api/kv.html
[kv-cli]: /docs/commands/kv.html

2
website/source/intro/index.html.markdown
View File

@ -31,7 +31,7 @@ key features:
used by an operator to monitor cluster health, and it is used by the service
discovery components to route traffic away from unhealthy hosts.
* **Key/Value Store**: Applications can make use of Consul's hierarchical key/value
* **KV Store**: Applications can make use of Consul's hierarchical key/value
store for any number of purposes, including dynamic configuration, feature flagging,
coordination, leader election, and more. The simple HTTP API makes it easy to use.

1
website/source/layouts/_sidebar.erb
View File

@ -8,6 +8,7 @@
<ul class="nav sidebar-nav">
<li><a href="/intro/index.html">Intro</a></li>
<li><a href="/docs/index.html">Docs</a></li>
<li><a href="/api/index.html">API</a></li>
<li><a href="/community.html">Community</a></li>
<li><a href="https://www.hashicorp.com/consul.html?utm_source=oss&utm_medium=header-nav&utm_campaign=consul">Enterprise</a></li>
<li><a href="/security.html">Security</a></li>

78
website/source/layouts/api.erb Normal file
View File

@ -0,0 +1,78 @@
<% wrap_layout :inner do %>
<% content_for :sidebar do %>
<ul class="nav docs-sidenav">
<li<%= sidebar_current("api-overview") %>>
<a href="/api/index.html">API Overview</a>
</li>
<li<%= sidebar_current("api-libraries-and-sdks") %>>
<a href="/api/libraries-and-sdks.html">Libraries &amp; SDKs</a>
</li>
<hr>
<li<%= sidebar_current("api-acls") %>>
<a href="/api/acl.html">ACLs</a>
</li>
<li<%= sidebar_current("api-agent") %>>
<a href="/api/agent.html">Agent</a>
<ul class="nav">
<li<%= sidebar_current("api-agent-check") %>>
<a href="/api/agent/check.html">Checks</a>
</li>
<li<%= sidebar_current("api-agent-service") %>>
<a href="/api/agent/service.html">Services</a>
</li>
</ul>
</li>
<li<%= sidebar_current("api-catalog") %>>
<a href="/api/catalog.html">Catalog</a>
</li>
<li<%= sidebar_current("api-coordinate") %>>
<a href="/api/coordinate.html">Coordinates</a>
</li>
<li<%= sidebar_current("api-event") %>>
<a href="/api/event.html">Events</a>
</li>
<li<%= sidebar_current("api-health") %>>
<a href="/api/health.html">Health</a>
</li>
<li<%= sidebar_current("api-kv-store") %>>
<a href="/api/kv.html">KV Store</a>
</li>
<li<%= sidebar_current("api-operator") %>>
<a href="/api/operator.html">Operator</a>
<ul class="nav">
<li<%= sidebar_current("api-operator-area") %>>
<a href="/api/operator/area.html">Area</a>
</li>
<li<%= sidebar_current("api-operator-autopilot") %>>
<a href="/api/operator/autopilot.html">Autopilot</a>
</li>
<li<%= sidebar_current("api-operator-keyring") %>>
<a href="/api/operator/keyring.html">Keyring</a>
</li>
<li<%= sidebar_current("api-operator-raft") %>>
<a href="/api/operator/raft.html">Raft</a>
</li>
</ul>
</li>
<li<%= sidebar_current("api-query") %>>
<a href="/api/query.html">Prepared Queries</a>
</li>
<li<%= sidebar_current("api-session") %>>
<a href="/api/session.html">Sessions</a>
</li>
<li<%= sidebar_current("api-snapshot") %>>
<a href="/api/snapshot.html">Snapshots</a>
</li>
<li<%= sidebar_current("api-status") %>>
<a href="/api/status.html">Status</a>
</li>
<li<%= sidebar_current("api-txn") %>>
<a href="/api/txn.html">Transactions</a>
</li>
</ul>
<% end %>
<%= yield %>
<% end %>

44
website/source/layouts/docs.erb
View File

@ -175,53 +175,9 @@
<li<%= sidebar_current("docs-agent-running") %>>
<a href="/docs/agent/basics.html">Running and Stopping</a>
</li>
<li<%= sidebar_current("docs-agent-dns") %>>
<a href="/docs/agent/dns.html">DNS Interface</a>
</li>
<li<%= sidebar_current("docs-agent-http") %>>
<a href="/docs/agent/http.html">HTTP API</a>
<ul class="nav">
<li<%= sidebar_current("docs-agent-http-acl") %>>
<a href="/docs/agent/http/acl.html">ACLs</a>
</li>
<li<%= sidebar_current("docs-agent-http-agent") %>>
<a href="/docs/agent/http/agent.html">Agent</a>
</li>
<li<%= sidebar_current("docs-agent-http-catalog") %>>
<a href="/docs/agent/http/catalog.html">Catalog</a>
</li>
<li<%= sidebar_current("docs-agent-http-event") %>>
<a href="/docs/agent/http/event.html">Events</a>
</li>
<li<%= sidebar_current("docs-agent-http-health") %>>
<a href="/docs/agent/http/health.html">Health Checks</a>
</li>
<li<%= sidebar_current("docs-agent-http-kv") %>>
<a href="/docs/agent/http/kv.html">Key/Value Store</a>
</li>
<li<%= sidebar_current("docs-agent-http-coordinate") %>>
<a href="/docs/agent/http/coordinate.html">Network Coordinates</a>
</li>
<li<%= sidebar_current("docs-agent-http-operator") %>>
<a href="/docs/agent/http/operator.html">Operator</a>
</li>
<li<%= sidebar_current("docs-agent-http-query") %>>
<a href="/docs/agent/http/query.html">Prepared Queries</a>
</li>
<li<%= sidebar_current("docs-agent-http-session") %>>
<a href="/docs/agent/http/session.html">Sessions</a>
</li>
<li<%= sidebar_current("docs-agent-http-snapshot") %>>
<a href="/docs/agent/http/snapshot.html">Snapshots</a>
</li>
<li<%= sidebar_current("docs-agent-http-status") %>>
<a href="/docs/agent/http/status.html">Status</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-agent-config") %>>
<a href="/docs/agent/options.html">Configuration</a>
</li>

2
website/source/layouts/intro.erb
View File

@ -55,7 +55,7 @@
<a href="/intro/getting-started/checks.html">Health Checks</a>
</li>
<li<%= sidebar_current("gettingstarted-kv") %>>
<a href="/intro/getting-started/kv.html">Key/Value Data</a>
<a href="/intro/getting-started/kv.html">KV Data</a>
</li>
<li<%= sidebar_current("gettingstarted-ui") %>>
<a href="/intro/getting-started/ui.html">Web UI</a>

4
website/source/layouts/layout.erb
View File

@ -47,7 +47,7 @@
<div class="col-xs-12">
<div class="navbar-header">
<div class="navbar-brand">
<a href="/" data-turbolinks="false">
<a href="/">
<%= inline_svg "logo-text.svg", height: 50, class: "logo" %>
</a>
</div>
@ -63,6 +63,7 @@
<ul class="main-links nav navbar-nav navbar-right">
<li><a href="/intro/index.html">Intro</a></li>
<li><a href="/docs/index.html">Docs</a></li>
<li><a href="/api/index.html">API</a></li>
<li><a href="/community.html">Community</a></li>
<li><a href="https://www.hashicorp.com/consul.html?utm_source=oss&utm_medium=header-nav&utm_campaign=consul">Enterprise</a></li>
<li>
@ -94,6 +95,7 @@
<ul class="footer-links nav navbar-nav">
<li><a href="/intro/index.html">Intro</a></li>
<li><a href="/docs/index.html">Docs</a></li>
<li><a href="/api/index.html">API</a></li>
<li><a href="/community.html">Community</a></li>
<li><a href="/security.html">Security</a></li>
<li><a href="http://demo.consul.io/">Demo</a></li>