From fcec9a18ce560ba2dcff655ea42368c24ca02ae6 Mon Sep 17 00:00:00 2001 From: Jared Kirschner Date: Sat, 19 Mar 2022 13:32:38 -0700 Subject: [PATCH] docs: mention filtered by ACLs in affected APIs --- website/content/api-docs/agent/check.mdx | 2 ++ website/content/api-docs/agent/index.mdx | 2 ++ website/content/api-docs/agent/service.mdx | 2 ++ website/content/api-docs/catalog.mdx | 14 ++++++++++++++ website/content/api-docs/config.mdx | 2 ++ website/content/api-docs/connect/intentions.mdx | 2 ++ website/content/api-docs/event.mdx | 2 ++ website/content/api-docs/health.mdx | 12 ++++++++++++ website/content/api-docs/kv.mdx | 6 ++++++ website/content/api-docs/namespaces.mdx | 2 ++ website/content/api-docs/query.mdx | 6 ++++++ website/content/api-docs/session.mdx | 4 ++++ 12 files changed, 56 insertions(+) diff --git a/website/content/api-docs/agent/check.mdx b/website/content/api-docs/agent/check.mdx index 05fc3f43e..706d07369 100644 --- a/website/content/api-docs/agent/check.mdx +++ b/website/content/api-docs/agent/check.mdx @@ -21,6 +21,8 @@ there is no leader elected. The agent performs active [anti-entropy](/docs/architecture/anti-entropy), so in most situations everything will be in sync within a few seconds. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | --------------- | ------------------ | | `GET` | `/agent/checks` | `application/json` | diff --git a/website/content/api-docs/agent/index.mdx b/website/content/api-docs/agent/index.mdx index 853e07119..50c013ee0 100644 --- a/website/content/api-docs/agent/index.mdx +++ b/website/content/api-docs/agent/index.mdx @@ -213,6 +213,8 @@ 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`. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | ---------------- | ------------------ | | `GET` | `/agent/members` | `application/json` | diff --git a/website/content/api-docs/agent/service.mdx b/website/content/api-docs/agent/service.mdx index 09223a9db..489556919 100644 --- a/website/content/api-docs/agent/service.mdx +++ b/website/content/api-docs/agent/service.mdx @@ -23,6 +23,8 @@ while there is no leader elected. The agent performs active [anti-entropy](/docs/architecture/anti-entropy), so in most situations everything will be in sync within a few seconds. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | ----------------- | ------------------ | | `GET` | `/agent/services` | `application/json` | diff --git a/website/content/api-docs/catalog.mdx b/website/content/api-docs/catalog.mdx index f24b2e9c0..64011347c 100644 --- a/website/content/api-docs/catalog.mdx +++ b/website/content/api-docs/catalog.mdx @@ -285,6 +285,8 @@ $ curl \ This endpoint and returns the nodes registered in a given datacenter. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | ---------------- | ------------------ | | `GET` | `/catalog/nodes` | `application/json` | @@ -382,6 +384,8 @@ the following selectors and filter operations being supported: This endpoint returns the services registered in a given datacenter. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | ------------------- | ------------------ | | `GET` | `/catalog/services` | `application/json` | @@ -438,6 +442,8 @@ a given service. This endpoint returns the nodes providing a service in a given datacenter. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | --------------------------- | ------------------ | | `GET` | `/catalog/service/:service` | `application/json` | @@ -651,6 +657,8 @@ This will include both proxies and native integrations. A service may register both Connect-capable and incapable services at the same time, so this endpoint may be used to filter only the Connect-capable endpoints. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | --------------------------- | ------------------ | | `GET` | `/catalog/connect/:service` | `application/json` | @@ -662,6 +670,8 @@ Parameters and response format are the same as This endpoint returns the node's registered services. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | --------------------- | ------------------ | | `GET` | `/catalog/node/:node` | `application/json` | @@ -791,6 +801,8 @@ top level Node object. The following selectors and filter operations are support This endpoint returns the node's registered services. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | ------------------------------ | ------------------ | | `GET` | `/catalog/node-services/:node` | `application/json` | @@ -925,6 +937,8 @@ top level object. The following selectors and filter operations are supported: This endpoint returns the services associated with an ingress gateway or terminating gateway. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | ------------------------------------ | ------------------ | | `GET` | `/catalog/gateway-services/:gateway` | `application/json` | diff --git a/website/content/api-docs/config.mdx b/website/content/api-docs/config.mdx index c8ea8172b..151af061f 100644 --- a/website/content/api-docs/config.mdx +++ b/website/content/api-docs/config.mdx @@ -161,6 +161,8 @@ $ curl \ This endpoint returns all config entries of the given kind. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | --------------- | ------------------ | | `GET` | `/config/:kind` | `application/json` | diff --git a/website/content/api-docs/connect/intentions.mdx b/website/content/api-docs/connect/intentions.mdx index a2f7eddcd..2ffcc58bc 100644 --- a/website/content/api-docs/connect/intentions.mdx +++ b/website/content/api-docs/connect/intentions.mdx @@ -435,6 +435,8 @@ $ curl \ This endpoint lists all intentions. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | --------------------- | ------------------ | | `GET` | `/connect/intentions` | `application/json` | diff --git a/website/content/api-docs/event.mdx b/website/content/api-docs/event.mdx index f322c7b42..c9edbe47b 100644 --- a/website/content/api-docs/event.mdx +++ b/website/content/api-docs/event.mdx @@ -93,6 +93,8 @@ agent may have a different view of the events. Events are broadcast using the [gossip protocol](/docs/architecture/gossip), so they have no global ordering nor do they make a promise of delivery. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | ------------- | ------------------ | | `GET` | `/event/list` | `application/json` | diff --git a/website/content/api-docs/health.mdx b/website/content/api-docs/health.mdx index cc4fc72ba..1ae4c2701 100644 --- a/website/content/api-docs/health.mdx +++ b/website/content/api-docs/health.mdx @@ -18,6 +18,8 @@ raw entries. This endpoint returns the checks specific to the node provided on the path. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | -------------------- | ------------------ | | `GET` | `/health/node/:node` | `application/json` | @@ -113,6 +115,8 @@ the following selectors and filter operations being supported: This endpoint returns the checks associated with the service provided on the path. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | ------------------------- | ------------------ | | `GET` | `/health/checks/:service` | `application/json` | @@ -203,6 +207,8 @@ This endpoint returns the service instances providing the service indicated on t Users can also build in support for dynamic load balancing and other features by incorporating the use of health checks. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | -------------------------- | ------------------ | | `GET` | `/health/service/:service` | `application/json` | @@ -409,6 +415,8 @@ This will include both proxies and native integrations. A service may register both Connect-capable and incapable services at the same time, so this endpoint may be used to filter only the Connect-capable endpoints. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | -------------------------- | ------------------ | | `GET` | `/health/connect/:service` | `application/json` | @@ -423,6 +431,8 @@ Parameters and response format are the same as This endpoint returns the service instances providing an [ingress gateway](/docs/connect/gateways/ingress-gateway) for a service in a given datacenter. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | -------------------------- | ------------------ | | `GET` | `/health/ingress/:service` | `application/json` | @@ -438,6 +448,8 @@ endpoint does not support the [streaming backend](/api/features/blocking#streami This endpoint returns the checks in the state provided on the path. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | ---------------------- | ------------------ | | `GET` | `/health/state/:state` | `application/json` | diff --git a/website/content/api-docs/kv.mdx b/website/content/api-docs/kv.mdx index 65972f2d2..029c3ae81 100644 --- a/website/content/api-docs/kv.mdx +++ b/website/content/api-docs/kv.mdx @@ -29,6 +29,12 @@ This endpoint returns the specified key. If no key exists at the given path, a For multi-key reads (up to a limit of 64 KV operations) please consider using [transactions](/api/txn) instead. +If the [`recurse`](#recurse) or [`keys`](#keys) query parameters are `true`, +this endpoint will return an array of keys. In this case, +the HTTP response includes the `X-Consul-Results-Filtered-By-ACLs: true` header +if the response array excludes results due to ACL policy configuration. +Refer to the [HTTP API documentation](/api-docs#results-filtered-by-acls) for more information. + | Method | Path | Produces | | ------ | ---------- | ------------------ | | `GET` | `/kv/:key` | `application/json` | diff --git a/website/content/api-docs/namespaces.mdx b/website/content/api-docs/namespaces.mdx index bf22ec6ca..c14c9a721 100644 --- a/website/content/api-docs/namespaces.mdx +++ b/website/content/api-docs/namespaces.mdx @@ -427,6 +427,8 @@ $ curl --request DELETE \ This endpoint lists all the Namespaces. The output will be filtered based on the privileges of the ACL token used for the request. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | ------------- | ------------------ | | `GET` | `/namespaces` | `application/json` | diff --git a/website/content/api-docs/query.mdx b/website/content/api-docs/query.mdx index b5e608b6e..2adaa152e 100644 --- a/website/content/api-docs/query.mdx +++ b/website/content/api-docs/query.mdx @@ -299,6 +299,8 @@ $ curl \ This endpoint returns a list of all prepared queries. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | ------ | -------- | ------------------ | | `GET` | `/query` | `application/json` | @@ -478,6 +480,10 @@ $ curl \ This endpoint executes an existing prepared query. If no query exists by the given ID, an error is returned. +The HTTP response includes the `X-Consul-Results-Filtered-By-ACLs: true` header +if the [`Nodes`](#nodes) response array excludes results due to ACL policy configuration. +Refer to the [HTTP API documentation](/api-docs#results-filtered-by-acls) for more information. + | Method | Path | Produces | | ------ | ---------------------- | ------------------ | | `GET` | `/query/:uuid/execute` | `application/json` | diff --git a/website/content/api-docs/session.mdx b/website/content/api-docs/session.mdx index 63766f32b..efaccbcc3 100644 --- a/website/content/api-docs/session.mdx +++ b/website/content/api-docs/session.mdx @@ -230,6 +230,8 @@ If the session does not exist, an empty JSON list `[]` is returned. This endpoint returns the active sessions for a given node. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | :----- | :-------------------- | ------------------ | | `GET` | `/session/node/:node` | `application/json` | @@ -292,6 +294,8 @@ $ curl \ This endpoint returns the list of active sessions. +@include 'http_api_results_filtered_by_acls.mdx' + | Method | Path | Produces | | :----- | :-------------- | ------------------ | | `GET` | `/session/list` | `application/json` |