diff --git a/website/Makefile b/website/Makefile index 0e83eb946..d7620d1c2 100644 --- a/website/Makefile +++ b/website/Makefile @@ -1,14 +1,24 @@ VERSION?="0.3.22" +build: + @echo "==> Starting build in Docker..." + @docker run \ + --interactive \ + --rm \ + --tty \ + --volume "$(shell pwd):/website" \ + hashicorp/middleman-hashicorp:${VERSION} \ + bundle exec middleman build --verbose --clean + website: @echo "==> Starting website in Docker..." @docker run \ - --interactive \ - --rm \ + --interactive \ + --rm \ --tty \ --publish "4567:4567" \ --publish "35729:35729" \ --volume "$(shell pwd):/website" \ hashicorp/middleman-hashicorp:${VERSION} -.PHONY: website +.PHONY: build website diff --git a/website/source/api/acl.html.md b/website/source/api/acl.html.md new file mode 100644 index 000000000..f31728712 --- /dev/null +++ b/website/source/api/acl.html.md @@ -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: )` - 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: )` - 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: )` - 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. diff --git a/website/source/api/agent.html.md b/website/source/api/agent.html.md new file mode 100644 index 000000000..cf8ea8d5b --- /dev/null +++ b/website/source/api/agent.html.md @@ -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: )` - 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: )` - 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 +``` diff --git a/website/source/api/agent/check.html.md b/website/source/api/agent/check.html.md new file mode 100644 index 000000000..1a413e855 --- /dev/null +++ b/website/source/api/agent/check.html.md @@ -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: )` - 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 +``` diff --git a/website/source/api/agent/service.html.md b/website/source/api/agent/service.html.md new file mode 100644 index 000000000..0310e0fc0 --- /dev/null +++ b/website/source/api/agent/service.html.md @@ -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: )` - 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: 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: )` - 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: )` - Specifies the ID of the service to put + in maintenance mode. This is specified as part of the URL. + +- `enable` `(bool: )` - 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 +``` diff --git a/website/source/api/catalog.html.md b/website/source/api/catalog.html.md new file mode 100644 index 000000000..c784663a2 --- /dev/null +++ b/website/source/api/catalog.html.md @@ -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: )` - Specifies the node ID to register. + +- `Address` `(string: )` - Specifies the address to register. + +- `Datacenter` `(string: "")` - Specifies the datacenter, which defaults to the + agent's datacenter if not provided. + +- `TaggedAddresses` `(map: nil)` - Specifies the tagged + addresses. + +- `Meta` `(map: 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: )` - 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: )` - 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: )` - 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 + } + } +} +``` diff --git a/website/source/api/coordinate.html.md b/website/source/api/coordinate.html.md new file mode 100644 index 000000000..14800b5c3 --- /dev/null +++ b/website/source/api/coordinate.html.md @@ -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] + } + } +] +``` diff --git a/website/source/api/event.html.md b/website/source/api/event.html.md new file mode 100644 index 000000000..b60b4daa5 --- /dev/null +++ b/website/source/api/event.html.md @@ -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: )` - 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: )` - 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. diff --git a/website/source/api/health.html.markdown b/website/source/api/health.html.markdown new file mode 100644 index 000000000..b0ce02200 --- /dev/null +++ b/website/source/api/health.html.markdown @@ -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: )` - 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: )` - 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: )` - 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: )` - 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" + } +] +``` diff --git a/website/source/api/index.html.md b/website/source/api/index.html.md new file mode 100644 index 000000000..beb188abc --- /dev/null +++ b/website/source/api/index.html.md @@ -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. diff --git a/website/source/api/kv.html.md b/website/source/api/kv.html.md new file mode 100644 index 000000000..2fdf38a3b --- /dev/null +++ b/website/source/api/kv.html.md @@ -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������z^�-�ɑj�q����#u�-R�r��T�D��٬�Y��l,�ιK��Fm��}�#e�� +``` + +(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 +``` diff --git a/website/source/api/libraries-and-sdks.html.md b/website/source/api/libraries-and-sdks.html.md new file mode 100644 index 000000000..ca65e3493 --- /dev/null +++ b/website/source/api/libraries-and-sdks.html.md @@ -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. + +
    +
  • + api - Official Go client for the Consul HTTP API +
    • +
  • + consulate - Python client for the Consul HTTP API +
    • +
  • + python-consul - Python client for the Consul HTTP API +
    • +
  • + consul-kv - Python 3 client for the Consul KV-store +
    • +
  • + consul-php-sdk - PHP client for the Consul HTTP API +
    • +
  • + php-consul-api - GO-like PHP Client for the Consul HTTP API +
    • +
  • + envoy - Consul Clojure client with watchers and other goodies +
    • +
  • + clj-consul-catalog - Clojure discovery client for the Consul HTTP API +
    • +
  • + scala-consul - Scala client for the Consul HTTP API +
    • +
  • + consul-client - Java client for the Consul HTTP API +
    • +
  • + consul-api - Java client for the Consul HTTP API +
    • +
  • + discovery - Erlang/OTP client for the Consul HTTP API +
    • +
  • + consul-client - Ruby client for the Consul HTTP API +
    • +
  • + diplomat - Ruby library to query Consul's KV-store and services directory +
    • +
  • + node-consul - Node.js client for the Consul HTTP API +
    • +
  • + Consul.NET - C# client for the Consul HTTP API +
    • +
  • + Consul - Perl client for the Consul HTTP API +
    • +
  • + CondenserDotNet - C# an opinionated API for .NET that provides higher level functionality for services using the HTTP API +
    • +
diff --git a/website/source/api/operator.html.md b/website/source/api/operator.html.md new file mode 100644 index 000000000..21fe2d9ba --- /dev/null +++ b/website/source/api/operator.html.md @@ -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. diff --git a/website/source/api/operator/area.html.md b/website/source/api/operator/area.html.md new file mode 100644 index 000000000..bfccd68f7 --- /dev/null +++ b/website/source/api/operator/area.html.md @@ -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: )` - 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: 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: )` - 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: )` - 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: )` - 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: )` - 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). diff --git a/website/source/api/operator/autopilot.html.md b/website/source/api/operator/autopilot.html.md new file mode 100644 index 000000000..5edfffb11 --- /dev/null +++ b/website/source/api/operator/autopilot.html.md @@ -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. diff --git a/website/source/api/operator/keyring.html.md b/website/source/api/operator/keyring.html.md new file mode 100644 index 000000000..0b4dacc92 --- /dev/null +++ b/website/source/api/operator/keyring.html.md @@ -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: )` - 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: )` - 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: )` - 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 +``` diff --git a/website/source/api/operator/raft.html.md b/website/source/api/operator/raft.html.md new file mode 100644 index 000000000..486680893 --- /dev/null +++ b/website/source/api/operator/raft.html.md @@ -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: )` - 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 +``` diff --git a/website/source/api/query.html.md b/website/source/api/query.html.md new file mode 100644 index 000000000..2a06f0b58 --- /dev/null +++ b/website/source/api/query.html.md @@ -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: )` - Specifies the structure to define the query's behavior. + + - `Service` `(string: )` - 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: 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: 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: 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": "", + "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: )` - 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: )` - 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: )` - 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`1 | + +1 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: )` - 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: )` - 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": "", + "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"} + } + } +} +``` diff --git a/website/source/api/session.html.md b/website/source/api/session.html.md new file mode 100644 index 000000000..6b061da9d --- /dev/null +++ b/website/source/api/session.html.md @@ -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: "")` - 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: 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: )` - 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: )` - 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: )` - 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: )` - 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. diff --git a/website/source/api/snapshot.html.md b/website/source/api/snapshot.html.md new file mode 100644 index 000000000..fe5ed5963 --- /dev/null +++ b/website/source/api/snapshot.html.md @@ -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 + +``` + +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. diff --git a/website/source/api/status.html.md b/website/source/api/status.html.md new file mode 100644 index 000000000..6b27c92c0 --- /dev/null +++ b/website/source/api/status.html.md @@ -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" +] +``` diff --git a/website/source/api/txn.markdown b/website/source/api/txn.markdown new file mode 100644 index 000000000..2aaaabdc6 --- /dev/null +++ b/website/source/api/txn.markdown @@ -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`1 | `key:read,key:write`2 | + +1 For read-only transactions +
+2 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: )` - Specifies the type of operation to perform. + Please see the table below for available verbs. + + - `Key` `(string: )` - 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": "", + "Key": "", + "Value": "", + "Flags": , + "Index": , + "Session": "" + } + } +] +``` + +### 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": , + "Key": "", + "Flags": , + "Value": "", + "CreateIndex": , + "ModifyIndex": + } + } + ], + "Errors": [ + { + "OpIndex": , + "What": "" + }, + ] +} +``` + +- `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/` 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` | | diff --git a/website/source/docs/agent/checks.html.markdown b/website/source/docs/agent/checks.html.markdown index 20a205ce1..3e0dcd789 100644 --- a/website/source/docs/agent/checks.html.markdown +++ b/website/source/docs/agent/checks.html.markdown @@ -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 diff --git a/website/source/docs/agent/dns.html.markdown b/website/source/docs/agent/dns.html.markdown index 9914051da..7e33ade73 100644 --- a/website/source/docs/agent/dns.html.markdown +++ b/website/source/docs/agent/dns.html.markdown @@ -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. diff --git a/website/source/docs/agent/http.html.markdown b/website/source/docs/agent/http.html.markdown deleted file mode 100644 index 445d00eca..000000000 --- a/website/source/docs/agent/http.html.markdown +++ /dev/null @@ -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. - -## 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. - - -## 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. diff --git a/website/source/docs/agent/http/acl.html.markdown b/website/source/docs/agent/http/acl.html.markdown deleted file mode 100644 index e11299556..000000000 --- a/website/source/docs/agent/http/acl.html.markdown +++ /dev/null @@ -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/`](#acl_destroy): Destroys a given token -* [`/v1/acl/info/`](#acl_info): Queries the policy of a given token -* [`/v1/acl/clone/`](#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 - -### /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" -} -``` - -### /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). - -### /v1/acl/destroy/\ - -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. - -### /v1/acl/info/\ - -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. - -### /v1/acl/clone/\ - -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" -} -``` - -### /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": "..." - }, - ... -] -``` - -### /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. diff --git a/website/source/docs/agent/http/agent.html.markdown b/website/source/docs/agent/http/agent.html.markdown deleted file mode 100644 index 166cc954b..000000000 --- a/website/source/docs/agent/http/agent.html.markdown +++ /dev/null @@ -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/
`](#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/`](#agent_force_leave): Forces removal of a node -* [`/v1/agent/check/register`](#agent_check_register) : Registers a new local check -* [`/v1/agent/check/deregister/`](#agent_check_deregister) : Deregisters a local check -* [`/v1/agent/check/pass/`](#agent_check_pass) : Marks a local check as passing -* [`/v1/agent/check/warn/`](#agent_check_warn) : Marks a local check as warning -* [`/v1/agent/check/fail/`](#agent_check_fail) : Marks a local check as critical -* [`/v1/agent/check/update/`](#agent_check_update) : Updates a local check -* [`/v1/agent/service/register`](#agent_service_register) : Registers a new local service -* [`/v1/agent/service/deregister/`](#agent_service_deregister) : Deregisters a local service -* [`/v1/agent/service/maintenance/`](#agent_service_maintenance) : Manages service maintenance mode - -### /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" - } -} -``` - -### /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 - } -} -``` - -### /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 - } -] -``` - -### /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", - } -} -``` - -### /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. - -### /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. - -### /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. - -### /v1/agent/join/\ - -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. - -### /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. - -### /v1/agent/force-leave/\ - -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. - -### /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=`, 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. - -### /v1/agent/check/deregister/\ - -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. - -### /v1/agent/check/pass/\ - -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. - -### /v1/agent/check/warn/\ - -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. - -### /v1/agent/check/fail/\ - -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. - -### /v1/agent/check/update/\ - -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. - -### /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:`. 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=`, 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. - -### /v1/agent/service/deregister/\ - -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. - -### /v1/agent/service/maintenance/\ - -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. diff --git a/website/source/docs/agent/http/catalog.html.markdown b/website/source/docs/agent/http/catalog.html.markdown deleted file mode 100644 index 1ef062cdf..000000000 --- a/website/source/docs/agent/http/catalog.html.markdown +++ /dev/null @@ -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/`](#catalog_service) : Lists the nodes in a given service -* [`/v1/catalog/node/`](#catalog_node) : Lists the services provided by a node - -The `nodes` and `services` endpoints support blocking queries and -tunable consistency modes. - -### /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. - -### /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. - -### /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. - -### /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. - -### /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. - -### /v1/catalog/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. - -### /v1/catalog/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. diff --git a/website/source/docs/agent/http/coordinate.html.markdown b/website/source/docs/agent/http/coordinate.html.markdown deleted file mode 100644 index be1ff8010..000000000 --- a/website/source/docs/agent/http/coordinate.html.markdown +++ /dev/null @@ -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 - -### /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. - -### /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. diff --git a/website/source/docs/agent/http/event.html.markdown b/website/source/docs/agent/http/event.html.markdown deleted file mode 100644 index f1b1554c6..000000000 --- a/website/source/docs/agent/http/event.html.markdown +++ /dev/null @@ -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/`](#event_fire): Fires a new user event -* [`/v1/event/list`](#event_list): Lists the most recent events an agent has seen. - -### /v1/event/fire/\ - -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. - -### /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 - }, - ... -] -``` diff --git a/website/source/docs/agent/http/health.html.markdown b/website/source/docs/agent/http/health.html.markdown deleted file mode 100644 index 8481d1397..000000000 --- a/website/source/docs/agent/http/health.html.markdown +++ /dev/null @@ -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/`](#health_node): Returns the health info of a node -* [`/v1/health/checks/`](#health_checks): Returns the checks of a service -* [`/v1/health/service/`](#health_service): Returns the nodes and health info of a service -* [`/v1/health/state/`](#health_state): Returns the checks in a given state - -All of the health endpoints support blocking queries and all consistency modes. - -### /v1/health/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. - -### /v1/health/checks/\ - -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. - -### /v1/health/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. - -### /v1/health/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. diff --git a/website/source/docs/agent/http/kv.html.markdown b/website/source/docs/agent/http/kv.html.markdown deleted file mode 100644 index 8d7504f32..000000000 --- a/website/source/docs/agent/http/kv.html.markdown +++ /dev/null @@ -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/`](#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 - -### /v1/kv/<key> - -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=` : 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=` : 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=` : 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=` : 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=` : 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. - -### /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": "", - "Key": "", - "Value": "", - "Flags": , - "Index": , - "Session": "" - } - }, - ... -] -``` - -`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): - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
VerbOperationKeyValueFlagsIndexSession
setSets the `Key` to the given `Value`.XXO
casSets 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`.XXOX
lockLocks 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.XXOX
unlockUnlocks the `Key` with the given `Session`. The `Key` will only release the lock if the `Session` is valid and currently has it locked.XXOX
getGets 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.X
get-treeGets 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.X
check-indexFails the transaction if `Key` does not have a modify index equal to `Index`.XX
check-sessionFails the transaction if `Key` is not currently locked by `Session`.XX
deleteDeletes the `Key`.X
delete-treeDeletes all keys with a prefix of`Key`.X
delete-casDeletes the `Key` with check-and-set semantics. The `Key` will only be deleted if its current modify index matches the supplied `Index`.XX
- -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": , - "Key": "", - "Flags": , - "Value": "", - "CreateIndex": , - "ModifyIndex": - } - }, - ... - ], - "Errors": [ - { - "OpIndex": , - "What": "" - }, - ... - ] -} -``` - -`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/` 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. diff --git a/website/source/docs/agent/http/operator.html.markdown b/website/source/docs/agent/http/operator.html.markdown deleted file mode 100644 index e7697683c..000000000 --- a/website/source/docs/agent/http/operator.html.markdown +++ /dev/null @@ -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 - -### /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=` 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. - -### /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 - -### /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/`](#area-specific): Delete an area -* [`/v1/operator/area//join`](#area-join): Join Consul servers into an area -* [`/v1/operator/area//members`](#area-members): List Consul servers in an area - -### /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" ] - }, - ... -] -``` - -### /v1/operator/area/\ - -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. - -### /v1/operator/area/\/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. - -### /v1/operator/area/\/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 - -### /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. - -### /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. diff --git a/website/source/docs/agent/http/query.html.markdown b/website/source/docs/agent/http/query.html.markdown deleted file mode 100644 index 6dfe66d46..000000000 --- a/website/source/docs/agent/http/query.html.markdown +++ /dev/null @@ -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/`](#specific): Updates, fetches, or deletes - a prepared query -* [`/v1/query//execute`](#execute): Executes a - prepared query by its ID or optional name -* [`/v1/query//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. - -### /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. - - -`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. - - -`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" -} -``` - -Prepared Query Templates - -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 `` 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": "", - "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 - } - } -] -``` - -### /v1/query/\ - -The query-specific endpoint supports the `GET`, `PUT`, and `DELETE` methods. The -\ 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 `` 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. - -### /v1/query/\/execute - -The query execute endpoint supports only the `GET` method and is used to -execute a prepared query. The \ 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 -near parameter 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. - -### /v1/query/\/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 `` 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": "", - "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`. diff --git a/website/source/docs/agent/http/session.html.markdown b/website/source/docs/agent/http/session.html.markdown deleted file mode 100644 index 8b82bdda6..000000000 --- a/website/source/docs/agent/http/session.html.markdown +++ /dev/null @@ -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_destroy): Destroys a given session -* [`/v1/session/info/`](#session_info): Queries a given session -* [`/v1/session/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. - -### /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" -} -``` - -### /v1/session/destroy/\ - -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. - -### /v1/session/info/\ - -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. - -### /v1/session/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. - -### /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. - -### /v1/session/renew/\ - -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. - diff --git a/website/source/docs/agent/http/snapshot.html.markdown b/website/source/docs/agent/http/snapshot.html.markdown deleted file mode 100644 index 52df4a299..000000000 --- a/website/source/docs/agent/http/snapshot.html.markdown +++ /dev/null @@ -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. - -### /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. diff --git a/website/source/docs/agent/http/status.html.markdown b/website/source/docs/agent/http/status.html.markdown deleted file mode 100644 index d012fa37c..000000000 --- a/website/source/docs/agent/http/status.html.markdown +++ /dev/null @@ -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 - -### /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" -``` - -### /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. diff --git a/website/source/docs/agent/options.html.markdown b/website/source/docs/agent/options.html.markdown index 30610b800..a30a44930 100644 --- a/website/source/docs/agent/options.html.markdown +++ b/website/source/docs/agent/options.html.markdown @@ -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 data directory so that it will remain the same across agent restarts. This is currently only exposed via - /v1/agent/self, - /v1/catalog, and - /v1/health endpoints, but future versions of + /v1/agent/self, + /v1/catalog, and + /v1/health endpoints, but future versions of Consul will use this to better manage cluster changes, especially for Consul servers. * `-node-meta` - 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". * `acl_agent_master_token` - - Used to access agent endpoints that require agent read + Used to access agent endpoints 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 `acl_enforce_version_8` @@ -1033,11 +1033,11 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass

The following endpoints translate addresses:
- * [`/v1/catalog/nodes`](/docs/agent/http/catalog.html#catalog_nodes) - * [`/v1/catalog/node/`](/docs/agent/http/catalog.html#catalog_node) - * [`/v1/catalog/service/`](/docs/agent/http/catalog.html#catalog_service) - * [`/v1/health/service/`](/docs/agent/http/health.html#health_service) - * [`/v1/query//execute`](/docs/agent/http/query.html#execute) + * [`/v1/catalog/nodes`](/api/catalog.html#catalog_nodes) + * [`/v1/catalog/node/`](/api/catalog.html#catalog_node) + * [`/v1/catalog/service/`](/api/catalog.html#catalog_service) + * [`/v1/health/service/`](/api/health.html#health_service) + * [`/v1/query//execute`](/api/query.html#execute) * `ui` - Equivalent to the [`-ui`](#_ui) command-line flag. diff --git a/website/source/docs/agent/services.html.markdown b/website/source/docs/agent/services.html.markdown index efc50cab1..154fcd015 100644 --- a/website/source/docs/agent/services.html.markdown +++ b/website/source/docs/agent/services.html.markdown @@ -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 diff --git a/website/source/docs/commands/index.html.markdown b/website/source/docs/commands/index.html.markdown index 275f17a9b..435dc5699 100644 --- a/website/source/docs/commands/index.html.markdown +++ b/website/source/docs/commands/index.html.markdown @@ -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 diff --git a/website/source/docs/commands/kv.html.markdown b/website/source/docs/commands/kv.html.markdown index 6b3e8aa89..bb8029c7a 100644 --- a/website/source/docs/commands/kv.html.markdown +++ b/website/source/docs/commands/kv.html.markdown @@ -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 diff --git a/website/source/docs/commands/kv/delete.html.markdown.erb b/website/source/docs/commands/kv/delete.html.markdown.erb index 05295cbf8..9bf234a67 100644 --- a/website/source/docs/commands/kv/delete.html.markdown.erb +++ b/website/source/docs/commands/kv/delete.html.markdown.erb @@ -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 diff --git a/website/source/docs/commands/kv/export.html.markdown.erb b/website/source/docs/commands/kv/export.html.markdown.erb index 06bed5fa4..d15f415cb 100644 --- a/website/source/docs/commands/kv/export.html.markdown.erb +++ b/website/source/docs/commands/kv/export.html.markdown.erb @@ -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. diff --git a/website/source/docs/commands/kv/get.html.markdown.erb b/website/source/docs/commands/kv/get.html.markdown.erb index b14ec4a57..a140594b1 100644 --- a/website/source/docs/commands/kv/get.html.markdown.erb +++ b/website/source/docs/commands/kv/get.html.markdown.erb @@ -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 diff --git a/website/source/docs/commands/kv/put.html.markdown.erb b/website/source/docs/commands/kv/put.html.markdown.erb index 68189f772..28e8071eb 100644 --- a/website/source/docs/commands/kv/put.html.markdown.erb +++ b/website/source/docs/commands/kv/put.html.markdown.erb @@ -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=` - Unsigned integer value to assign to this key-value pair. This +* `-flags=` - 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 diff --git a/website/source/docs/commands/lock.html.markdown.erb b/website/source/docs/commands/lock.html.markdown.erb index c5069c8a0..1b9739a7f 100644 --- a/website/source/docs/commands/lock.html.markdown.erb +++ b/website/source/docs/commands/lock.html.markdown.erb @@ -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. diff --git a/website/source/docs/commands/operator.html.markdown.erb b/website/source/docs/commands/operator.html.markdown.erb index 049d2b9f4..58167978f 100644 --- a/website/source/docs/commands/operator.html.markdown.erb +++ b/website/source/docs/commands/operator.html.markdown.erb @@ -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 diff --git a/website/source/docs/commands/snapshot.html.markdown b/website/source/docs/commands/snapshot.html.markdown index 2c1464372..2334be23f 100644 --- a/website/source/docs/commands/snapshot.html.markdown +++ b/website/source/docs/commands/snapshot.html.markdown @@ -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 diff --git a/website/source/docs/commands/snapshot/agent.html.markdown.erb b/website/source/docs/commands/snapshot/agent.html.markdown.erb index fdf34ec3d..88958dc2f 100644 --- a/website/source/docs/commands/snapshot/agent.html.markdown.erb +++ b/website/source/docs/commands/snapshot/agent.html.markdown.erb @@ -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. diff --git a/website/source/docs/commands/snapshot/inspect.html.markdown.erb b/website/source/docs/commands/snapshot/inspect.html.markdown.erb index d249c06f5..2bed91c01 100644 --- a/website/source/docs/commands/snapshot/inspect.html.markdown.erb +++ b/website/source/docs/commands/snapshot/inspect.html.markdown.erb @@ -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. \ No newline at end of file diff --git a/website/source/docs/commands/snapshot/restore.html.markdown.erb b/website/source/docs/commands/snapshot/restore.html.markdown.erb index 27c0f6e5b..9fb89f27d 100644 --- a/website/source/docs/commands/snapshot/restore.html.markdown.erb +++ b/website/source/docs/commands/snapshot/restore.html.markdown.erb @@ -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. diff --git a/website/source/docs/commands/snapshot/save.html.markdown.erb b/website/source/docs/commands/snapshot/save.html.markdown.erb index 14033c8e1..5388bdc7f 100644 --- a/website/source/docs/commands/snapshot/save.html.markdown.erb +++ b/website/source/docs/commands/snapshot/save.html.markdown.erb @@ -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. diff --git a/website/source/docs/faq.html.markdown b/website/source/docs/faq.html.markdown index cbbfcd1a9..02eb9a204 100644 --- a/website/source/docs/faq.html.markdown +++ b/website/source/docs/faq.html.markdown @@ -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 diff --git a/website/source/docs/guides/areas.html.markdown b/website/source/docs/guides/areas.html.markdown index 5a33a0494..7a88f1cb6 100644 --- a/website/source/docs/guides/areas.html.markdown +++ b/website/source/docs/guides/areas.html.markdown @@ -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 diff --git a/website/source/docs/guides/autopilot.html.markdown b/website/source/docs/guides/autopilot.html.markdown index d22f49218..72360d050 100644 --- a/website/source/docs/guides/autopilot.html.markdown +++ b/website/source/docs/guides/autopilot.html.markdown @@ -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: ``` diff --git a/website/source/docs/guides/datacenters.html.markdown b/website/source/docs/guides/datacenters.html.markdown index f4aeff21a..66db8e75c 100644 --- a/website/source/docs/guides/datacenters.html.markdown +++ b/website/source/docs/guides/datacenters.html.markdown @@ -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 diff --git a/website/source/docs/guides/dns-cache.html.markdown b/website/source/docs/guides/dns-cache.html.markdown index 69db198d6..0f3dfcb2d 100644 --- a/website/source/docs/guides/dns-cache.html.markdown +++ b/website/source/docs/guides/dns-cache.html.markdown @@ -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 diff --git a/website/source/docs/guides/external.html.markdown b/website/source/docs/guides/external.html.markdown index 3e190be8d..53032768a 100644 --- a/website/source/docs/guides/external.html.markdown +++ b/website/source/docs/guides/external.html.markdown @@ -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). diff --git a/website/source/docs/guides/index.html.markdown b/website/source/docs/guides/index.html.markdown index 5007a3098..3ef1eba2b 100644 --- a/website/source/docs/guides/index.html.markdown +++ b/website/source/docs/guides/index.html.markdown @@ -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. diff --git a/website/source/docs/guides/leader-election.html.markdown b/website/source/docs/guides/leader-election.html.markdown index 1a97a627a..d80f73621 100644 --- a/website/source/docs/guides/leader-election.html.markdown +++ b/website/source/docs/guides/leader-election.html.markdown @@ -32,7 +32,7 @@ service//leader We'll abbreviate this pattern as simply `` 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=` query parameter. The `` 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 ``. This will look something like (note that `` 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 http://localhost:8500/v1/kv/?acquire= @@ -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 diff --git a/website/source/docs/guides/semaphore.html.markdown b/website/source/docs/guides/semaphore.html.markdown index 6e5870b8c..7fe1cd7de 100644 --- a/website/source/docs/guides/semaphore.html.markdown +++ b/website/source/docs/guides/semaphore.html.markdown @@ -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//lock/ We'll abbreviate this pattern as simply `` 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 http://localhost:8500/v1/kv//?acquire=` 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. diff --git a/website/source/docs/install/index.html.md b/website/source/docs/install/index.html.md new file mode 100644 index 000000000..07dda7b5d --- /dev/null +++ b/website/source/docs/install/index.html.md @@ -0,0 +1,73 @@ +--- +layout: "docs" +page_title: "Install Consul" +sidebar_current: "docs-install-install" +description: |- + Installing Consul is simple. You can download a precompiled binary or compile + from source. This page details both methods. +--- + +# Install Consul + +Installing Consul is simple. There are two approaches to installing Consul: + +1. Using a [precompiled binary](#precompiled-binaries) + +1. Installing [from source](#compiling-from-source) + +Downloading a precompiled binary is easiest, and we provide downloads over TLS +along with SHA256 sums to verify the binary. We also distribute a PGP signature +with the SHA256 sums that can be verified. + +## Precompiled Binaries + +To install the precompiled binary, [download](/downloads.html) the appropriate +package for your system. Consul is currently packaged as a zip file. We do not +have any near term plans to provide system packages. + +Once the zip is downloaded, unzip it into any directory. The `consul` binary +inside is all that is necessary to run Consul (or `consul.exe` for Windows). Any +additional files, if any, aren't required to run Consul. + +Copy the binary to anywhere on your system. If you intend to access it from the +command-line, make sure to place it somewhere on your `PATH`. + +## Compiling from Source + +To compile from source, you will need [Go](https://golang.org) installed and +configured properly (including a `GOPATH` environment variable set), as well as +a copy of [`git`](https://www.git-scm.com/) in your `PATH`. + + 1. Clone the Consul repository from GitHub into your `GOPATH`: + + ```shell + $ mkdir -p $GOPATH/src/github.com/hashicorp && cd $! + $ git clone https://github.com/hashicorp/consul.git + $ cd consul + ``` + + 1. Bootstrap the project. This will download and compile libraries and tools + needed to compile Consul: + + ```shell + $ make bootstrap + ``` + + 1. Build Consul for your current system and put the binary in `./bin/` + (relative to the git checkout). The `make dev` target is just a shortcut that + builds `consul` for only your local build environment (no cross-compiled + targets). + + ```shell + $ make dev + ``` + +## Verifying the Installation + +To verify Consul is properly installed, run `consul -v` on your system. You +should see help output. If you are executing it from the command line, make sure +it is on your PATH or you may get an error about Consul not being found. + +```shell +$ consul -v +``` diff --git a/website/source/docs/internals/acl.html.markdown b/website/source/docs/internals/acl.html.markdown index 4159c26fa..2435865b1 100644 --- a/website/source/docs/internals/acl.html.markdown +++ b/website/source/docs/internals/acl.html.markdown @@ -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. diff --git a/website/source/docs/internals/coordinates.html.markdown b/website/source/docs/internals/coordinates.html.markdown index 476c82d22..b79155ca1 100644 --- a/website/source/docs/internals/coordinates.html.markdown +++ b/website/source/docs/internals/coordinates.html.markdown @@ -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": { diff --git a/website/source/docs/internals/sessions.html.markdown b/website/source/docs/internals/sessions.html.markdown index da100decc..2f7049423 100644 --- a/website/source/docs/internals/sessions.html.markdown +++ b/website/source/docs/internals/sessions.html.markdown @@ -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 diff --git a/website/source/docs/upgrade-specific.html.markdown b/website/source/docs/upgrade-specific.html.markdown index 0da7f5264..49b838e3f 100644 --- a/website/source/docs/upgrade-specific.html.markdown +++ b/website/source/docs/upgrade-specific.html.markdown @@ -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 diff --git a/website/source/downloads_tools.html.erb b/website/source/downloads_tools.html.erb index 4b31c71ca..b03b388a8 100644 --- a/website/source/downloads_tools.html.erb +++ b/website/source/downloads_tools.html.erb @@ -32,67 +32,6 @@ description: |- -

Consul SDK

-

- These Consul SDK are created and managed by the amazing members of the Consul community: -

-
    -
  • - api - Official Go client for the Consul HTTP API -
    • -
  • - consulate - Python client for the Consul HTTP API -
    • -
  • - python-consul - Python client for the Consul HTTP API -
    • -
  • - consul-kv - Python 3 client for the Consul KV-store -
    • -
  • - consul-php-sdk - PHP client for the Consul HTTP API -
    • -
  • - php-consul-api - GO-like PHP Client for the Consul HTTP API -
    • -
  • - envoy - Consul Clojure client with watchers and other goodies -
    • -
  • - clj-consul-catalog - Clojure discovery client for the Consul HTTP API -
    • -
  • - scala-consul - Scala client for the Consul HTTP API -
    • -
  • - consul-client - Java client for the Consul HTTP API -
    • -
  • - consul-api - Java client for the Consul HTTP API -
    • -
  • - discovery - Erlang/OTP client for the Consul HTTP API -
    • -
  • - consul-client - Ruby client for the Consul HTTP API -
    • -
  • - diplomat - Ruby library to query Consul's KV-store and services directory -
    • -
  • - node-consul - Node.js client for the Consul HTTP API -
    • -
  • - Consul.NET - C# client for the Consul HTTP API -
    • -
  • - Consul - Perl client for the Consul HTTP API -
    • -
  • - CondenserDotNet - C# an opinionated API for .NET that provides higher level functionality for services using the HTTP API -
    • -
-

Community Tools

These Consul tools are created and managed by the amazing members of the Consul community: diff --git a/website/source/index.html.erb b/website/source/index.html.erb index 9424b531d..01672f0a6 100644 --- a/website/source/index.html.erb +++ b/website/source/index.html.erb @@ -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 %>

-

Key/Value Storage

+

KV Storage

Flexible key/value store for dynamic configuration, feature flagging, coordination, leader election and more. Long poll for near-instant diff --git a/website/source/intro/getting-started/checks.html.markdown b/website/source/intro/getting-started/checks.html.markdown index 6b0a70474..d4e37c4b8 100644 --- a/website/source/intro/getting-started/checks.html.markdown +++ b/website/source/intro/getting-started/checks.html.markdown @@ -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. diff --git a/website/source/intro/getting-started/install.html.markdown b/website/source/intro/getting-started/install.html.markdown index 95660d32e..df01f91c0 100644 --- a/website/source/intro/getting-started/install.html.markdown +++ b/website/source/intro/getting-started/install.html.markdown @@ -8,32 +8,26 @@ description: |- # Install Consul -Consul must first be installed on every node that will be a member of the -Consul cluster. To make installation easy, Consul is distributed as a -[binary package](/downloads.html) for all supported platforms and -architectures. This page will not cover how to compile Consul from -source. +Consul must first be installed on your machine. Consul is distributed as a +[binary package](/downloads.html) for all supported platforms and architectures. +This page will not cover how to compile Consul from source, but compiling from +source is covered in the [documentation](/docs/index.html) for those who want to +be sure they're compiling source they trust into the final binary. ## Installing Consul To install Consul, find the [appropriate package](/downloads.html) for -your system and download it. Consul is packaged as a "zip" archive. +your system and download it. Consul is packaged as a zip archive. -After downloading Consul, unzip the package. Copy the `consul` binary to -somewhere on the `PATH` so that it can be executed. On Unix systems, -`~/bin` and `/usr/local/bin` are common installation directories, -depending on if you want to restrict the install to a single user or -expose it to the entire system. On Windows systems, you can put it -wherever you would like, as long as that location is on the `%PATH%`. +After downloading Consul, unzip the package. Consul runs as a single binary +named `consul`. Any other files in the package can be safely removed and +Consul will still function. -### OS X - -If you are using [homebrew](http://brew.sh/#install) as a package manager, -you can install consul with: - -```text -$ brew install consul -``` +The final step is to make sure that the `consul` binary is available on the `PATH`. +See [this page](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux) +for instructions on setting the PATH on Linux and Mac. +[This page](https://stackoverflow.com/questions/1618280/where-can-i-set-path-to-make-exe-on-windows) +contains instructions for setting the PATH on Windows. ## Verifying the Installation @@ -48,17 +42,8 @@ usage: consul [--version] [--help] [] Available commands are: agent Runs a Consul agent event Fire a new event - exec Executes a command on Consul nodes - force-leave Forces a member of the cluster to enter the "left" state - info Provides debugging information for operators - join Tell Consul agent to join cluster - keygen Generates a new encryption key - leave Gracefully leaves the Consul cluster and shuts down - members Lists the members of a Consul cluster - monitor Stream logs from a Consul agent - reload Triggers the agent to reload configuration files - version Prints the Consul version - watch Watch for changes in Consul + +# ... ``` If you get an error that `consul` could not be found, your `PATH` diff --git a/website/source/intro/getting-started/kv.html.markdown b/website/source/intro/getting-started/kv.html.markdown index 0b9a30fc2..63cd75192 100644 --- a/website/source/intro/getting-started/kv.html.markdown +++ b/website/source/intro/getting-started/kv.html.markdown @@ -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 diff --git a/website/source/intro/index.html.markdown b/website/source/intro/index.html.markdown index 40504803b..0b1b6eb62 100644 --- a/website/source/intro/index.html.markdown +++ b/website/source/intro/index.html.markdown @@ -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. diff --git a/website/source/layouts/_sidebar.erb b/website/source/layouts/_sidebar.erb index 8d949daf0..30b3bbd13 100644 --- a/website/source/layouts/_sidebar.erb +++ b/website/source/layouts/_sidebar.erb @@ -8,6 +8,7 @@