mirror of https://github.com/status-im/consul.git
docs: move streaming docs to blocking query page
This commit is contained in:
Daniel Nephin
parent
c46f4391f0
commit
8b9ec040c3
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,43 +0,0 @@
|
|||
---
|
||||
layout: api
|
||||
page_title: Streaming
|
||||
description: |-
|
||||
Some API endpoints support a feature known as "streaming". Change events
|
||||
are published to a stream topic, allowing clients to build a localized
|
||||
view, and removing the need to send full state-of-the-world responses
|
||||
every time data changes.
|
||||
---
|
||||
|
||||
# Streaming
|
||||
|
||||
A few endpoints in Consul support a feature known as "streaming". With streaming
|
||||
the Consul servers publish change events to a topic. Clients can 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 [blocking queries][1] by significantly reducing the quantity
|
||||
of data sent from servers to clients, while still allowing clients to handle
|
||||
read requests.
|
||||
|
||||
Streaming, first introduced in Consul 1.10, is a replacement for [blocking queries][1],
|
||||
and is only supported by a small number of endpoints. If streaming is supported by an
|
||||
endpoint, it will be used when either the `index` or `cached` query parameters are set.
|
||||
|
||||
Endpoints that support streaming 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 `index` is set, 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.
|
||||
|
||||
Note that streaming does not support all query parameters used by blocking queries, and
|
||||
that some response headers (ex: `X-Consul-LastContact` and `X-Consul-KnownLeader`) are not
|
||||
set because the data is not available.
|
||||
|
||||
[1]: /api-docs/features/blocking
|
||||
|
|
@ -197,7 +197,7 @@ 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 Service Instances for Service ((list-nodes-for-service))
|
||||
## List Service Instances for Service ((#list-nodes-for-service))
|
||||
|
||||
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
|
||||
|
|
@ -208,15 +208,19 @@ incorporating the use of health checks.
|
|||
| `GET` | `/health/service/:service` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[streaming](/api/features/streaming),
|
||||
[blocking queries](/api/features/blocking),
|
||||
[consistency modes](/api/features/consistency),
|
||||
[agent caching](/api/features/caching), and
|
||||
[required ACLs](/api#authentication).
|
||||
|
||||
| Streaming | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
||||
| ----------| ---------------- | ----------------- | -------------------- | ------------------------ |
|
||||
| `partial` | `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
|
||||
|
||||
|
|
@ -412,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 Service Instances for Ingress Gateways Associated with 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 service instances 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 |
|
||||
|
|
@ -427,8 +431,7 @@ 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 [streaming](/api/features/streaming), and will use
|
||||
[blocking queries](/api/features/blocking).
|
||||
endpoint does not support the [streaming backend](/api/features/blocking#streaming-backend).
|
||||
|
||||
|
||||
## List Checks in State
|
||||
|
|
|
|||
Loading…
Reference in New Issue