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

Merge pull request #10169 from hashicorp/dnephin/streaming-docs 

docs: add streaming to api-docs
This commit is contained in:
Daniel Nephin 2021-06-08 16:13:34 -04:00 committed by GitHub
parent 62facc1a04 85ffcdb8db
commit 175bd6d9aa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 36 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
website/content/api-docs/features/blocking.mdx
View File

@ -82,6 +82,24 @@ cases that must be handled correctly.
[token bucket](https://en.wikipedia.org/wiki/Token_bucket) with burst of 2 is a simple
way to achieve this.
## Streaming backend
The streaming backend, first introduced in Consul 1.10, is a replacement for the long
polling backend. If streaming is supported by an endpoint, it will be used when either
the `index` or `cached` query parameters are set.
When streaming is used, the Consul servers publish change events to a topic. Clients
subscribe to a topic to receive these change events. The clients use the change events to build
a local "materialized view". Clients are then able to handle requests using that view.
Streaming improves on the traditional long polling between clients and servers
by significantly reducing the quantity of data sent between them, while still allowing
clients to handle read requests.
While streaming is a significant optimization over long polling, it will not populate the
`X-Consul-LastContact` or `X-Consul-KnownLeader` response headers, because the required
data is not available to the client.
## Hash-based Blocking Queries
A limited number of agent endpoints also support blocking however because the

27
website/content/api-docs/health.mdx
View File

@ -197,9 +197,9 @@ the following selectors and filter operations being supported:
| `ServiceTags` | In, Not In, Is Empty, Is Not Empty |
| `Status` | Equal, Not Equal, In, Not In, Matches, Not Matches |
## List Nodes for Service
## List Service Instances for Service ((#list-nodes-for-service))
This endpoint returns the nodes providing the service indicated on the path.
This endpoint returns the service instances 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.
@ -213,9 +213,14 @@ The table below shows this endpoint's support for
[agent caching](/api/features/caching), and
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | -------------------- | ------------------------ |
| `YES` | `all` | `background refresh` | `node:read,service:read` |
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| -------------------- | ----------------- | -------------------- | ------------------------ |
| `YES` <sup>1</sup> | `all` | `background refresh` | `node:read,service:read` |
<p>
<sup>1</sup>some query parameters will use the
<a href="/api/features/blocking#streaming-backend">streaming backend</a>
</p>
### Parameters
@ -396,9 +401,9 @@ following selectors and filter operations being supported:
| `Service.Weights.Passing` | Equal, Not Equal |
| `Service.Weights.Warning` | Equal, Not Equal |
## List Nodes for Connect-capable Service
## List Service Instances for Connect-enabled Service
This endpoint returns the nodes providing a
This endpoint returns the service instances providing a
[Connect-capable](/docs/connect) service in a given datacenter.
This will include both proxies and native integrations. A service may
register both Connect-capable and incapable services at the same time,
@ -411,11 +416,11 @@ so this endpoint may be used to filter only the Connect-capable endpoints.
Parameters and response format are the same as
[`/health/service/:service`](/api/health#list-nodes-for-service).
## List Nodes for Ingress Gateways Associated to a Service
## List Service Instances for Ingress Gateways Associated with a Service
-> **1.8.0+:** This API is available in Consul versions 1.8.0 and later.
This endpoint returns the nodes providing a [ingress
This endpoint returns the service instances providing an [ingress
gateway](/docs/connect/ingress-gateway) for a service in a given datacenter.
| Method | Path | Produces |
@ -425,6 +430,10 @@ gateway](/docs/connect/ingress-gateway) for a service in a given datacenter.
Parameters and response format are the same as
[`/health/service/:service`](/api/health#list-nodes-for-service).
**Note** that unlike `/health/connect/:service` and `/health/service/:service` this
endpoint does not support the [streaming backend](/api/features/blocking#streaming-backend).
## List Checks in State
This endpoint returns the checks in the state provided on the path.