diff --git a/.changelog/9262.txt b/.changelog/9262.txt new file mode 100644 index 0000000000..fc93251d57 --- /dev/null +++ b/.changelog/9262.txt @@ -0,0 +1,6 @@ +```release-note:deprecation +api: the `tag`, `node-meta`, and `passing` query parameters for various health and catalog +endpoints are now deprecated. The `filter` query parameter should be used as a replacement +for all of the deprecated fields. The deprecated query parameters will be removed in a future +version of Consul. +``` diff --git a/website/pages/api-docs/catalog.mdx b/website/pages/api-docs/catalog.mdx index 942bdd5144..d2728f9ef0 100644 --- a/website/pages/api-docs/catalog.mdx +++ b/website/pages/api-docs/catalog.mdx @@ -309,7 +309,9 @@ The table below shows this endpoint's support for `?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 +- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Meta` selector instead. + This parameter will be removed in a future version of Consul. + 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. @@ -454,7 +456,9 @@ The table below shows this endpoint's support for the datacenter of the agent being queried. This is specified as part of the URL as a query parameter. -- `tag` `(string: "")` - Specifies the tag to filter on. This is specified as part of +- `tag` `(string: "")` **Deprecated** - Use `filter` with the `ServiceTags` selector instead. + This parameter will be removed in a future version of Consul. + Specifies the tag to filter on. This is specified as part of the URL as a query parameter. Can be used multiple times for additional filtering, returning only the results that include all of the tag values provided. @@ -463,7 +467,9 @@ The table below shows this endpoint's support for `?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 +- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `NodeMeta` selector instead. + This parameter will be removed in a future version of Consul. + 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. diff --git a/website/pages/api-docs/health.mdx b/website/pages/api-docs/health.mdx index 0f3ac434ff..7038d94278 100644 --- a/website/pages/api-docs/health.mdx +++ b/website/pages/api-docs/health.mdx @@ -142,7 +142,9 @@ The table below shows this endpoint's support for `?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 +- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Node.Meta` selector instead. + This parameter will be removed in a future version of Consul. + 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. @@ -232,17 +234,23 @@ The table below shows this endpoint's support for `?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 tag to filter the list. This is +- `tag` `(string: "")` **Deprecated** - Use `filter` with the `Service.Tags` selector instead. + This parameter will be removed in a future version of Consul. + Specifies the tag to filter the list. This is specified as part of the URL as a query parameter. Can be used multiple times for additional filtering, returning only the results that include all of the tag values provided. -- `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair +- `node-meta` `(string: "")` **Deprecated** - Use `filter` with the `Node.Meta` selector instead. + This parameter will be removed in a future version of Consul. + 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 +- `passing` `(bool: false)` **Deprecated** - Use `filter` with the `Checks.Status` selector instead. + This parameter will be removed in a future version of Consul. + 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.