From 84eba733e7194d4a8c3c73663084d2855119ab29 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Tue, 8 Jun 2021 16:13:34 -0400 Subject: [PATCH] Merge pull request #10169 from hashicorp/dnephin/streaming-docs docs: add streaming to api-docs --- .../content/api-docs/features/blocking.mdx | 18 +++++++++++++ website/content/api-docs/health.mdx | 27 ++++++++++++------- 2 files changed, 36 insertions(+), 9 deletions(-) diff --git a/website/content/api-docs/features/blocking.mdx b/website/content/api-docs/features/blocking.mdx index 093bd1e545..2b7a9ae860 100644 --- a/website/content/api-docs/features/blocking.mdx +++ b/website/content/api-docs/features/blocking.mdx @@ -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 diff --git a/website/content/api-docs/health.mdx b/website/content/api-docs/health.mdx index 220244dc63..77721a7cbc 100644 --- a/website/content/api-docs/health.mdx +++ b/website/content/api-docs/health.mdx @@ -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` 1 | `all` | `background refresh` | `node:read,service:read` | + +

+ 1some query parameters will use the + streaming backend +

### 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.