From 8234ec28a32d2d4aee159edc32a6e1bada8a47dc Mon Sep 17 00:00:00 2001 From: Archer Date: Fri, 24 Jan 2025 16:30:38 -0600 Subject: [PATCH 01/24] Add markers for cluster APIs. Signed-off-by: Archer --- _api-reference/cat/cat-nodes.md | 2 +- _api-reference/cat/cat-pending-tasks.md | 2 +- _api-reference/cat/cat-recovery.md | 2 +- _api-reference/cat/cat-segment-replication.md | 2 +- _api-reference/cat/cat-shards.md | 2 +- _api-reference/cat/cat-snapshots.md | 2 +- _api-reference/cat/cat-tasks.md | 2 +- .../cluster-api/cluster-allocation.md | 30 ++++-- .../cluster-api/cluster-awareness.md | 36 +++++-- .../cluster-api/cluster-component-template.md | 95 +++++++++++++++++++ .../cluster-api/cluster-decommission.md | 44 +++++++-- _api-reference/cluster-api/cluster-health.md | 51 ++++------ .../cluster-api/cluster-pending-tasks.md | 32 +++++++ _api-reference/cluster-api/cluster-reroute.md | 30 ++++++ .../cluster-api/cluster-settings.md | 40 ++++---- _api-reference/cluster-api/cluster-state.md | 30 ++++++ _api-reference/cluster-api/cluster-stats.md | 31 ++---- .../cluster-voting-configuration.md | 44 +++++++++ .../cluster-api/cluster-weighted-routing.md | 46 +++++++++ 19 files changed, 420 insertions(+), 103 deletions(-) create mode 100644 _api-reference/cluster-api/cluster-component-template.md create mode 100644 _api-reference/cluster-api/cluster-pending-tasks.md create mode 100644 _api-reference/cluster-api/cluster-reroute.md create mode 100644 _api-reference/cluster-api/cluster-state.md create mode 100644 _api-reference/cluster-api/cluster-voting-configuration.md create mode 100644 _api-reference/cluster-api/cluster-weighted-routing.md diff --git a/_api-reference/cat/cat-nodes.md b/_api-reference/cat/cat-nodes.md index 5a570ca23c..e5c64f6430 100644 --- a/_api-reference/cat/cat-nodes.md +++ b/_api-reference/cat/cat-nodes.md @@ -47,7 +47,7 @@ The following table lists the available query parameters. All query parameters a | `h` | List | A comma-separated list of column names to display. | N/A | | `help` | Boolean | Returns help information. | `false` | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units](https://opensearch.org/docs/latest/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-pending-tasks.md b/_api-reference/cat/cat-pending-tasks.md index 38cc295ee7..41a9575d67 100644 --- a/_api-reference/cat/cat-pending-tasks.md +++ b/_api-reference/cat/cat-pending-tasks.md @@ -44,7 +44,7 @@ The following table lists the available query parameters. All query parameters a | `help` | Boolean | Returns help information. | `false` | | `local` | Boolean | Returns local information but does not retrieve the state from the cluster manager node. | `false` | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units](https://opensearch.org/docs/latest/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-recovery.md b/_api-reference/cat/cat-recovery.md index 1a3e6857f7..de40eb0388 100644 --- a/_api-reference/cat/cat-recovery.md +++ b/_api-reference/cat/cat-recovery.md @@ -46,7 +46,7 @@ The following table lists the available query parameters. All query parameters a | `h` | List | A comma-separated list of column names to display. | N/A | | `help` | Boolean | Returns help information. | `false` | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units](https://opensearch.org/docs/latest/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-segment-replication.md b/_api-reference/cat/cat-segment-replication.md index 4e867e7ecf..7dbe3b4ebd 100644 --- a/_api-reference/cat/cat-segment-replication.md +++ b/_api-reference/cat/cat-segment-replication.md @@ -68,7 +68,7 @@ The following table lists the available query parameters. All query parameters a | `ignore_unavailable` | Boolean | Whether the specified concrete indexes should be ignored when missing or closed. | N/A | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | | `shards` | List | A comma-separated list of shards to display. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units](https://opensearch.org/docs/latest/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | | `timeout` | String | The operation timeout. | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-shards.md b/_api-reference/cat/cat-shards.md index 5d2f873702..c721e89d3c 100644 --- a/_api-reference/cat/cat-shards.md +++ b/_api-reference/cat/cat-shards.md @@ -46,7 +46,7 @@ The following table lists the available query parameters. All query parameters a | `help` | Boolean | Returns help information. | `false` | | `local` | Boolean | Returns local information but does not retrieve the state from the cluster manager node. | `false` | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units](https://opensearch.org/docs/latest/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-snapshots.md b/_api-reference/cat/cat-snapshots.md index 5e2add5de6..dc2ffaab62 100644 --- a/_api-reference/cat/cat-snapshots.md +++ b/_api-reference/cat/cat-snapshots.md @@ -45,7 +45,7 @@ The following table lists the available query parameters. All query parameters a | `help` | Boolean | Returns help information. | `false` | | `ignore_unavailable` | Boolean | When `true`, the response does not include information from unavailable snapshots. | `false` | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units](https://opensearch.org/docs/latest/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-tasks.md b/_api-reference/cat/cat-tasks.md index 2d30c92727..5cac1c3936 100644 --- a/_api-reference/cat/cat-tasks.md +++ b/_api-reference/cat/cat-tasks.md @@ -45,7 +45,7 @@ The following table lists the available query parameters. All query parameters a | `nodes` | List | A comma-separated list of node IDs or names used to limit the returned information. Use `_local` to return information from the node to which you're connecting, specify a specific node from which to get information, or keep the parameter empty to get information from all nodes. | N/A | | `parent_task_id` | String | The parent task identifier, which is used to limit the response. | N/A | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units](https://opensearch.org/docs/latest/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cluster-api/cluster-allocation.md b/_api-reference/cluster-api/cluster-allocation.md index 5e7984cd75..94430c3ace 100644 --- a/_api-reference/cluster-api/cluster-allocation.md +++ b/_api-reference/cluster-api/cluster-allocation.md @@ -12,26 +12,36 @@ redirect_from: **Introduced 1.0** {: .label .label-purple } -The most basic cluster allocation explain request finds an unassigned shard and explains why it can't be allocated to a node. +The Cluster allocation explain API gives an explanation for how shards are allocated in the current cluster and provides an explanation for why unassigned shards can't be allocated to a node. -If you add some options, you can instead get information on a specific shard, including why OpenSearch assigned it to its current node. + ## Endpoints - ```json -GET _cluster/allocation/explain -POST _cluster/allocation/explain +GET /_cluster/allocation/explain +POST /_cluster/allocation/explain ``` + + + ## Query parameters -All parameters are optional. +The following table lists the available query parameters. All query parameters are optional. -Parameter | Type | Description -:--- | :--- | :--- -include_yes_decisions | Boolean | OpenSearch makes a series of yes or no decisions when trying to allocate a shard to a node. If this parameter is true, OpenSearch includes the (generally more numerous) "yes" decisions in its response. Default is `false`. -include_disk_info | Boolean | Whether to include information about disk usage in the response. Default is `false`. +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `include_disk_info` | Boolean | When `true`, returns information about disk usage and shard sizes. _(Default: `false`)_ | +| `include_yes_decisions` | Boolean | When `true`, returns any `YES` decisions in the allocation explanation. _(Default: `false`)_ | + + ## Request body fields diff --git a/_api-reference/cluster-api/cluster-awareness.md b/_api-reference/cluster-api/cluster-awareness.md index 4be9f50947..2f888236f5 100644 --- a/_api-reference/cluster-api/cluster-awareness.md +++ b/_api-reference/cluster-api/cluster-awareness.md @@ -15,19 +15,41 @@ redirect_from: To control the distribution of search or HTTP traffic, you can use the weights per awareness attribute to control the distribution of search or HTTP traffic across zones. This is commonly used for zonal deployments, heterogeneous instances, and routing traffic away from zones during zonal failure. + ## Endpoints +```json +GET /_cluster/routing/awareness/{attribute}/weights +``` + + ```json -PUT /_cluster/routing/awareness//weights -GET /_cluster/routing/awareness//weights?local -GET /_cluster/routing/awareness//weights +PUT /_cluster/routing/awareness/{attribute}/weights ``` + -## Path parameters + +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `include_disk_info` | Boolean | When `true`, returns information about disk usage and shard sizes. _(Default: `false`)_ | +| `include_yes_decisions` | Boolean | When `true`, returns any `YES` decisions in the allocation explanation. _(Default: `false`)_ | + + -Parameter | Type | Description -:--- | :--- | :--- -attribute | String | The name of the awareness attribute, usually `zone`. The attribute name must match the values listed in the request body when assigning weights to zones. ## Request body fields diff --git a/_api-reference/cluster-api/cluster-component-template.md b/_api-reference/cluster-api/cluster-component-template.md new file mode 100644 index 0000000000..5dd838acd1 --- /dev/null +++ b/_api-reference/cluster-api/cluster-component-template.md @@ -0,0 +1,95 @@ +--- +layout: default +title: Cluster component template +nav_order: 25 +parent: Cluster APIs +--- + +# Cluster component template +**Introduced 1.0** +{: .label .label-purple } + +The Cluster component template APIs creates and updates the cluster's component templates + +# Endpoints + +The `GET` method returns one or more component templates. + + +```json +GET /_component_template +GET /_component_template/{name} +``` + + +The `EXISTS` method returns information about whether a particular component template exist. + + +```json +HEAD /_component_template/{name} +``` + + +The `PUT` method creates or updates a component template. + + +```json +POST /_component_template/{name} +PUT /_component_template/{name} +``` + + +The `DELETE` method deletes a component template. + + +```json +DELETE /_component_template/{name} +``` + + + +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `name` | **Required** | String | The name of the component template to create. OpenSearch includes the following built-in component templates: `logs-mappings`; 'logs-settings`; `metrics-mappings`; `metrics-settings`;`synthetics-mapping`; `synthetics-settings`. OpenSearch uses these templates to configure backing indexes for its data streams. If you want to overwrite one of these templates, set the replacement template `version` to a higher value than the current version. If you want to disable all built-in component and index templates, set `stack.templates.enabled` to `false` using the Cluster Update Settings API. | + + + + +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| `create` | Boolean | When `true`, this request cannot replace or update existing component templates. _(Default: `false`)_ | +| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | + + diff --git a/_api-reference/cluster-api/cluster-decommission.md b/_api-reference/cluster-api/cluster-decommission.md index 04d73d329d..ab54672b71 100644 --- a/_api-reference/cluster-api/cluster-decommission.md +++ b/_api-reference/cluster-api/cluster-decommission.md @@ -13,25 +13,55 @@ redirect_from: **Introduced 1.0** {: .label .label-purple } -The cluster decommission operation adds support decommissioning based on awareness. It greatly benefits multi-zone deployments, where awareness attributes, such as `zones`, can aid in applying new upgrades to a cluster in a controlled fashion. This is especially useful during outages, in which case, you can decommission the unhealthy zone to prevent replication requests from stalling and prevent your request backlog from becoming too large. +The Cluster decommission API adds support decommissioning based on awareness. It greatly benefits multi-zone deployments, where awareness attributes, such as `zones`, can aid in applying new upgrades to a cluster in a controlled fashion. This is especially useful during outages, in which case, you can decommission the unhealthy zone to prevent replication requests from stalling and prevent your request backlog from becoming too large. For more information about allocation awareness, see [Shard allocation awareness]({{site.url}}{{site.baseurl}}//opensearch/cluster/#shard-allocation-awareness). + ## Endpoints +```json +GET /_cluster/decommission/awareness/{awareness_attribute_name}/_status +``` + + +```json +PUT /_cluster/decommission/awareness/{awareness_attribute_name}/{awareness_attribute_value} +``` + + + ```json -PUT /_cluster/decommission/awareness/{awareness_attribute_name}/{awareness_attribute_value} -GET /_cluster/decommission/awareness/{awareness_attribute_name}/_status DELETE /_cluster/decommission/awareness ``` + + ## Path parameters -Parameter | Type | Description -:--- | :--- | :--- -awareness_attribute_name | String | The name of awareness attribute, usually `zone`. -awareness_attribute_value | String | The value of the awareness attribute. For example, if you have shards allocated in two different zones, you can give each zone a value of `zone-a` or `zoneb`. The cluster decommission operation decommissions the zone listed in the method. +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `awareness_attribute_name` | **Required** | String | The name of the awareness attribute. | +| `awareness_attribute_value` | **Required** | String | The value of the awareness attribute. | + + ## Example requests diff --git a/_api-reference/cluster-api/cluster-health.md b/_api-reference/cluster-api/cluster-health.md index 07ba8d4364..ceafb2fd08 100644 --- a/_api-reference/cluster-api/cluster-health.md +++ b/_api-reference/cluster-api/cluster-health.md @@ -17,41 +17,24 @@ The most basic cluster health request returns a simple status of the health of y To get the status of a specific index, provide the index name. + + + + + + + + -## Endpoints - -```json -GET _cluster/health -GET _cluster/health/ -``` - -## Path parameters - -The following table lists the available path parameters. All path parameters are optional. - -Parameter | Data type | Description -:--- | :--- | :--- -<index-name> | String | Limits health reporting to a specific index. Can be a single index or a comma-separated list of index names. - -## Query parameters - -The following table lists the available query parameters. All query parameters are optional. - -Parameter | Type | Description -:--- | :--- | :--- -expand_wildcards | Enum | Expands wildcard expressions to concrete indexes. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`. -level | Enum | The level of detail for returned health information. Supported values are `cluster`, `indices`, `shards`, and `awareness_attributes`. Default is `cluster`. -awareness_attribute | String | The name of the awareness attribute, for which to return cluster health (for example, `zone`). Applicable only if `level` is set to `awareness_attributes`. -local | Boolean | Whether to return information from the local node only instead of from the cluster manager node. Default is `false`. -cluster_manager_timeout | Time | The amount of time to wait for a connection to the cluster manager node. Default is 30 seconds. -timeout | Time | The amount of time to wait for a response. If the timeout expires, the request fails. Default is 30 seconds. -wait_for_active_shards | String | Wait until the specified number of shards is active before returning a response. `all` for all shards. Default is `0`. -wait_for_nodes | String | Wait for N number of nodes. Use `12` for exact match, `>12` and `<12` for range. -wait_for_events | Enum | Wait until all currently queued events with the given priority are processed. Supported values are `immediate`, `urgent`, `high`, `normal`, `low`, and `languid`. -wait_for_no_relocating_shards | Boolean | Whether to wait until there are no relocating shards in the cluster. Default is `false`. -wait_for_no_initializing_shards | Boolean | Whether to wait until there are no initializing shards in the cluster. Default is `false`. -wait_for_status | Enum | Wait until the cluster health reaches the specified status or better. Supported values are `green`, `yellow`, and `red`. -weights | JSON object | Assigns weights to attributes within the request body of the PUT request. Weights can be set in any ration, for example, 2:3:5. In a 2:3:5 ratio with three zones, for every 100 requests sent to the cluster, each zone would receive either 20, 30, or 50 search requests in a random order. When assigned a weight of `0`, the zone does not receive any search traffic. ## Example requests diff --git a/_api-reference/cluster-api/cluster-pending-tasks.md b/_api-reference/cluster-api/cluster-pending-tasks.md new file mode 100644 index 0000000000..40912e7936 --- /dev/null +++ b/_api-reference/cluster-api/cluster-pending-tasks.md @@ -0,0 +1,32 @@ +--- +layout: default +title: Cluster pending tasks +nav_order: 42 +parent: Cluster APIs +--- + +# Cluster pending tasks + +**Introduced 1.0** +{: .label .label-purple } + +The Cluster pending tasks API returns a list of pending cluster-level tasks, such as index creation, mapping updates, +or new allocations. + + + + + + + + + \ No newline at end of file diff --git a/_api-reference/cluster-api/cluster-reroute.md b/_api-reference/cluster-api/cluster-reroute.md new file mode 100644 index 0000000000..cc71c16ed1 --- /dev/null +++ b/_api-reference/cluster-api/cluster-reroute.md @@ -0,0 +1,30 @@ +--- +layout: default +title: Cluster reroute +nav_order: 45 +parent: Cluster APIs +--- + +# Cluster reroute +**Introduced 1.0** +{: .label .label-purple } + +The Cluster reroute API changes the allocation of individual shards in the cluster. + + + + + + + + + diff --git a/_api-reference/cluster-api/cluster-settings.md b/_api-reference/cluster-api/cluster-settings.md index 9008234ff6..95a217a8dd 100644 --- a/_api-reference/cluster-api/cluster-settings.md +++ b/_api-reference/cluster-api/cluster-settings.md @@ -14,23 +14,29 @@ redirect_from: The cluster settings operation lets you check the current settings for your cluster, review default settings, and change settings. When you update a setting using the API, OpenSearch applies it to all nodes in the cluster. -## Endpoints - -```json -GET _cluster/settings -PUT _cluster/settings -``` - -## Path parameters - -All parameters are optional. - -Parameter | Data type | Description -:--- | :--- | :--- -flat_settings | Boolean | Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings. For example, the flat form of `"cluster": { "max_shards_per_node": 500 }` is `"cluster.max_shards_per_node": "500"`. -include_defaults (GET only) | Boolean | Whether to include default settings as part of the response. This parameter is useful for identifying the names and current values of settings you want to update. -cluster_manager_timeout | Time unit | The amount of time to wait for a response from the cluster manager node. Default is `30 seconds`. -timeout (PUT only) | Time unit | The amount of time to wait for a response from the cluster. Default is `30 seconds`. + + + + + + + + + + + ## Request body fields diff --git a/_api-reference/cluster-api/cluster-state.md b/_api-reference/cluster-api/cluster-state.md new file mode 100644 index 0000000000..8f6522c7ac --- /dev/null +++ b/_api-reference/cluster-api/cluster-state.md @@ -0,0 +1,30 @@ +--- +layout: default +title: Cluster state +nav_order: 55 +parent: Cluster APIs +--- + +# Cluster state +**Introduced 1.0** +{: .label .label-purple } + +The Cluster state API returns comprehensive information about the state of the cluster. + + + + + + + + + \ No newline at end of file diff --git a/_api-reference/cluster-api/cluster-stats.md b/_api-reference/cluster-api/cluster-stats.md index 5d0d9c6d95..80adfe5b5f 100644 --- a/_api-reference/cluster-api/cluster-stats.md +++ b/_api-reference/cluster-api/cluster-stats.md @@ -16,28 +16,17 @@ redirect_from: The cluster stats API operation returns statistics about your cluster. -## Endpoints + + -```json -GET _cluster/stats -GET _cluster/stats/nodes/ -GET _cluster/stats//nodes/ -GET _cluster/stats///nodes/ -``` - -## Path parameters - -All parameters are optional. - -Parameter | Type | Description -:--- | :--- | :--- -<node-filters> | List | A comma-separated list of [node filters]({{site.url}}{{site.baseurl}}/api-reference/nodes-apis/index/#node-filters) that OpenSearch uses to filter results. -metric | String | A comma-separated list of [metric groups](#metric-groups), for example, `jvm,fs`. Default is all metric groups. -index_metric | String | A comma-separated list of [index metric groups](#index-metric-groups), for example, `docs,store`. Default is all index metrics. - - -Although the term `master` was deprecated in favor of `cluster_manager` subsequent to OpenSearch 2.0, the `master` field was retained for backward compatibility. If you have a node that has either a `master` role or a `cluster_manager` role, the `count` increases for both fields by 1. For an example node count increase, see the [example response](#example-response). -{: .note } + + ### Metric groups diff --git a/_api-reference/cluster-api/cluster-voting-configuration.md b/_api-reference/cluster-api/cluster-voting-configuration.md new file mode 100644 index 0000000000..562f2c3e93 --- /dev/null +++ b/_api-reference/cluster-api/cluster-voting-configuration.md @@ -0,0 +1,44 @@ +--- +layout: default +title: Cluster voting configuration +nav_order: 55 +parent: Cluster APIs +--- + +# Cluster voting configuration +**Introduced 1.0** +{: .label .label-purple } + +The Cluster voting configuration API updates and clears voting configurations. + +# Endpoints + +The `POST` method updates the cluster voting configuration by excluding certain node IDs or names. + + + + +The `DELETE` method clears any cluster voting configuration exclusions. + + + + + + + + + \ No newline at end of file diff --git a/_api-reference/cluster-api/cluster-weighted-routing.md b/_api-reference/cluster-api/cluster-weighted-routing.md new file mode 100644 index 0000000000..28eb7822a9 --- /dev/null +++ b/_api-reference/cluster-api/cluster-weighted-routing.md @@ -0,0 +1,46 @@ +--- +layout: default +title: Cluster weighted routing +nav_order: 60 +parent: Cluster APIs +--- + +# Cluster weighted routing +**Introduced 1.0** +{: .label .label-purple } + +The Cluster weighted routing API updates and creates routing weights for shard allocation. + +# Endpoints + +The `GET` method fetches shard routing weights. + + + + +The `PUT` method updates shard routing weights. + + + + +The `DELETE` method deletes shard routing weights. + + + + + + \ No newline at end of file From 7f0f39bf46f27107950a1f277cbd4001414b72c9 Mon Sep 17 00:00:00 2001 From: Archer Date: Fri, 24 Jan 2025 17:45:15 -0600 Subject: [PATCH 02/24] Add rest of cluster inserts Signed-off-by: Archer --- _api-reference/cluster-api/cluster-health.md | 33 +++++++++++++++++++ .../cluster-api/cluster-pending-tasks.md | 22 +++++++++---- _api-reference/cluster-api/cluster-reroute.md | 24 ++++++++++---- .../cluster-api/cluster-settings.md | 25 ++++++++++---- _api-reference/cluster-api/cluster-state.md | 33 ++++++++++++++++++- _api-reference/cluster-api/cluster-stats.md | 17 ++++++++++ .../cluster-voting-configuration.md | 23 +++++++++---- .../cluster-api/cluster-weighted-routing.md | 31 +++++++++++++---- 8 files changed, 176 insertions(+), 32 deletions(-) diff --git a/_api-reference/cluster-api/cluster-health.md b/_api-reference/cluster-api/cluster-health.md index ceafb2fd08..6f99392c76 100644 --- a/_api-reference/cluster-api/cluster-health.md +++ b/_api-reference/cluster-api/cluster-health.md @@ -21,18 +21,51 @@ To get the status of a specific index, provide the index name. api: cluster.health component: endpoints --> +## Endpoints +```json +GET /_cluster/health +GET /_cluster/health/{index} +``` +## Path parameters + +The following table lists the available path parameters. All path parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `index` | List or String | A comma-separated list of data streams, indexes, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams and indexes, omit this parameter or use `*` or `_all`. | + +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | Default | +| :--- | :--- | :--- | :--- | +| `awareness_attribute` | String | The name of the awareness attribute for which to return the cluster health status (for example, `zone`). Applicable only if `level` is set to `awareness_attributes`. | N/A | +| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `expand_wildcards` | List or String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with open, closed, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes. | N/A | +| `level` | String |
Valid values are: `awareness_attributes`, `cluster`, `indices`, `shards` | `cluster` | +| `local` | Boolean | Whether to return information from the local node only instead of from the cluster manager node. | `false` | +| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `wait_for_active_shards` | Integer or String | Waits until the specified number of shards is active before returning a response. Use `all` for all shards.
Valid values are: `all`, `index-setting` | N/A | +| `wait_for_events` | String | Waits until all currently queued events with the given priority are processed.
Valid values are: `high`, `immediate`, `languid`, `low`, `normal`, `urgent` | N/A | +| `wait_for_no_initializing_shards` | Boolean | Whether to wait until there are no initializing shards in the cluster. | `false` | +| `wait_for_no_relocating_shards` | Boolean | Whether to wait until there are no relocating shards in the cluster. | N/A | +| `wait_for_nodes` | Float or String | Waits until the specified number of nodes (`N`) is available. Accepts `>=N`, `<=N`, `>N`, and ` Valid values are: `green`, `GREEN`, `yellow`, `YELLOW`, `red`, `RED` | N/A | +| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | + diff --git a/_api-reference/cluster-api/cluster-pending-tasks.md b/_api-reference/cluster-api/cluster-pending-tasks.md index 40912e7936..b5a7e644ec 100644 --- a/_api-reference/cluster-api/cluster-pending-tasks.md +++ b/_api-reference/cluster-api/cluster-pending-tasks.md @@ -17,16 +17,24 @@ or new allocations. api: cluster.pending_tasks component: endpoints --> - - - +## Endpoints +```json +GET /_cluster/pending_tasks +``` - \ No newline at end of file +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| `local` | Boolean | When `true`, the request retrieves information from the local node only. When `false`, information is retrieved from the cluster manager node. _(Default: `false`)_ | +| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | + + diff --git a/_api-reference/cluster-api/cluster-reroute.md b/_api-reference/cluster-api/cluster-reroute.md index cc71c16ed1..b60dc4d7d2 100644 --- a/_api-reference/cluster-api/cluster-reroute.md +++ b/_api-reference/cluster-api/cluster-reroute.md @@ -15,16 +15,28 @@ The Cluster reroute API changes the allocation of individual shards in the clust api: cluster.reroute component: endpoints --> - - - +## Endpoints +```json +POST /_cluster/reroute +``` +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| `dry_run` | Boolean | When `true`, the request simulates the operation and returns the resulting state. | +| `explain` | Boolean | When `true`, the response contains an explanation of why certain commands can or cannot be executed. | +| `metric` | List or String | Limits the information returned to the specified metrics.
Valid values are: `_all`, `blocks`, `cluster_manager_node`, `master_node`, `metadata`, `nodes`, `routing_nodes`, `routing_table`, `version` | +| `retry_failed` | Boolean | When `true`, retries shard allocation if it was blocked because of too many subsequent failures. | +| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | + diff --git a/_api-reference/cluster-api/cluster-settings.md b/_api-reference/cluster-api/cluster-settings.md index 95a217a8dd..f8fae70e46 100644 --- a/_api-reference/cluster-api/cluster-settings.md +++ b/_api-reference/cluster-api/cluster-settings.md @@ -18,24 +18,37 @@ The cluster settings operation lets you check the current settings for your clus api: cluster.get_settings component: endpoints --> +## Endpoints +```json +GET /_cluster/settings +``` - - - +## Endpoints +```json +PUT /_cluster/settings +``` +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| `flat_settings` | Boolean | Returns settings in a flat format. _(Default: `false`)_ | +| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | + ## Request body fields diff --git a/_api-reference/cluster-api/cluster-state.md b/_api-reference/cluster-api/cluster-state.md index 8f6522c7ac..3155ed91bb 100644 --- a/_api-reference/cluster-api/cluster-state.md +++ b/_api-reference/cluster-api/cluster-state.md @@ -15,16 +15,47 @@ The Cluster state API returns comprehensive information about the state of the c api: cluster.state component: endpoints --> +## Endpoints +```json +GET /_cluster/state +GET /_cluster/state/{metric} +GET /_cluster/state/{metric}/{index} +``` +## Path parameters + +The following table lists the available path parameters. All path parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `index` | List or String | A comma-separated list of data streams, indexes, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams and indexes, omit this parameter or use `*` or `_all`. | +| `metric` | List | Limits the information returned to only the specified metrics. | + - \ No newline at end of file +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `allow_no_indices` | Boolean | Whether to ignore a wildcard index expression that resolves into no concrete indexes. This includes the `_all` string or when no indexes have been specified. | +| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| `expand_wildcards` | List or String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with open, closed, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes. | +| `flat_settings` | Boolean | Returns settings in a flat format. _(Default: `false`)_ | +| `ignore_unavailable` | Boolean | Whether the specified concrete indexes should be ignored when unavailable (missing or closed). | +| `local` | Boolean | Whether to return information from the local node only instead of from the cluster manager node. _(Default: `false`)_ | +| `wait_for_metadata_version` | Integer | Wait for the metadata version to be equal or greater than the specified metadata version. | +| `wait_for_timeout` | String | The maximum time to wait for `wait_for_metadata_version` before timing out. | +| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | + + diff --git a/_api-reference/cluster-api/cluster-stats.md b/_api-reference/cluster-api/cluster-stats.md index 80adfe5b5f..cb741ceea5 100644 --- a/_api-reference/cluster-api/cluster-stats.md +++ b/_api-reference/cluster-api/cluster-stats.md @@ -20,12 +20,29 @@ The cluster stats API operation returns statistics about your cluster. api: cluster.stats component: endpoints --> +## Endpoints +```json +GET /_cluster/stats +GET /_cluster/stats/nodes/{node_id} +GET /_cluster/stats/{metric}/nodes/{node_id} +GET /_cluster/stats/{metric}/{index_metric}/nodes/{node_id} +``` +## Path parameters + +The following table lists the available path parameters. All path parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `index_metric` | List | A comma-separated list of index metric groups, for example, `docs,store`. | +| `metric` | List | Limit the information returned to the specified metrics. | +| `node_id` | List or String | A comma-separated list of node IDs used to filter results. Supports [node filters]({{site.url}}{{site.baseurl}}/api-reference/nodes-apis/index/#node-filters). | + ### Metric groups diff --git a/_api-reference/cluster-api/cluster-voting-configuration.md b/_api-reference/cluster-api/cluster-voting-configuration.md index 562f2c3e93..8a06b914be 100644 --- a/_api-reference/cluster-api/cluster-voting-configuration.md +++ b/_api-reference/cluster-api/cluster-voting-configuration.md @@ -20,6 +20,9 @@ api: cluster.post_voting_config_exclusions component: endpoints omit_header: true --> +```json +POST /_cluster/voting_config_exclusions +``` The `DELETE` method clears any cluster voting configuration exclusions. @@ -29,16 +32,24 @@ api: cluster.delete_voting_config_exclusions component: endpoints omit_header: true --> +```json +DELETE /_cluster/voting_config_exclusions +``` - - - \ No newline at end of file +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `node_ids` | List or String | A comma-separated list of node IDs to exclude from the voting configuration. When using this setting, you cannot also specify `node_names`. | +| `node_names` | List or String | A comma-separated list of node names to exclude from the voting configuration. When using this setting, you cannot also specify `node_ids`. | +| `timeout` | String | When adding a voting configuration exclusion, the API waits for the specified nodes to be excluded from the voting configuration before returning a response. If the timeout expires before the appropriate condition is satisfied, the request fails and returns an error. | + + diff --git a/_api-reference/cluster-api/cluster-weighted-routing.md b/_api-reference/cluster-api/cluster-weighted-routing.md index 28eb7822a9..aa2d2d8426 100644 --- a/_api-reference/cluster-api/cluster-weighted-routing.md +++ b/_api-reference/cluster-api/cluster-weighted-routing.md @@ -20,27 +20,46 @@ api: cluster.get_weighted_routing component: endpoints omit_header: true --> +```json +GET /_cluster/routing/awareness/{attribute}/weights +``` The `PUT` method updates shard routing weights. +```json +PUT /_cluster/routing/awareness/{attribute}/weights +``` The `DELETE` method deletes shard routing weights. +```json +DELETE /_cluster/routing/awareness/weights +``` - \ No newline at end of file +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `attribute` | **Required** | String | The name of the awareness attribute. | + + + From 94b4cd1b9670db71f99bc18ce8dd6ea446f032e3 Mon Sep 17 00:00:00 2001 From: Archer Date: Tue, 4 Feb 2025 14:35:43 -0600 Subject: [PATCH 03/24] Adjust tables. Add example requests and responses. Signed-off-by: Archer --- .../cluster-api/cluster-allocation.md | 9 +- .../cluster-api/cluster-awareness.md | 9 +- .../cluster-api/cluster-component-template.md | 59 +++++- _api-reference/cluster-api/cluster-health.md | 1 + .../cluster-api/cluster-pending-tasks.md | 54 ++++- _api-reference/cluster-api/cluster-reroute.md | 186 +++++++++++++++++- .../cluster-api/cluster-settings.md | 13 +- _api-reference/cluster-api/cluster-state.md | 78 ++++++++ .../cluster-voting-configuration.md | 14 ++ .../cluster-api/cluster-weighted-routing.md | 35 ++++ 10 files changed, 424 insertions(+), 34 deletions(-) diff --git a/_api-reference/cluster-api/cluster-allocation.md b/_api-reference/cluster-api/cluster-allocation.md index 94430c3ace..6948cbee88 100644 --- a/_api-reference/cluster-api/cluster-allocation.md +++ b/_api-reference/cluster-api/cluster-allocation.md @@ -30,16 +30,17 @@ POST /_cluster/allocation/explain ## Query parameters The following table lists the available query parameters. All query parameters are optional. -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `include_disk_info` | Boolean | When `true`, returns information about disk usage and shard sizes. _(Default: `false`)_ | -| `include_yes_decisions` | Boolean | When `true`, returns any `YES` decisions in the allocation explanation. _(Default: `false`)_ | +| Parameter | Data type | Description | Default | +| :--- | :--- | :--- | :--- | +| `include_disk_info` | Boolean | When `true`, returns information about disk usage and shard sizes. | `false` | +| `include_yes_decisions` | Boolean | When `true`, returns any `YES` decisions in the allocation explanation. | `false` | diff --git a/_api-reference/cluster-api/cluster-awareness.md b/_api-reference/cluster-api/cluster-awareness.md index 2f888236f5..26dd3a4e66 100644 --- a/_api-reference/cluster-api/cluster-awareness.md +++ b/_api-reference/cluster-api/cluster-awareness.md @@ -37,16 +37,17 @@ PUT /_cluster/routing/awareness/{attribute}/weights ## Query parameters The following table lists the available query parameters. All query parameters are optional. -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `include_disk_info` | Boolean | When `true`, returns information about disk usage and shard sizes. _(Default: `false`)_ | -| `include_yes_decisions` | Boolean | When `true`, returns any `YES` decisions in the allocation explanation. _(Default: `false`)_ | +| Parameter | Data type | Description | Default | +| :--- | :--- | :--- | :--- | +| `include_disk_info` | Boolean | When `true`, returns information about disk usage and shard sizes. | `false` | +| `include_yes_decisions` | Boolean | When `true`, returns any `YES` decisions in the allocation explanation. | `false` | diff --git a/_api-reference/cluster-api/cluster-component-template.md b/_api-reference/cluster-api/cluster-component-template.md index 5dd838acd1..5dde2cb128 100644 --- a/_api-reference/cluster-api/cluster-component-template.md +++ b/_api-reference/cluster-api/cluster-component-template.md @@ -79,17 +79,64 @@ The following table lists the available path parameters. ## Query parameters The following table lists the available query parameters. All query parameters are optional. -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | -| `create` | Boolean | When `true`, this request cannot replace or update existing component templates. _(Default: `false`)_ | -| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | -| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| Parameter | Data type | Description | Default | +| :--- | :--- | :--- | :--- | +| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `create` | Boolean | When `true`, this request cannot replace or update existing component templates. | `false` | +| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | + +## Example request + +```json +POST /_component_template/logs_template +{ + "template": { + "settings": { + "number_of_shards": 1, + "number_of_replicas": 1 + }, + "mappings": { + "properties": { + "timestamp": { + "type": "date" + }, + "message": { + "type": "text" + }, + "level": { + "type": "keyword" + }, + "service": { + "type": "keyword" + } + } + }, + "aliases": { + "logs_alias": {} + } + }, + "version": 1, + "meta": { + "description": "Component template for log data" + } +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "acknowledged": true +} +``` diff --git a/_api-reference/cluster-api/cluster-health.md b/_api-reference/cluster-api/cluster-health.md index 6f99392c76..cebcf5b3c3 100644 --- a/_api-reference/cluster-api/cluster-health.md +++ b/_api-reference/cluster-api/cluster-health.md @@ -44,6 +44,7 @@ The following table lists the available path parameters. All path parameters are ## Query parameters diff --git a/_api-reference/cluster-api/cluster-pending-tasks.md b/_api-reference/cluster-api/cluster-pending-tasks.md index b5a7e644ec..614e77307e 100644 --- a/_api-reference/cluster-api/cluster-pending-tasks.md +++ b/_api-reference/cluster-api/cluster-pending-tasks.md @@ -25,16 +25,60 @@ GET /_cluster/pending_tasks ## Query parameters The following table lists the available query parameters. All query parameters are optional. -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | -| `local` | Boolean | When `true`, the request retrieves information from the local node only. When `false`, information is retrieved from the cluster manager node. _(Default: `false`)_ | -| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| Parameter | Data type | Description | Default | +| :--- | :--- | :--- | :--- | +| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `local` | Boolean | When `true`, the request retrieves information from the local node only. When `false`, information is retrieved from the cluster manager node. | `false` | +| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | + +## Example request + +```json +GET /_cluster/pending_tasks +``` + +## Example response + +```json +{ + "tasks": [ + { + "insert_order": 101, + "priority": "URGENT", + "source": "create-index [new_index]", + "time_in_queue_millis": 86, + "time_in_queue": "86ms" + }, + { + "insert_order": 102, + "priority": "HIGH", + "source": "shard-started ([new_index][0], node[tMTocMvQQgGCkj7QDHl3OA], [P], s[INITIALIZING])", + "time_in_queue_millis": 53, + "time_in_queue": "53ms" + }, + { + "insert_order": 103, + "priority": "HIGH", + "source": "shard-started ([new_index][1], node[tMTocMvQQgGCkj7QDHl3OA], [P], s[INITIALIZING])", + "time_in_queue_millis": 45, + "time_in_queue": "45ms" + }, + { + "insert_order": 104, + "priority": "NORMAL", + "source": "refresh-mapping [new_index]", + "time_in_queue_millis": 22, + "time_in_queue": "22ms" + } + ] +} +``` \ No newline at end of file diff --git a/_api-reference/cluster-api/cluster-reroute.md b/_api-reference/cluster-api/cluster-reroute.md index b60dc4d7d2..0dd7ab7712 100644 --- a/_api-reference/cluster-api/cluster-reroute.md +++ b/_api-reference/cluster-api/cluster-reroute.md @@ -24,19 +24,187 @@ POST /_cluster/reroute ## Query parameters The following table lists the available query parameters. All query parameters are optional. -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | -| `dry_run` | Boolean | When `true`, the request simulates the operation and returns the resulting state. | -| `explain` | Boolean | When `true`, the response contains an explanation of why certain commands can or cannot be executed. | -| `metric` | List or String | Limits the information returned to the specified metrics.
Valid values are: `_all`, `blocks`, `cluster_manager_node`, `master_node`, `metadata`, `nodes`, `routing_nodes`, `routing_table`, `version` | -| `retry_failed` | Boolean | When `true`, retries shard allocation if it was blocked because of too many subsequent failures. | -| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | -| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| Parameter | Data type | Description | Default | +| :--- | :--- | :--- | :--- | +| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `dry_run` | Boolean | When `true`, the request simulates the operation and returns the resulting state. | N/A | +| `explain` | Boolean | When `true`, the response contains an explanation of why certain commands can or cannot be executed. | N/A | +| `metric` | List or String | Limits the information returned to the specified metrics.
Valid values are: `_all`, `blocks`, `cluster_manager_node`, `master_node`, `metadata`, `nodes`, `routing_nodes`, `routing_table`, `version` | N/A | +| `retry_failed` | Boolean | When `true`, retries shard allocation if it was blocked because of too many subsequent failures. | N/A | +| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | + +## Request body options + +| Parameter | Data Type | Description | +| :--- | :--- | :--- | +| `commands` | Array | A list of reroute commands to run. | +| `dry_run` | Boolean | When true, simulates the reroute without actually performing it. | +| `explain` | Boolean | When true, returns detailed explanations of command decisions. | +| `retry_failed` | Boolean | When true, retries allocation of shards that failed in previous reroute attempts. | +| `metric` | String/Array | Limits the information returned to specific metrics. | +| `timeout` | Time | The period of time to wait for a response. | + +## Example request + +```json +POST /_cluster/reroute +{ + "commands": [ + { + "move": { + "index": "my_index", + "shard": 0, + "from_node": "node1", + "to_node": "node2" + } + }, + { + "allocate_replica": { + "index": "my_index", + "shard": 1, + "node": "node3" + } + }, + { + "cancel": { + "index": "my_index", + "shard": 2, + "node": "node4" + } + } + ], + "dry_run": false +} +``` + +## Example response + +```json +{ + "acknowledged": true, + "state": { + "version": 101, + "state_uuid": "8sj3yzsTSxKMrIhOzBoKRA", + "cluster_manager_node": "node1", + "blocks": {}, + "nodes": { + "node1": { + "name": "node1", + "transport_address": "127.0.0.1:9300" + }, + "node2": { + "name": "node2", + "transport_address": "127.0.0.2:9300" + }, + "node3": { + "name": "node3", + "transport_address": "127.0.0.3:9300" + }, + "node4": { + "name": "node4", + "transport_address": "127.0.0.4:9300" + } + }, + "routing_table": { + "indices": { + "my_index": { + "shards": { + "0": [ + { + "state": "STARTED", + "primary": true, + "node": "node2", + "relocating_node": null, + "shard": 0, + "index": "my_index" + } + ], + "1": [ + { + "state": "STARTED", + "primary": true, + "node": "node1", + "relocating_node": null, + "shard": 1, + "index": "my_index" + }, + { + "state": "INITIALIZING", + "primary": false, + "node": "node3", + "relocating_node": null, + "shard": 1, + "index": "my_index" + } + ], + "2": [ + { + "state": "STARTED", + "primary": true, + "node": "node1", + "relocating_node": null, + "shard": 2, + "index": "my_index" + } + ] + } + } + } + } + }, + "explanations": [ + { + "command": "move", + "parameters": { + "index": "my_index", + "shard": 0, + "from_node": "node1", + "to_node": "node2" + }, + "accepted": true + }, + { + "command": "allocate_replica", + "parameters": { + "index": "my_index", + "shard": 1, + "node": "node3" + }, + "accepted": true + }, + { + "command": "cancel", + "parameters": { + "index": "my_index", + "shard": 2, + "node": "node4" + }, + "accepted": true + } + ] +} +``` + +## Response body options + +| Parameter | Data Type | Description | +| :--- | :--- | :--- | +| `acknowledged` | Boolean | Indicates whether the request was acknowledged. | +| `state` | Object | The state of the current cluster after a reroute. | +| `explanations` | Array | The detailed explanations of command decisions when the `if explain` setting is `true`. | +| `state_uui`d | String | The UUID of the cluster state. | +| `cluster_manager_node` | String | The ID of the elected cluster manager node. | +| `version` | Integer | The version of the cluster state. | +| `blocks` | Object | The description of any cluster-level blocks. | +| `nodes` | Object | Any information about nodes in the cluster. | +| `routing_table` | Object | The current routing state of the cluster. | +| `routing_nodes` | Object | The node-level view of the routing table. | \ No newline at end of file diff --git a/_api-reference/cluster-api/cluster-settings.md b/_api-reference/cluster-api/cluster-settings.md index f8fae70e46..fa25440188 100644 --- a/_api-reference/cluster-api/cluster-settings.md +++ b/_api-reference/cluster-api/cluster-settings.md @@ -36,18 +36,19 @@ PUT /_cluster/settings ## Query parameters The following table lists the available query parameters. All query parameters are optional. -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | -| `flat_settings` | Boolean | Returns settings in a flat format. _(Default: `false`)_ | -| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | -| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| Parameter | Data type | Description | Default | +| :--- | :--- | :--- | :--- | +| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `flat_settings` | Boolean | Returns settings in a flat format. | `false` | +| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | diff --git a/_api-reference/cluster-api/cluster-state.md b/_api-reference/cluster-api/cluster-state.md index 3155ed91bb..f1af7e2a8c 100644 --- a/_api-reference/cluster-api/cluster-state.md +++ b/_api-reference/cluster-api/cluster-state.md @@ -59,3 +59,81 @@ The following table lists the available query parameters. All query parameters a | `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | + +## Example request + +```json +GET /_cluster/state/{metric} +``` + + +## Example response + +```json +{ + "cluster_name": "my_opensearch_cluster", + "cluster_uuid": "abcdefghijklmnopqrstuvwxyz", + "version": 42, + "state_uuid": "0123456789abcdefghij", + "master_node": "node-1", + "blocks": {}, + "metadata": { + "cluster_uuid": "abcdefghijklmnopqrstuvwxyz", + "cluster_coordination": { + "term": 5, + "last_committed_config": ["node-1", "node-2", "node-3"] + }, + "templates": {}, + "indices": { + "my_index": { + "state": "open", + "settings": { + "index": { + "number_of_shards": "5", + "number_of_replicas": "1", + "creation_date": "1623456789000" + } + }, + "mappings": {}, + "aliases": ["my_alias"] + } + } + }, + "routing_table": { + "indices": { + "my_index": { + "shards": { + "0": [ + { + "state": "STARTED", + "primary": true, + "node": "node-1", + "relocating_node": null + }, + { + "state": "STARTED", + "primary": false, + "node": "node-2", + "relocating_node": null + } + ], + "1": [ + { + "state": "STARTED", + "primary": true, + "node": "node-2", + "relocating_node": null + }, + { + "state": "STARTED", + "primary": false, + "node": "node-3", + "relocating_node": null + } + ] + } + } + } + } +} +``` \ No newline at end of file diff --git a/_api-reference/cluster-api/cluster-voting-configuration.md b/_api-reference/cluster-api/cluster-voting-configuration.md index 8a06b914be..717e1b2189 100644 --- a/_api-reference/cluster-api/cluster-voting-configuration.md +++ b/_api-reference/cluster-api/cluster-voting-configuration.md @@ -53,3 +53,17 @@ The following table lists the available query parameters. All query parameters a | `timeout` | String | When adding a voting configuration exclusion, the API waits for the specified nodes to be excluded from the voting configuration before returning a response. If the timeout expires before the appropriate condition is satisfied, the request fails and returns an error. | + +## Example request + +```json +POST /_cluster/voting_config_exclusions?node_names=node-3,node-4&timeout=30s +``` + +## Example response + +```json +{ + "acknowledged": true +} +``` diff --git a/_api-reference/cluster-api/cluster-weighted-routing.md b/_api-reference/cluster-api/cluster-weighted-routing.md index aa2d2d8426..44ee938df8 100644 --- a/_api-reference/cluster-api/cluster-weighted-routing.md +++ b/_api-reference/cluster-api/cluster-weighted-routing.md @@ -63,3 +63,38 @@ The following table lists the available path parameters. +## Example request + +```json +{ + "weights": { + "zone-1": 3, + "zone-2": 2, + "zone-3": 1 + } +} +``` + +## Example response + +```json +{ + "acknowledged": true, + "persistent": { + "cluster": { + "routing": { + "awareness": { + "zone": { + "weights": { + "zone-1": "3", + "zone-2": "2", + "zone-3": "1" + } + } + } + } + } + }, + "transient": {} +} +``` \ No newline at end of file From 645f9e1ede8c9f5066aca53d712d7f03b0041eaf Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 4 Feb 2025 14:53:27 -0600 Subject: [PATCH 04/24] Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _api-reference/cluster-api/cluster-reroute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/cluster-api/cluster-reroute.md b/_api-reference/cluster-api/cluster-reroute.md index 0dd7ab7712..01203d5080 100644 --- a/_api-reference/cluster-api/cluster-reroute.md +++ b/_api-reference/cluster-api/cluster-reroute.md @@ -44,7 +44,7 @@ The following table lists the available query parameters. All query parameters a ## Request body options -| Parameter | Data Type | Description | +| Parameter | Data type | Description | | :--- | :--- | :--- | | `commands` | Array | A list of reroute commands to run. | | `dry_run` | Boolean | When true, simulates the reroute without actually performing it. | From b713b3b672f8dfd089f014b5f15c72ea30724302 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 4 Feb 2025 15:03:58 -0600 Subject: [PATCH 05/24] Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _api-reference/cluster-api/cluster-reroute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/cluster-api/cluster-reroute.md b/_api-reference/cluster-api/cluster-reroute.md index 01203d5080..1927e0d09a 100644 --- a/_api-reference/cluster-api/cluster-reroute.md +++ b/_api-reference/cluster-api/cluster-reroute.md @@ -196,7 +196,7 @@ POST /_cluster/reroute ## Response body options -| Parameter | Data Type | Description | +| Parameter | Data type | Description | | :--- | :--- | :--- | | `acknowledged` | Boolean | Indicates whether the request was acknowledged. | | `state` | Object | The state of the current cluster after a reroute. | From 7550e90930e4a902000d49beae9986a3a96dfa92 Mon Sep 17 00:00:00 2001 From: Archer Date: Fri, 14 Feb 2025 11:23:43 -0600 Subject: [PATCH 06/24] Remove depracated parameters. Signed-off-by: Archer --- _api-reference/cluster-api/cluster-allocation.md | 9 ++++----- _api-reference/cluster-api/cluster-awareness.md | 4 ++-- _api-reference/cluster-api/cluster-component-template.md | 2 +- _api-reference/cluster-api/cluster-pending-tasks.md | 2 +- _api-reference/cluster-api/cluster-reroute.md | 2 +- _api-reference/cluster-api/cluster-settings.md | 2 +- 6 files changed, 10 insertions(+), 11 deletions(-) diff --git a/_api-reference/cluster-api/cluster-allocation.md b/_api-reference/cluster-api/cluster-allocation.md index 6948cbee88..ad2bdbeadb 100644 --- a/_api-reference/cluster-api/cluster-allocation.md +++ b/_api-reference/cluster-api/cluster-allocation.md @@ -15,7 +15,6 @@ redirect_from: The Cluster allocation explain API gives an explanation for how shards are allocated in the current cluster and provides an explanation for why unassigned shards can't be allocated to a node. - ## Query parameters @@ -91,7 +92,6 @@ The following table lists the available query parameters. All query parameters a | `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | | `create` | Boolean | When `true`, this request cannot replace or update existing component templates. | `false` | | `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | -| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | diff --git a/_api-reference/cluster-api/cluster-pending-tasks.md b/_api-reference/cluster-api/cluster-pending-tasks.md index 614e77307e..0e5cb28d8f 100644 --- a/_api-reference/cluster-api/cluster-pending-tasks.md +++ b/_api-reference/cluster-api/cluster-pending-tasks.md @@ -26,6 +26,7 @@ GET /_cluster/pending_tasks ## Query parameters @@ -36,7 +37,6 @@ The following table lists the available query parameters. All query parameters a | :--- | :--- | :--- | :--- | | `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | | `local` | Boolean | When `true`, the request retrieves information from the local node only. When `false`, information is retrieved from the cluster manager node. | `false` | -| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | diff --git a/_api-reference/cluster-api/cluster-reroute.md b/_api-reference/cluster-api/cluster-reroute.md index 1927e0d09a..2d63374abc 100644 --- a/_api-reference/cluster-api/cluster-reroute.md +++ b/_api-reference/cluster-api/cluster-reroute.md @@ -24,6 +24,7 @@ POST /_cluster/reroute ## Query parameters @@ -38,7 +39,6 @@ The following table lists the available query parameters. All query parameters a | `metric` | List or String | Limits the information returned to the specified metrics.
Valid values are: `_all`, `blocks`, `cluster_manager_node`, `master_node`, `metadata`, `nodes`, `routing_nodes`, `routing_table`, `version` | N/A | | `retry_failed` | Boolean | When `true`, retries shard allocation if it was blocked because of too many subsequent failures. | N/A | | `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | -| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | diff --git a/_api-reference/cluster-api/cluster-settings.md b/_api-reference/cluster-api/cluster-settings.md index fa25440188..246b48a13c 100644 --- a/_api-reference/cluster-api/cluster-settings.md +++ b/_api-reference/cluster-api/cluster-settings.md @@ -37,6 +37,7 @@ PUT /_cluster/settings ## Query parameters @@ -48,7 +49,6 @@ The following table lists the available query parameters. All query parameters a | `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | | `flat_settings` | Boolean | Returns settings in a flat format. | `false` | | `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | -| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | From 5fbb2c44bc9a2722b49c3c93d3afd04f30b7da57 Mon Sep 17 00:00:00 2001 From: Archer Date: Fri, 14 Feb 2025 11:26:27 -0600 Subject: [PATCH 07/24] One last deprecated parameter Signed-off-by: Archer --- _api-reference/cluster-api/cluster-health.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/cluster-api/cluster-health.md b/_api-reference/cluster-api/cluster-health.md index cebcf5b3c3..b23473508b 100644 --- a/_api-reference/cluster-api/cluster-health.md +++ b/_api-reference/cluster-api/cluster-health.md @@ -45,6 +45,7 @@ The following table lists the available path parameters. All path parameters are ## Query parameters @@ -65,7 +66,6 @@ The following table lists the available query parameters. All query parameters a | `wait_for_no_relocating_shards` | Boolean | Whether to wait until there are no relocating shards in the cluster. | N/A | | `wait_for_nodes` | Float or String | Waits until the specified number of nodes (`N`) is available. Accepts `>=N`, `<=N`, `>N`, and ` Valid values are: `green`, `GREEN`, `yellow`, `YELLOW`, `red`, `RED` | N/A | -| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | From 19b60e4a0c33955ae4e220c555d2849437cc5321 Mon Sep 17 00:00:00 2001 From: Archer Date: Fri, 14 Feb 2025 12:53:32 -0600 Subject: [PATCH 08/24] Description additions. Signed-off-by: Archer --- _api-reference/cluster-api/cluster-component-template.md | 2 +- _api-reference/cluster-api/cluster-health.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_api-reference/cluster-api/cluster-component-template.md b/_api-reference/cluster-api/cluster-component-template.md index bcc2a0031c..ca05d1d26c 100644 --- a/_api-reference/cluster-api/cluster-component-template.md +++ b/_api-reference/cluster-api/cluster-component-template.md @@ -73,7 +73,7 @@ The following table lists the available path parameters. | Parameter | Required | Data type | Description | | :--- | :--- | :--- | :--- | -| `name` | **Required** | String | The name of the component template to create. OpenSearch includes the following built-in component templates: `logs-mappings`; 'logs-settings`; `metrics-mappings`; `metrics-settings`;`synthetics-mapping`; `synthetics-settings`. OpenSearch uses these templates to configure backing indexes for its data streams. If you want to overwrite one of these templates, set the replacement template `version` to a higher value than the current version. If you want to disable all built-in component and index templates, set `stack.templates.enabled` to `false` using the Cluster Update Settings API. | +| `name` | **Required** | String | The name of the component template to create. OpenSearch includes the following built-in component templates: `logs-mappings`; `logs-settings`; `metrics-mappings`; `metrics-settings`; `synthetics-mapping`; `synthetics-settings`. OpenSearch uses these templates to configure backing indexes for its data streams. If you want to overwrite one of these templates, set the replacement template `version` to a higher value than the current version. If you want to disable all built-in component and index templates, set `stack.templates.enabled` to `false` using the Cluster Update Settings API. | diff --git a/_api-reference/cluster-api/cluster-health.md b/_api-reference/cluster-api/cluster-health.md index b23473508b..2c5ec3a7e6 100644 --- a/_api-reference/cluster-api/cluster-health.md +++ b/_api-reference/cluster-api/cluster-health.md @@ -57,7 +57,7 @@ The following table lists the available query parameters. All query parameters a | `awareness_attribute` | String | The name of the awareness attribute for which to return the cluster health status (for example, `zone`). Applicable only if `level` is set to `awareness_attributes`. | N/A | | `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | | `expand_wildcards` | List or String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with open, closed, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes. | N/A | -| `level` | String |
Valid values are: `awareness_attributes`, `cluster`, `indices`, `shards` | `cluster` | +| `level` | String | Controls the amount of detail included in the cluster health response.
Valid values are: `awareness_attributes`, `cluster`, `indices`, `shards` | `cluster` | | `local` | Boolean | Whether to return information from the local node only instead of from the cluster manager node. | `false` | | `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | | `wait_for_active_shards` | Integer or String | Waits until the specified number of shards is active before returning a response. Use `all` for all shards.
Valid values are: `all`, `index-setting` | N/A | From 7c8ea81f13db8507b57ae8203f15f70d660ecba4 Mon Sep 17 00:00:00 2001 From: Archer Date: Thu, 20 Feb 2025 11:33:38 -0600 Subject: [PATCH 09/24] Fix formatting error. Signed-off-by: Archer --- _api-reference/cluster-api/cluster-awareness.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/_api-reference/cluster-api/cluster-awareness.md b/_api-reference/cluster-api/cluster-awareness.md index debdf82c93..adb5ce8ce3 100644 --- a/_api-reference/cluster-api/cluster-awareness.md +++ b/_api-reference/cluster-api/cluster-awareness.md @@ -62,7 +62,7 @@ Parameter | Type | Description In the following example request body, `zone_1` and `zone_2` receive 50 requests each, whereas `zone_3` is prevented from receiving requests: -``` +```json { "weights": { @@ -140,6 +140,7 @@ OpenSearch responds with the weight of each zone: }, "_version":1 } +``` ## Next steps From 662c5070d32ec5265d243fbc626be99eee038aa8 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Fri, 21 Feb 2025 14:28:13 -0600 Subject: [PATCH 10/24] Apply suggestions from code review Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _api-reference/cluster-api/cluster-allocation.md | 2 +- _api-reference/cluster-api/cluster-component-template.md | 8 ++++---- _api-reference/cluster-api/cluster-decommission.md | 2 +- _api-reference/cluster-api/cluster-pending-tasks.md | 2 +- _api-reference/cluster-api/cluster-reroute.md | 6 +++--- _api-reference/cluster-api/cluster-state.md | 2 +- .../cluster-api/cluster-voting-configuration.md | 8 ++++---- _api-reference/cluster-api/cluster-weighted-routing.md | 2 +- 8 files changed, 16 insertions(+), 16 deletions(-) diff --git a/_api-reference/cluster-api/cluster-allocation.md b/_api-reference/cluster-api/cluster-allocation.md index ad2bdbeadb..14f2561e32 100644 --- a/_api-reference/cluster-api/cluster-allocation.md +++ b/_api-reference/cluster-api/cluster-allocation.md @@ -12,7 +12,7 @@ redirect_from: **Introduced 1.0** {: .label .label-purple } -The Cluster allocation explain API gives an explanation for how shards are allocated in the current cluster and provides an explanation for why unassigned shards can't be allocated to a node. +The Cluster Allocation Explain API explains how shards are allocated in the cluster and why unassigned shards cannot be assigned to a node. -The `EXISTS` method returns information about whether a particular component template exist. +The `EXISTS` method returns information about whether a component template exists: -The `PUT` method creates or updates a component template. +The `PUT` method creates or updates a component template: -The `DELETE` method deletes a component template. +The `DELETE` method deletes a component template: -## Request body options +## Request body fields | Parameter | Data type | Description | | :--- | :--- | :--- | @@ -194,7 +194,7 @@ POST /_cluster/reroute } ``` -## Response body options +## Response body fields | Parameter | Data type | Description | | :--- | :--- | :--- | diff --git a/_api-reference/cluster-api/cluster-state.md b/_api-reference/cluster-api/cluster-state.md index f1af7e2a8c..1dea10ead6 100644 --- a/_api-reference/cluster-api/cluster-state.md +++ b/_api-reference/cluster-api/cluster-state.md @@ -9,7 +9,7 @@ parent: Cluster APIs **Introduced 1.0** {: .label .label-purple } -The Cluster state API returns comprehensive information about the state of the cluster. +The Cluster State API returns comprehensive information about the state of the cluster. -The `DELETE` method clears any cluster voting configuration exclusions. +The `DELETE` method removes all exclusions from the voting configuration: +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `attribute` | **Required** | String | The name of the awareness attribute. | + + + + @@ -46,8 +60,6 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | -| `include_disk_info` | Boolean | When `true`, returns information about disk usage and shard sizes. | `false` | -| `include_yes_decisions` | Boolean | When `true`, returns any `YES` decisions in the allocation explanation. | `false` | diff --git a/_api-reference/cluster-api/cluster-pending-tasks.md b/_api-reference/cluster-api/cluster-pending-tasks.md index 763ca30423..df811b84b0 100644 --- a/_api-reference/cluster-api/cluster-pending-tasks.md +++ b/_api-reference/cluster-api/cluster-pending-tasks.md @@ -10,8 +10,7 @@ parent: Cluster APIs **Introduced 1.0** {: .label .label-purple } -The Cluster Pending Tasks API returns a list of pending cluster-level tasks, such as index creation, mapping updates, -or new allocations. +The Cluster Pending Tasks API returns a list of pending cluster-level tasks, such as index creation, mapping updates, or new allocations. ## Query parameters The following table lists the available query parameters. All query parameters are optional. -| Parameter | Data type | Description | Default | -| :--- | :--- | :--- | :--- | -| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | -| `dry_run` | Boolean | When `true`, the request simulates the operation and returns the resulting state. | N/A | -| `explain` | Boolean | When `true`, the response contains an explanation of why certain commands can or cannot be executed. | N/A | -| `metric` | List or String | Limits the information returned to the specified metrics.
Valid values are: `_all`, `blocks`, `cluster_manager_node`, `master_node`, `metadata`, `nodes`, `routing_nodes`, `routing_table`, `version` | N/A | -| `retry_failed` | Boolean | When `true`, retries shard allocation if it was blocked because of too many subsequent failures. | N/A | -| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| Parameter | Required | Data type | Description | Default | +| :--- | :--- | :--- | :--- | :--- | +| `cluster_manager_timeout` | _Optional_ | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `dry_run` | _Optional_ | Boolean | When `true`, the request simulates the operation and returns the resulting state. | N/A | +| `explain` | _Optional_ | Boolean | When `true`, the response contains an explanation of why certain commands can or cannot be executed. | N/A | +| `metric` | _Optional_ | List or String | Limits the information returned to the specified metrics.
Valid values are: `_all`, `blocks`, `cluster_manager_node`, `master_node`, `metadata`, `nodes`, `routing_nodes`, `routing_table`, `version` | N/A | +| `retry_failed` | _Optional_ | Boolean | When `true`, retries shard allocation if it was blocked because of too many subsequent failures. | N/A | +| `timeout` | _Optional_ | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | ## Request body fields -| Field | Data type | Description | -| :--- | :--- | :--- | -| `commands` | Array | A list of reroute commands to run. | -| `dry_run` | Boolean | When true, simulates the reroute without actually performing it. | -| `explain` | Boolean | When true, returns detailed explanations of command decisions. | -| `retry_failed` | Boolean | When true, retries allocation of shards that failed in previous reroute attempts. | -| `metric` | String/Array | Limits the information returned to specific metrics. | -| `timeout` | Time | The period of time to wait for a response. | +| Field | Data type | Description | Required +| :--- | :--- | :--- | :--- | +| `commands` | Array | A list of reroute commands to run. For a list of supported commands, see the [Cluster Reroute API schema](https://github.com/opensearch-project/opensearch-api-specification/blob/595fb05011fb0d13f2b535aa21b02554657db8dc/spec/schemas/cluster.reroute.yaml#L9-L55).| Required. | +| `dry_run` | Boolean | When true, simulates the reroute without actually performing it. | _Optional_ | +| `explain` | Boolean | When true, returns detailed explanations of command decisions. | _Optional_ | +| `retry_failed` | Boolean | When true, retries allocation of shards that failed in previous reroute attempts. | _Optional_ | +| `metric` | String/Array | Limits the information returned to specific metrics. | _Optional_ | +| `timeout` | Time | The period of time to wait for a response. | _Optional_ | ## Example request diff --git a/_api-reference/cluster-api/cluster-voting-configuration.md b/_api-reference/cluster-api/cluster-voting-configuration.md index 2d7675228d..2e99dc6470 100644 --- a/_api-reference/cluster-api/cluster-voting-configuration.md +++ b/_api-reference/cluster-api/cluster-voting-configuration.md @@ -59,6 +59,7 @@ The following table lists the available query parameters. All query parameters a ```json POST /_cluster/voting_config_exclusions?node_names=node-3,node-4&timeout=30s ``` +{% include copy-curl.html %} ## Example response From 96a153f032f9f11827e1d6d4f40400258fd23772 Mon Sep 17 00:00:00 2001 From: Archer Date: Tue, 4 Mar 2025 13:00:42 -0600 Subject: [PATCH 15/24] Fix code examples Signed-off-by: Archer --- _api-reference/cluster-api/cluster-reroute.md | 17 +++++++++-------- _api-reference/cluster-api/cluster-state.md | 2 +- .../cluster-api/cluster-weighted-routing.md | 2 ++ 3 files changed, 12 insertions(+), 9 deletions(-) diff --git a/_api-reference/cluster-api/cluster-reroute.md b/_api-reference/cluster-api/cluster-reroute.md index e2e0f284a5..9998a455a9 100644 --- a/_api-reference/cluster-api/cluster-reroute.md +++ b/_api-reference/cluster-api/cluster-reroute.md @@ -31,14 +31,14 @@ columns: Parameter, Required, Data type, Description, Default The following table lists the available query parameters. All query parameters are optional. -| Parameter | Required | Data type | Description | Default | -| :--- | :--- | :--- | :--- | :--- | -| `cluster_manager_timeout` | _Optional_ | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | -| `dry_run` | _Optional_ | Boolean | When `true`, the request simulates the operation and returns the resulting state. | N/A | -| `explain` | _Optional_ | Boolean | When `true`, the response contains an explanation of why certain commands can or cannot be executed. | N/A | -| `metric` | _Optional_ | List or String | Limits the information returned to the specified metrics.
Valid values are: `_all`, `blocks`, `cluster_manager_node`, `master_node`, `metadata`, `nodes`, `routing_nodes`, `routing_table`, `version` | N/A | -| `retry_failed` | _Optional_ | Boolean | When `true`, retries shard allocation if it was blocked because of too many subsequent failures. | N/A | -| `timeout` | _Optional_ | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| Parameter | Data type | Description | Default | +| :--- | :--- | :--- | :--- | +| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `dry_run` | Boolean | When `true`, the request simulates the operation and returns the resulting state. | N/A | +| `explain` | Boolean | When `true`, the response contains an explanation of why certain commands can or cannot be executed. | N/A | +| `metric` | List or String | Limits the information returned to the specified metrics.
Valid values are: `_all`, `blocks`, `cluster_manager_node`, `master_node`, `metadata`, `nodes`, `routing_nodes`, `routing_table`, `version` | N/A | +| `retry_failed` | Boolean | When `true`, retries shard allocation if it was blocked because of too many subsequent failures. | N/A | +| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | @@ -85,6 +85,7 @@ POST /_cluster/reroute "dry_run": false } ``` +{% include copy-curl.html %} ## Example response diff --git a/_api-reference/cluster-api/cluster-state.md b/_api-reference/cluster-api/cluster-state.md index 1dea10ead6..8ec0e4e909 100644 --- a/_api-reference/cluster-api/cluster-state.md +++ b/_api-reference/cluster-api/cluster-state.md @@ -75,7 +75,7 @@ GET /_cluster/state/{metric} "cluster_uuid": "abcdefghijklmnopqrstuvwxyz", "version": 42, "state_uuid": "0123456789abcdefghij", - "master_node": "node-1", + "cluster_manager_node": "node-1", "blocks": {}, "metadata": { "cluster_uuid": "abcdefghijklmnopqrstuvwxyz", diff --git a/_api-reference/cluster-api/cluster-weighted-routing.md b/_api-reference/cluster-api/cluster-weighted-routing.md index f39f195938..087d7daab0 100644 --- a/_api-reference/cluster-api/cluster-weighted-routing.md +++ b/_api-reference/cluster-api/cluster-weighted-routing.md @@ -66,6 +66,7 @@ The following table lists the available path parameters. ## Example request ```json +PUT /_cluster/routing/awareness/zone//weights { "weights": { "zone-1": 3, @@ -74,6 +75,7 @@ The following table lists the available path parameters. } } ``` +{% include copy-curl.html %} ## Example response From 1028bcde0dc7ceca38d5abe260da3b4b4def17c5 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 11 Mar 2025 17:22:51 -0500 Subject: [PATCH 16/24] Remove query parameters section Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _api-reference/cluster-api/cluster-awareness.md | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/_api-reference/cluster-api/cluster-awareness.md b/_api-reference/cluster-api/cluster-awareness.md index b3a7b8f889..ae309a747d 100644 --- a/_api-reference/cluster-api/cluster-awareness.md +++ b/_api-reference/cluster-api/cluster-awareness.md @@ -49,23 +49,11 @@ The following table lists the available path parameters. - -## Query parameters - -The following table lists the available query parameters. All query parameters are optional. - -| Parameter | Data type | Description | Default | -| :--- | :--- | :--- | :--- | - - - ## Request body fields +The following table lists the available request body fields. + Parameter | Type | Description :--- | :--- | :--- `weights` | JSON object | Assigns weights to attributes within the request body of the PUT request. Weights can be set in any ratio, for example, 2:3:5. In a 2:3:5 ratio with 3 zones, for every 100 requests sent to the cluster, each zone would receive either 20, 30, or 50 search requests in a random order. When assigned a weight of `0`, the zone does not receive any search traffic. From aaaa1d1382b46a65775153485cbb4d4e0b3df7e2 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 11 Mar 2025 17:25:52 -0500 Subject: [PATCH 17/24] Fix example request Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _api-reference/cluster-api/cluster-awareness.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/_api-reference/cluster-api/cluster-awareness.md b/_api-reference/cluster-api/cluster-awareness.md index ae309a747d..dc0813c757 100644 --- a/_api-reference/cluster-api/cluster-awareness.md +++ b/_api-reference/cluster-api/cluster-awareness.md @@ -63,6 +63,7 @@ Parameter | Type | Description In the following example request body, `zone_1` and `zone_2` receive 50 requests each, whereas `zone_3` is prevented from receiving requests: ```json +PUT /_cluster/routing/awareness/zone/weights { "weights": { @@ -73,6 +74,7 @@ In the following example request body, `zone_1` and `zone_2` receive 50 requests "_version" : 1 } ``` +{% include copy-curl.html %} ## Example requests @@ -80,7 +82,6 @@ In the following example request body, `zone_1` and `zone_2` receive 50 requests The following example request creates a round robin shard allocation for search traffic by using an undefined ratio: - ```json PUT /_cluster/routing/awareness/zone/weights { From 66dd54db77da92ae29c4d0b58450ced91579066b Mon Sep 17 00:00:00 2001 From: Archer Date: Tue, 11 Mar 2025 17:28:07 -0500 Subject: [PATCH 18/24] Add incoporated spec feedback Signed-off-by: Archer --- _api-reference/cluster-api/cluster-allocation.md | 2 +- _api-reference/cluster-api/cluster-awareness.md | 2 +- .../cluster-api/cluster-component-template.md | 2 +- .../cluster-api/cluster-decommission.md | 2 +- _api-reference/cluster-api/cluster-health.md | 12 ++++++------ .../cluster-api/cluster-pending-tasks.md | 2 +- _api-reference/cluster-api/cluster-reroute.md | 16 ++++++++-------- _api-reference/cluster-api/cluster-settings.md | 2 +- _api-reference/cluster-api/cluster-state.md | 2 +- .../cluster-api/cluster-weighted-routing.md | 2 +- 10 files changed, 22 insertions(+), 22 deletions(-) diff --git a/_api-reference/cluster-api/cluster-allocation.md b/_api-reference/cluster-api/cluster-allocation.md index 109200816b..6aaf26f062 100644 --- a/_api-reference/cluster-api/cluster-allocation.md +++ b/_api-reference/cluster-api/cluster-allocation.md @@ -39,7 +39,7 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | | `include_disk_info` | Boolean | When `true`, returns information about disk usage and shard sizes. | `false` | -| `include_yes_decisions` | Boolean | When `true`, returns any `YES` decisions in the allocation explanation. | `false` | +| `include_yes_decisions` | Boolean | When `true`, returns any `YES` decisions in the allocation explanation. `YES` decisions indicate when a particular shard allocation attempt was successful for the given node. | `false` | diff --git a/_api-reference/cluster-api/cluster-awareness.md b/_api-reference/cluster-api/cluster-awareness.md index dc0813c757..c5390743e0 100644 --- a/_api-reference/cluster-api/cluster-awareness.md +++ b/_api-reference/cluster-api/cluster-awareness.md @@ -45,7 +45,7 @@ The following table lists the available path parameters. | Parameter | Required | Data type | Description | | :--- | :--- | :--- | :--- | -| `attribute` | **Required** | String | The name of the awareness attribute. | +| `attribute` | **Required** | String | The name of awareness attribute, usually `zone`. | diff --git a/_api-reference/cluster-api/cluster-component-template.md b/_api-reference/cluster-api/cluster-component-template.md index 2cf7df9035..ed8e470c00 100644 --- a/_api-reference/cluster-api/cluster-component-template.md +++ b/_api-reference/cluster-api/cluster-component-template.md @@ -89,7 +89,7 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | -| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | N/A | | `create` | Boolean | When `true`, this request cannot replace or update existing component templates. | `false` | | `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | diff --git a/_api-reference/cluster-api/cluster-decommission.md b/_api-reference/cluster-api/cluster-decommission.md index 7a8a0c3ac3..bd689e5464 100644 --- a/_api-reference/cluster-api/cluster-decommission.md +++ b/_api-reference/cluster-api/cluster-decommission.md @@ -59,7 +59,7 @@ The following table lists the available path parameters. | Parameter | Required | Data type | Description | | :--- | :--- | :--- | :--- | | `awareness_attribute_name` | **Required** | String | The name of the awareness attribute. | -| `awareness_attribute_value` | **Required** | String | The value of the awareness attribute. | +| `awareness_attribute_value` | **Required** | String | The value of the awareness attribute. For example, if you have shards allocated in two different zones, you can give each zone a value of `zone-a` or `zoneb`. The cluster decommission operation decommissions the zone listed in the method. | diff --git a/_api-reference/cluster-api/cluster-health.md b/_api-reference/cluster-api/cluster-health.md index 2c5ec3a7e6..72220109c2 100644 --- a/_api-reference/cluster-api/cluster-health.md +++ b/_api-reference/cluster-api/cluster-health.md @@ -55,15 +55,15 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | | `awareness_attribute` | String | The name of the awareness attribute for which to return the cluster health status (for example, `zone`). Applicable only if `level` is set to `awareness_attributes`. | N/A | -| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | -| `expand_wildcards` | List or String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with open, closed, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes. | N/A | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | N/A | +| `expand_wildcards` | List or String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with open, closed, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes. | `open` | | `level` | String | Controls the amount of detail included in the cluster health response.
Valid values are: `awareness_attributes`, `cluster`, `indices`, `shards` | `cluster` | | `local` | Boolean | Whether to return information from the local node only instead of from the cluster manager node. | `false` | -| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | -| `wait_for_active_shards` | Integer or String | Waits until the specified number of shards is active before returning a response. Use `all` for all shards.
Valid values are: `all`, `index-setting` | N/A | -| `wait_for_events` | String | Waits until all currently queued events with the given priority are processed.
Valid values are: `high`, `immediate`, `languid`, `low`, `normal`, `urgent` | N/A | +| `timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | N/A | +| `wait_for_active_shards` | Integer or String | Waits until the specified number of shards is active before returning a response. Use `all` for all shards.
Valid values are: `all`, `index-setting` | `0` | +| `wait_for_events` | String | Waits until all currently queued events with the given priority are processed.
Valid values are:
- `immediate`: Highest priority, processed as soon as possible.
- `urgent`: Very high priority, processed after immediate events.
- `high`: High priority, processed after urgent events.
- `normal`: Default priority, processed after high priority events.
- `low`: Low priority, processed after normal events.
- `languid`: Lowest priority, processed after all other events. | N/A | | `wait_for_no_initializing_shards` | Boolean | Whether to wait until there are no initializing shards in the cluster. | `false` | -| `wait_for_no_relocating_shards` | Boolean | Whether to wait until there are no relocating shards in the cluster. | N/A | +| `wait_for_no_relocating_shards` | Boolean | Whether to wait until there are no relocating shards in the cluster. | `false` | | `wait_for_nodes` | Float or String | Waits until the specified number of nodes (`N`) is available. Accepts `>=N`, `<=N`, `>N`, and ` Valid values are: `green`, `GREEN`, `yellow`, `YELLOW`, `red`, `RED` | N/A | diff --git a/_api-reference/cluster-api/cluster-pending-tasks.md b/_api-reference/cluster-api/cluster-pending-tasks.md index df811b84b0..627de6b140 100644 --- a/_api-reference/cluster-api/cluster-pending-tasks.md +++ b/_api-reference/cluster-api/cluster-pending-tasks.md @@ -34,7 +34,7 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | -| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | N/A | | `local` | Boolean | When `true`, the request retrieves information from the local node only. When `false`, information is retrieved from the cluster manager node. | `false` | diff --git a/_api-reference/cluster-api/cluster-reroute.md b/_api-reference/cluster-api/cluster-reroute.md index 9998a455a9..d298763937 100644 --- a/_api-reference/cluster-api/cluster-reroute.md +++ b/_api-reference/cluster-api/cluster-reroute.md @@ -31,14 +31,14 @@ columns: Parameter, Required, Data type, Description, Default The following table lists the available query parameters. All query parameters are optional. -| Parameter | Data type | Description | Default | -| :--- | :--- | :--- | :--- | -| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | -| `dry_run` | Boolean | When `true`, the request simulates the operation and returns the resulting state. | N/A | -| `explain` | Boolean | When `true`, the response contains an explanation of why certain commands can or cannot be executed. | N/A | -| `metric` | List or String | Limits the information returned to the specified metrics.
Valid values are: `_all`, `blocks`, `cluster_manager_node`, `master_node`, `metadata`, `nodes`, `routing_nodes`, `routing_table`, `version` | N/A | -| `retry_failed` | Boolean | When `true`, retries shard allocation if it was blocked because of too many subsequent failures. | N/A | -| `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| Parameter | Required | Data type | Description | Default | +| :--- | :--- | :--- | :--- | :--- | +| `cluster_manager_timeout` | _Optional_ | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | N/A | +| `dry_run` | _Optional_ | Boolean | When `true`, the request simulates the operation and returns the resulting state. | N/A | +| `explain` | _Optional_ | Boolean | When `true`, the response contains an explanation of why reroute certain commands can or cannot be executed. | N/A | +| `metric` | _Optional_ | List or String | Limits the information returned to the specified metrics.
Valid values are:
- `_all`: Returns all available metrics.
- `blocks`: Returns information about cluster-level blocks.
- `cluster_manager_node`: Returns information about the current cluster manager node.
- `master_node`: The alias for `cluster_manager_node`. Deprecated, but maintained for backwards compatibility.
- `metadata`: Returns the cluster state metadata.
- `nodes`: Returns information about nodes in the cluster.
- `routing_nodes`: Returns the node-level shard allocations.
- `routing_table`: Returns index-level shard allocations.
- `version`: Returns the cluster state version. | N/A | +| `retry_failed` | _Optional_ | Boolean | When `true`, retries shard allocation if it was blocked because of too many subsequent failures. | N/A | +| `timeout` | _Optional_ | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | diff --git a/_api-reference/cluster-api/cluster-settings.md b/_api-reference/cluster-api/cluster-settings.md index 246b48a13c..bc9c08b714 100644 --- a/_api-reference/cluster-api/cluster-settings.md +++ b/_api-reference/cluster-api/cluster-settings.md @@ -46,7 +46,7 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | -| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | N/A | | `flat_settings` | Boolean | Returns settings in a flat format. | `false` | | `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | diff --git a/_api-reference/cluster-api/cluster-state.md b/_api-reference/cluster-api/cluster-state.md index 8ec0e4e909..29f2e18bd5 100644 --- a/_api-reference/cluster-api/cluster-state.md +++ b/_api-reference/cluster-api/cluster-state.md @@ -49,7 +49,7 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | | :--- | :--- | :--- | | `allow_no_indices` | Boolean | Whether to ignore a wildcard index expression that resolves into no concrete indexes. This includes the `_all` string or when no indexes have been specified. | -| `cluster_manager_timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | | `expand_wildcards` | List or String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with open, closed, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes. | | `flat_settings` | Boolean | Returns settings in a flat format. _(Default: `false`)_ | | `ignore_unavailable` | Boolean | Whether the specified concrete indexes should be ignored when unavailable (missing or closed). | diff --git a/_api-reference/cluster-api/cluster-weighted-routing.md b/_api-reference/cluster-api/cluster-weighted-routing.md index 087d7daab0..519b27686a 100644 --- a/_api-reference/cluster-api/cluster-weighted-routing.md +++ b/_api-reference/cluster-api/cluster-weighted-routing.md @@ -59,7 +59,7 @@ The following table lists the available path parameters. | Parameter | Required | Data type | Description | | :--- | :--- | :--- | :--- | -| `attribute` | **Required** | String | The name of the awareness attribute. | +| `attribute` | **Required** | String | The name of awareness attribute, usually `zone`. | From 276d0fee7294cf00df3e3168bb5ed1bc9291ac5c Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 11 Mar 2025 17:32:31 -0500 Subject: [PATCH 19/24] Update cluster-reroute.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _api-reference/cluster-api/cluster-reroute.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/_api-reference/cluster-api/cluster-reroute.md b/_api-reference/cluster-api/cluster-reroute.md index d298763937..34944e2390 100644 --- a/_api-reference/cluster-api/cluster-reroute.md +++ b/_api-reference/cluster-api/cluster-reroute.md @@ -44,6 +44,8 @@ The following table lists the available query parameters. All query parameters a ## Request body fields +The following table lists the available request body fields. + | Field | Data type | Description | Required | :--- | :--- | :--- | :--- | | `commands` | Array | A list of reroute commands to run. For a list of supported commands, see the [Cluster Reroute API schema](https://github.com/opensearch-project/opensearch-api-specification/blob/595fb05011fb0d13f2b535aa21b02554657db8dc/spec/schemas/cluster.reroute.yaml#L9-L55).| Required. | @@ -197,6 +199,8 @@ POST /_cluster/reroute ## Response body fields +The following table lists the available response body fields. + | Field | Data type | Description | | :--- | :--- | :--- | | `acknowledged` | Boolean | Indicates whether the request was acknowledged. | @@ -208,4 +212,4 @@ POST /_cluster/reroute | `blocks` | Object | The description of any cluster-level blocks. | | `nodes` | Object | Any information about nodes in the cluster. | | `routing_table` | Object | The current routing state of the cluster. | -| `routing_nodes` | Object | The node-level view of the routing table. | \ No newline at end of file +| `routing_nodes` | Object | The node-level view of the routing table. | From bb0b96bbb228e5c1f4fd35498e134817d657a8c0 Mon Sep 17 00:00:00 2001 From: Archer Date: Tue, 11 Mar 2025 17:49:04 -0500 Subject: [PATCH 20/24] Additional feedback Signed-off-by: Archer --- _api-reference/cluster-api/cluster-health.md | 4 +- _api-reference/cluster-api/cluster-state.md | 40 +++++++++++++++++++- 2 files changed, 40 insertions(+), 4 deletions(-) diff --git a/_api-reference/cluster-api/cluster-health.md b/_api-reference/cluster-api/cluster-health.md index 72220109c2..264536aa16 100644 --- a/_api-reference/cluster-api/cluster-health.md +++ b/_api-reference/cluster-api/cluster-health.md @@ -13,7 +13,7 @@ redirect_from: **Introduced 1.0** {: .label .label-purple } -The most basic cluster health request returns a simple status of the health of your cluster. OpenSearch expresses cluster health in three colors: green, yellow, and red. A green status means all primary shards and their replicas are allocated to nodes. A yellow status means all primary shards are allocated to nodes, but some replicas aren't. A red status means at least one primary shard is not allocated to any node. +The Cluster Health API returns a simple status of the health of your cluster. OpenSearch expresses cluster health in three colors: green, yellow, and red. A green status means all primary shards and their replicas are allocated to nodes. A yellow status means all primary shards are allocated to nodes, but some replicas aren't. A red status means at least one primary shard is not allocated to any node. To get the status of a specific index, provide the index name. @@ -72,7 +72,7 @@ The following table lists the available query parameters. All query parameters a ## Example requests -The following examples show how to use the cluster health API. +The following examples show how to use the Cluster Health API. This request waits 50 seconds for the cluster to reach the yellow status or better: diff --git a/_api-reference/cluster-api/cluster-state.md b/_api-reference/cluster-api/cluster-state.md index 29f2e18bd5..ca9a7dba4a 100644 --- a/_api-reference/cluster-api/cluster-state.md +++ b/_api-reference/cluster-api/cluster-state.md @@ -38,9 +38,41 @@ The following table lists the available path parameters. All path parameters are +### Supported metrics + +If you want to isolate the cluster state response to a specific metric, use one or more of the following: + +- `cluster_name` +- `cluster_uuid` +- `version` +- `state_uuid` +- `cluster_manager_node` +- `blocks` +- `nodes` +- `metadata` + - `cluster_uuid` + - `templates` + - `indices` + - `index-graveyard` + - `cluster_coordination` + - `ingest` + - `repositories` + - `component_template` + - `index_template` + - `data_stream` + - `aliases` +- `routing_table` + - `indices` +- `routing_nodes` +- `customs` +- `snapshots` +- `restore` +- `snapshot_deletions` + ## Query parameters @@ -60,12 +92,16 @@ The following table lists the available query parameters. All query parameters a + + ## Example request +The following example request lists the full cluster state. + ```json -GET /_cluster/state/{metric} +GET /_cluster/state/ ``` - +{% include copy-curl.html %} ## Example response From 6862a8561be11d87d3f9d119ab71d918c8671f32 Mon Sep 17 00:00:00 2001 From: Archer Date: Tue, 11 Mar 2025 18:36:14 -0500 Subject: [PATCH 21/24] Remove deprecated setting Signed-off-by: Archer --- _api-reference/cluster-api/cluster-state.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/_api-reference/cluster-api/cluster-state.md b/_api-reference/cluster-api/cluster-state.md index ca9a7dba4a..d6341e40c9 100644 --- a/_api-reference/cluster-api/cluster-state.md +++ b/_api-reference/cluster-api/cluster-state.md @@ -72,7 +72,7 @@ If you want to isolate the cluster state response to a specific metric, use one ## Query parameters @@ -88,12 +88,10 @@ The following table lists the available query parameters. All query parameters a | `local` | Boolean | Whether to return information from the local node only instead of from the cluster manager node. _(Default: `false`)_ | | `wait_for_metadata_version` | Integer | Wait for the metadata version to be equal or greater than the specified metadata version. | | `wait_for_timeout` | String | The maximum time to wait for `wait_for_metadata_version` before timing out. | -| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | - ## Example request The following example request lists the full cluster state. From 9f8070c5a998f715a9e73d04b4a11a82b73d6b50 Mon Sep 17 00:00:00 2001 From: Archer Date: Mon, 17 Mar 2025 13:52:42 -0500 Subject: [PATCH 22/24] Add latest spec edits Signed-off-by: Archer --- _api-reference/cluster-api/cluster-component-template.md | 2 +- _api-reference/cluster-api/cluster-settings.md | 2 +- _api-reference/cluster-api/cluster-state.md | 4 ++-- _api-reference/cluster-api/cluster-stats.md | 2 +- _api-reference/cluster-api/cluster-voting-configuration.md | 4 ++-- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/_api-reference/cluster-api/cluster-component-template.md b/_api-reference/cluster-api/cluster-component-template.md index ed8e470c00..207fbbb0bc 100644 --- a/_api-reference/cluster-api/cluster-component-template.md +++ b/_api-reference/cluster-api/cluster-component-template.md @@ -73,7 +73,7 @@ The following table lists the available path parameters. | Parameter | Required | Data type | Description | | :--- | :--- | :--- | :--- | -| `name` | **Required** | String | The name of the component template to create. OpenSearch includes the following built-in component templates: `logs-mappings`; `logs-settings`; `metrics-mappings`; `metrics-settings`; `synthetics-mapping`; `synthetics-settings`. OpenSearch uses these templates to configure backing indexes for its data streams. If you want to overwrite one of these templates, set the replacement template `version` to a higher value than the current version. If you want to disable all built-in component and index templates, set `stack.templates.enabled` to `false` using the Cluster Update Settings API. | +| `name` | **Required** | String | The name of the component template to create. OpenSearch includes the following built-in component templates: `logs-mappings`, `logs-settings`, `metrics-mappings`, `metrics-settings`, `synthetics-mapping`, and `synthetics-settings`. OpenSearch uses these templates to configure backing indexes for its data streams. If you want to overwrite one of these templates, set the replacement template `version` to a higher value than the current version. If you want to disable all built-in component and index templates, set `stack.templates.enabled` to `false` using the [Cluster Update Settings API]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-settings/). | diff --git a/_api-reference/cluster-api/cluster-settings.md b/_api-reference/cluster-api/cluster-settings.md index bc9c08b714..1dbca5edb8 100644 --- a/_api-reference/cluster-api/cluster-settings.md +++ b/_api-reference/cluster-api/cluster-settings.md @@ -47,7 +47,7 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | | `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | N/A | -| `flat_settings` | Boolean | Returns settings in a flat format. | `false` | +| `flat_settings` | Boolean | Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings. For example, the flat form of `"cluster": { "max_shards_per_node": 500 }` is `"cluster.max_shards_per_node": "500"`. | `false` | | `timeout` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. | N/A | diff --git a/_api-reference/cluster-api/cluster-state.md b/_api-reference/cluster-api/cluster-state.md index d6341e40c9..3baa21730d 100644 --- a/_api-reference/cluster-api/cluster-state.md +++ b/_api-reference/cluster-api/cluster-state.md @@ -34,7 +34,7 @@ The following table lists the available path parameters. All path parameters are | Parameter | Data type | Description | | :--- | :--- | :--- | | `index` | List or String | A comma-separated list of data streams, indexes, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams and indexes, omit this parameter or use `*` or `_all`. | -| `metric` | List | Limits the information returned to only the specified metrics. | +| `metric` | List | Limits the information returned to only the [specified metric groups]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-stats/#metric-groups). | @@ -83,7 +83,7 @@ The following table lists the available query parameters. All query parameters a | `allow_no_indices` | Boolean | Whether to ignore a wildcard index expression that resolves into no concrete indexes. This includes the `_all` string or when no indexes have been specified. | | `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | | `expand_wildcards` | List or String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with open, closed, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes. | -| `flat_settings` | Boolean | Returns settings in a flat format. _(Default: `false`)_ | +| `flat_settings` | Boolean | Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings. For example, the flat form of `"cluster": { "max_shards_per_node": 500 }` is `"cluster.max_shards_per_node": "500"`. _(Default: `false`)_ | | `ignore_unavailable` | Boolean | Whether the specified concrete indexes should be ignored when unavailable (missing or closed). | | `local` | Boolean | Whether to return information from the local node only instead of from the cluster manager node. _(Default: `false`)_ | | `wait_for_metadata_version` | Integer | Wait for the metadata version to be equal or greater than the specified metadata version. | diff --git a/_api-reference/cluster-api/cluster-stats.md b/_api-reference/cluster-api/cluster-stats.md index cb741ceea5..905b0ec3db 100644 --- a/_api-reference/cluster-api/cluster-stats.md +++ b/_api-reference/cluster-api/cluster-stats.md @@ -39,7 +39,7 @@ The following table lists the available path parameters. All path parameters are | Parameter | Data type | Description | | :--- | :--- | :--- | -| `index_metric` | List | A comma-separated list of index metric groups, for example, `docs,store`. | +| `index_metric` | List | A comma-separated list of [index metric groups]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-stats/#index-metric-groups), for example, `docs,store`. | | `metric` | List | Limit the information returned to the specified metrics. | | `node_id` | List or String | A comma-separated list of node IDs used to filter results. Supports [node filters]({{site.url}}{{site.baseurl}}/api-reference/nodes-apis/index/#node-filters). | diff --git a/_api-reference/cluster-api/cluster-voting-configuration.md b/_api-reference/cluster-api/cluster-voting-configuration.md index 2e99dc6470..db720054d9 100644 --- a/_api-reference/cluster-api/cluster-voting-configuration.md +++ b/_api-reference/cluster-api/cluster-voting-configuration.md @@ -48,8 +48,8 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | | :--- | :--- | :--- | -| `node_ids` | List or String | A comma-separated list of node IDs to exclude from the voting configuration. When using this setting, you cannot also specify `node_names`. | -| `node_names` | List or String | A comma-separated list of node names to exclude from the voting configuration. When using this setting, you cannot also specify `node_ids`. | +| `node_ids` | List or String | A comma-separated list of node IDs to exclude from the voting configuration. When using this setting, you cannot also specify `node_names`. Either `node_ids` or `node_names` are required to receive a valid response. | +| `node_names` | List or String | A comma-separated list of node names to exclude from the voting configuration. When using this setting, you cannot also specify `node_ids`. Either `node_ids` or `node_names` are required to receive a valid response. | | `timeout` | String | When adding a voting configuration exclusion, the API waits for the specified nodes to be excluded from the voting configuration before returning a response. If the timeout expires before the appropriate condition is satisfied, the request fails and returns an error. | From 1abf796cdfceec053c18771a683d82dd39be8d6f Mon Sep 17 00:00:00 2001 From: Archer Date: Mon, 24 Mar 2025 12:24:21 -0500 Subject: [PATCH 23/24] Add updated spec information Signed-off-by: Archer --- _api-reference/cat/cat-allocation.md | 2 +- _api-reference/cat/cat-field-data.md | 3 ++- _api-reference/cat/cat-health.md | 2 +- _api-reference/cat/cat-indices.md | 6 +++--- _api-reference/cat/cat-nodes.md | 4 ++-- _api-reference/cat/cat-pending-tasks.md | 2 +- _api-reference/cat/cat-pit-segments.md | 2 +- _api-reference/cat/cat-recovery.md | 5 +++-- _api-reference/cat/cat-segment-replication.md | 5 +++-- _api-reference/cat/cat-segments.md | 2 +- _api-reference/cat/cat-shards.md | 4 ++-- _api-reference/cat/cat-snapshots.md | 5 +++-- _api-reference/cat/cat-tasks.md | 2 +- _api-reference/cluster-api/cluster-health.md | 6 +++--- _api-reference/tasks/list-tasks.md | 2 +- 15 files changed, 28 insertions(+), 24 deletions(-) diff --git a/_api-reference/cat/cat-allocation.md b/_api-reference/cat/cat-allocation.md index c1393d5135..f0e2859680 100644 --- a/_api-reference/cat/cat-allocation.md +++ b/_api-reference/cat/cat-allocation.md @@ -40,7 +40,7 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | -| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, `p` | N/A | +| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, and `p`. | N/A | | `cluster_manager_timeout` | String | A timeout for connection to the cluster manager node. | N/A | | `format` | String | A short version of the HTTP `Accept` header, such as `json` or `yaml`. | N/A | | `h` | List | A comma-separated list of column names to display. | N/A | diff --git a/_api-reference/cat/cat-field-data.md b/_api-reference/cat/cat-field-data.md index 01d207a016..1d16495d3e 100644 --- a/_api-reference/cat/cat-field-data.md +++ b/_api-reference/cat/cat-field-data.md @@ -38,7 +38,8 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | -| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, `p` | N/A | +| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, and `p`. | N/A | +| `fields` | List or String | A comma-separated list of fields used to limit the amount of returned information. | N/A | | `format` | String | A short version of the `Accept` header, such as `json` or `yaml`. | N/A | | `h` | List | A comma-separated list of column names to display. | N/A | | `help` | Boolean | Returns help information. | `false` | diff --git a/_api-reference/cat/cat-health.md b/_api-reference/cat/cat-health.md index 8477134b28..f81701ddba 100644 --- a/_api-reference/cat/cat-health.md +++ b/_api-reference/cat/cat-health.md @@ -42,7 +42,7 @@ The following table lists the available query parameters. All query parameters a | `h` | List | A comma-separated list of column names to display. | N/A | | `help` | Boolean | Returns help information. | `false` | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | The unit used to display time values.
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | The unit used to display time values.
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, and `d`. | N/A | | `ts` | Boolean | When `true`, returns `HH:MM:SS` and Unix epoch timestamps. | `true` | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-indices.md b/_api-reference/cat/cat-indices.md index 23cc44f69f..dfb416ae0e 100644 --- a/_api-reference/cat/cat-indices.md +++ b/_api-reference/cat/cat-indices.md @@ -39,18 +39,18 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | -| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, `p` | N/A | +| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, and `p`. | N/A | | `cluster_manager_timeout` | String | The amount of time allowed to establish a connection to the cluster manager node. | N/A | | `expand_wildcards` | List or String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with open, closed, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes. | N/A | | `format` | String | A short version of the `Accept` header, such as `json` or `yaml`. | N/A | | `h` | List | A comma-separated list of column names to display. | N/A | -| `health` | String | Limits indexes based on their health status. Supported values are `green`, `yellow`, and `red`.
Valid values are: `green`, `GREEN`, `yellow`, `YELLOW`, `red`, `RED` | N/A | +| `health` | String | Limits indexes based on their health status. Supported values are `green`, `yellow`, and `red`.
Valid values are: `green`, `GREEN`, `yellow`, `YELLOW`, `red`, and `RED`. | N/A | | `help` | Boolean | Returns help information. | `false` | | `include_unloaded_segments` | Boolean | Whether to include information from segments not loaded into memory. | `false` | | `local` | Boolean | Returns local information but does not retrieve the state from the cluster manager node. | `false` | | `pri` | Boolean | When `true`, returns information only from the primary shards. | `false` | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units.
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units.
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, and `d`. | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-nodes.md b/_api-reference/cat/cat-nodes.md index e5c64f6430..ca0cf3e7d5 100644 --- a/_api-reference/cat/cat-nodes.md +++ b/_api-reference/cat/cat-nodes.md @@ -40,14 +40,14 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | -| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, `p` | N/A | +| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, and `p`. | N/A | | `cluster_manager_timeout` | String | The amount of time allowed to establish a connection to the cluster manager node. | N/A | | `format` | String | A short version of the `Accept` header, such as `json` or `yaml`. | N/A | | `full_id` | Boolean or String | When `true`, returns the full node ID. When `false`, returns the shortened node ID. | `false` | | `h` | List | A comma-separated list of column names to display. | N/A | | `help` | Boolean | Returns help information. | `false` | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, and `d`. | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-pending-tasks.md b/_api-reference/cat/cat-pending-tasks.md index 41a9575d67..6b2674b4da 100644 --- a/_api-reference/cat/cat-pending-tasks.md +++ b/_api-reference/cat/cat-pending-tasks.md @@ -44,7 +44,7 @@ The following table lists the available query parameters. All query parameters a | `help` | Boolean | Returns help information. | `false` | | `local` | Boolean | Returns local information but does not retrieve the state from the cluster manager node. | `false` | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, and `d`. | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-pit-segments.md b/_api-reference/cat/cat-pit-segments.md index bad46ae15c..e4730de55f 100644 --- a/_api-reference/cat/cat-pit-segments.md +++ b/_api-reference/cat/cat-pit-segments.md @@ -43,7 +43,7 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | -| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, `p` | N/A | +| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, and `p`. | N/A | | `format` | String | A short version of the `Accept` header, such as `json` or `yaml`. | N/A | | `h` | List | A comma-separated list of column names to display. | N/A | | `help` | Boolean | Returns help information. | `false` | diff --git a/_api-reference/cat/cat-recovery.md b/_api-reference/cat/cat-recovery.md index de40eb0388..b6ab40a088 100644 --- a/_api-reference/cat/cat-recovery.md +++ b/_api-reference/cat/cat-recovery.md @@ -40,13 +40,14 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | | `active_only` | Boolean | If `true`, the response only includes ongoing shard recoveries. | `false` | -| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, `p` | N/A | +| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, and `p`. | N/A | | `detailed` | Boolean | When `true`, includes detailed information about shard recoveries. | `false` | | `format` | String | A short version of the `Accept` header, such as `json` or `yaml`. | N/A | | `h` | List | A comma-separated list of column names to display. | N/A | | `help` | Boolean | Returns help information. | `false` | +| `index` | List | A comma-separated list of data streams, indexes, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams and indexes, omit this parameter or use `*` or `_all`. | N/A | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, and `d`. | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-segment-replication.md b/_api-reference/cat/cat-segment-replication.md index 7dbe3b4ebd..2d4a992922 100644 --- a/_api-reference/cat/cat-segment-replication.md +++ b/_api-reference/cat/cat-segment-replication.md @@ -57,7 +57,7 @@ The following table lists the available query parameters. All query parameters a | :--- | :--- | :--- | :--- | | `active_only` | Boolean | When `true`, the response only includes ongoing segment replication events. | `false` | | `allow_no_indices` | Boolean | Whether to ignore the index if a wildcard index expression resolves to no concrete indexes. This includes the `_all` string or when no indexes have been specified. | N/A | -| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, `p` | N/A | +| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, and `p`. | N/A | | `completed_only` | Boolean | When `true`, the response only includes the last-completed segment replication events. | `false` | | `detailed` | Boolean | When `true`, the response includes additional metrics for each stage of a segment replication event. | `false` | | `expand_wildcards` | List or String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with open, closed, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes. | N/A | @@ -66,9 +66,10 @@ The following table lists the available query parameters. All query parameters a | `help` | Boolean | Returns help information. | `false` | | `ignore_throttled` | Boolean | Whether specified concrete, expanded, or aliased indexes should be ignored when throttled. | N/A | | `ignore_unavailable` | Boolean | Whether the specified concrete indexes should be ignored when missing or closed. | N/A | +| `index` | List | A comma-separated list of data streams, indexes, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams and indexes, omit this parameter or use `*` or `_all`. | N/A | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | | `shards` | List | A comma-separated list of shards to display. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, and `d`. | N/A | | `timeout` | String | The operation timeout. | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-segments.md b/_api-reference/cat/cat-segments.md index 03df94492e..6f65cc82de 100644 --- a/_api-reference/cat/cat-segments.md +++ b/_api-reference/cat/cat-segments.md @@ -39,7 +39,7 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | -| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, `p` | N/A | +| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, and `p`. | N/A | | `cluster_manager_timeout` | String | The amount of time allowed to establish a connection to the cluster manager node. | N/A | | `format` | String | A short version of the `Accept` header, such as `json` or `yaml`. | N/A | | `h` | List | A comma-separated list of column names to display. | N/A | diff --git a/_api-reference/cat/cat-shards.md b/_api-reference/cat/cat-shards.md index c721e89d3c..ebcbcb77ac 100644 --- a/_api-reference/cat/cat-shards.md +++ b/_api-reference/cat/cat-shards.md @@ -39,14 +39,14 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | -| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, `p` | N/A | +| `bytes` | String | The units used to display byte values.
Valid values are: `b`, `kb`, `k`, `mb`, `m`, `gb`, `g`, `tb`, `t`, `pb`, and `p`. | N/A | | `cluster_manager_timeout` | String | The amount of time allowed to establish a connection to the cluster manager node. | N/A | | `format` | String | A short version of the `Accept` header, such as `json` or `yaml`. | N/A | | `h` | List | A comma-separated list of column names to display. | N/A | | `help` | Boolean | Returns help information. | `false` | | `local` | Boolean | Returns local information but does not retrieve the state from the cluster manager node. | `false` | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, and `d`. | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-snapshots.md b/_api-reference/cat/cat-snapshots.md index dc2ffaab62..d152b39523 100644 --- a/_api-reference/cat/cat-snapshots.md +++ b/_api-reference/cat/cat-snapshots.md @@ -35,17 +35,18 @@ include_deprecated: false --> ## Query parameters -The following table lists the available query parameters. All query parameters are optional. +The following table lists the available query parameters. | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | +| `repository` | List or String | **(Required)** A comma-separated list of snapshot repositories used to limit the request. Accepts wildcard expressions. `_all` returns all repositories. If any repository fails during the request, OpenSearch returns an error. | N/A | | `cluster_manager_timeout` | String | The amount of time allowed to establish a connection to the cluster manager node. | N/A | | `format` | String | A short version of the `Accept` header, such as `json` or `yaml`. | N/A | | `h` | List | A comma-separated list of column names to display. | N/A | | `help` | Boolean | Returns help information. | `false` | | `ignore_unavailable` | Boolean | When `true`, the response does not include information from unavailable snapshots. | `false` | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, and `d`. | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cat/cat-tasks.md b/_api-reference/cat/cat-tasks.md index 5cac1c3936..e3c39478ce 100644 --- a/_api-reference/cat/cat-tasks.md +++ b/_api-reference/cat/cat-tasks.md @@ -45,7 +45,7 @@ The following table lists the available query parameters. All query parameters a | `nodes` | List | A comma-separated list of node IDs or names used to limit the returned information. Use `_local` to return information from the node to which you're connecting, specify a specific node from which to get information, or keep the parameter empty to get information from all nodes. | N/A | | `parent_task_id` | String | The parent task identifier, which is used to limit the response. | N/A | | `s` | List | A comma-separated list of column names or column aliases to sort by. | N/A | -| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` | N/A | +| `time` | String | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/).
Valid values are: `nanos`, `micros`, `ms`, `s`, `m`, `h`, and `d`. | N/A | | `v` | Boolean | Enables verbose mode, which displays column headers. | `false` | diff --git a/_api-reference/cluster-api/cluster-health.md b/_api-reference/cluster-api/cluster-health.md index 264536aa16..be978efd65 100644 --- a/_api-reference/cluster-api/cluster-health.md +++ b/_api-reference/cluster-api/cluster-health.md @@ -57,15 +57,15 @@ The following table lists the available query parameters. All query parameters a | `awareness_attribute` | String | The name of the awareness attribute for which to return the cluster health status (for example, `zone`). Applicable only if `level` is set to `awareness_attributes`. | N/A | | `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | N/A | | `expand_wildcards` | List or String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with open, closed, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes. | `open` | -| `level` | String | Controls the amount of detail included in the cluster health response.
Valid values are: `awareness_attributes`, `cluster`, `indices`, `shards` | `cluster` | +| `level` | String | Controls the amount of detail included in the cluster health response.
Valid values are: `awareness_attributes`, `cluster`, `indices`, and `shards`. | `cluster` | | `local` | Boolean | Whether to return information from the local node only instead of from the cluster manager node. | `false` | | `timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | N/A | -| `wait_for_active_shards` | Integer or String | Waits until the specified number of shards is active before returning a response. Use `all` for all shards.
Valid values are: `all`, `index-setting` | `0` | +| `wait_for_active_shards` | Integer or String | Waits until the specified number of shards is active before returning a response. Use `all` for all shards.
Valid values are: `all`, and `index-setting`. | `0` | | `wait_for_events` | String | Waits until all currently queued events with the given priority are processed.
Valid values are:
- `immediate`: Highest priority, processed as soon as possible.
- `urgent`: Very high priority, processed after immediate events.
- `high`: High priority, processed after urgent events.
- `normal`: Default priority, processed after high priority events.
- `low`: Low priority, processed after normal events.
- `languid`: Lowest priority, processed after all other events. | N/A | | `wait_for_no_initializing_shards` | Boolean | Whether to wait until there are no initializing shards in the cluster. | `false` | | `wait_for_no_relocating_shards` | Boolean | Whether to wait until there are no relocating shards in the cluster. | `false` | | `wait_for_nodes` | Float or String | Waits until the specified number of nodes (`N`) is available. Accepts `>=N`, `<=N`, `>N`, and ` Valid values are: `green`, `GREEN`, `yellow`, `YELLOW`, `red`, `RED` | N/A | +| `wait_for_status` | String | Waits until the cluster health reaches the specified status or better.
Valid values are: `green`, `GREEN`, `yellow`, `YELLOW`, `red`, and `RED`. | N/A | diff --git a/_api-reference/tasks/list-tasks.md b/_api-reference/tasks/list-tasks.md index 422b0565ed..c2ef9ec952 100644 --- a/_api-reference/tasks/list-tasks.md +++ b/_api-reference/tasks/list-tasks.md @@ -33,7 +33,7 @@ The following table lists the available query parameters. All query parameters a | :--- | :--- | :--- | :--- | | `actions` | List or String | A comma-separated list of actions that should be returned. Keep empty to return all. | N/A | | `detailed` | Boolean | When `true`, the response includes detailed information about shard recoveries. | `false` | -| `group_by` | String | Groups tasks by parent/child relationships or nodes.
Valid values are: `nodes`, `none`, `parents` | `nodes` | +| `group_by` | String | Groups tasks by parent/child relationships or nodes.
Valid values are: `nodes`, `none`, and `parents`. | `nodes` | | `nodes` | List | A comma-separated list of node IDs or names used to limit the returned information. Use `_local` to return information from the node you're connecting to, specify the node name to get information from a specific node, or keep the parameter empty to get information from all nodes. | N/A | | `parent_task_id` | String | Returns tasks with a specified parent task ID (`node_id:task_number`). Keep empty or set to -1 to return all. | N/A | | `timeout` | String | The amount of time to wait for a response. | N/A | From 8aeefa50c82bc6724d3bd4393c9772b83afa91af Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Thu, 3 Apr 2025 15:51:03 -0500 Subject: [PATCH 24/24] Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _api-reference/cluster-api/cluster-stats.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/cluster-api/cluster-stats.md b/_api-reference/cluster-api/cluster-stats.md index 1b3714ab70..b53cca4667 100644 --- a/_api-reference/cluster-api/cluster-stats.md +++ b/_api-reference/cluster-api/cluster-stats.md @@ -40,7 +40,7 @@ The following table lists the available path parameters. All path parameters are | Parameter | Data type | Description | | :--- | :--- | :--- | | `index_metric` | List | A comma-separated list of [index metric groups]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-stats/#index-metric-groups), for example, `docs,store`. | -| `metric` | List | Limit the information returned to the specified metrics. | +| `metric` | List | Limit the information returned to the [specified metrics](#metric-groups). | | `node_id` | List or String | A comma-separated list of node IDs used to filter results. Supports [node filters]({{site.url}}{{site.baseurl}}/api-reference/nodes-apis/index/#node-filters). |