Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add additional technical writer feedback to Cluster APIs #824

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Add additional technical writer feedback to Cluster APIs #824

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2fa3baa
Add additional technical writer feedback to Cluster APIs
Naarcha-AWS Feb 26, 2025
8a81ab7
Fix missing description
Naarcha-AWS Feb 26, 2025
2bcb599
Fix Enum descriptions in common.yaml
Naarcha-AWS Feb 26, 2025
b7cc5c2
Fix breaking change
Naarcha-AWS Feb 26, 2025
71cd5f9
Fix Spec tests
Naarcha-AWS Feb 26, 2025
1b9f37c
See if changing link location fixes style error
Naarcha-AWS Feb 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 24 additions & 8 deletions spec/namespaces/cluster.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -834,7 +834,7 @@
cluster.allocation_explain::query.include_yes_decisions:
in: query
name: include_yes_decisions
description: When `true`, returns any `YES` decisions in the allocation explanation.
description: 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.
schema:
type: boolean
default: false
Expand All @@ -852,7 +852,7 @@
cluster.delete_component_template::query.cluster_manager_timeout:
name: cluster_manager_timeout
in: query
description: Operation timeout for connection to cluster-manager node.
description: 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).

Check failure on line 855 in spec/namespaces/cluster.yaml

View workflow job for this annotation

GitHub Actions / check 

[vale] reported by reviewdog 🐶
[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 855, "column": 142}}}, "severity": "ERROR"}
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
x-version-added: '2.0'
Expand Down Expand Up @@ -897,6 +897,7 @@
style: simple
cluster.exists_component_template::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: 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).

Check failure on line 900 in spec/namespaces/cluster.yaml

View workflow job for this annotation

GitHub Actions / check 

[vale] reported by reviewdog 🐶
[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 900, "column": 142}}}, "severity": "ERROR"}
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
Expand Down Expand Up @@ -932,14 +933,18 @@
style: simple
cluster.get_component_template::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: 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).

Check failure on line 936 in spec/namespaces/cluster.yaml

View workflow job for this annotation

GitHub Actions / check 

[vale] reported by reviewdog 🐶
[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 936, "column": 142}}}, "severity": "ERROR"}
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
default: 30s
x-version-added: '2.0'
cluster.get_component_template::query.flat_settings:
in: query
name: flat_settings
description: If `true`, returns settings in flat format.
description: |-
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"`.
schema:
type: boolean
default: false
Expand Down Expand Up @@ -973,6 +978,7 @@
required: true
cluster.get_settings::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: 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).

Check failure on line 981 in spec/namespaces/cluster.yaml

View workflow job for this annotation

GitHub Actions / check 

[vale] reported by reviewdog 🐶
[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 981, "column": 142}}}, "severity": "ERROR"}
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
Expand Down Expand Up @@ -1033,6 +1039,7 @@
cluster.health::query.cluster_manager_timeout:
name: cluster_manager_timeout
in: query
description: 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).

Check failure on line 1042 in spec/namespaces/cluster.yaml

View workflow job for this annotation

GitHub Actions / check 

[vale] reported by reviewdog 🐶
[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 1042, "column": 142}}}, "severity": "ERROR"}
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
x-version-added: '2.0'
Expand All @@ -1041,6 +1048,7 @@
name: expand_wildcards
schema:
$ref: '../schemas/_common.yaml#/components/schemas/ExpandWildcards'
default: open
style: form
cluster.health::query.level:
in: query
Expand Down Expand Up @@ -1069,13 +1077,15 @@
cluster.health::query.timeout:
in: query
name: timeout
description: 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).

Check failure on line 1080 in spec/namespaces/cluster.yaml

View workflow job for this annotation

GitHub Actions / check 

[vale] reported by reviewdog 🐶
[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 1080, "column": 142}}}, "severity": "ERROR"}
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
style: form
cluster.health::query.wait_for_active_shards:
in: query
name: wait_for_active_shards
schema:
default: 0
$ref: '../schemas/_common.yaml#/components/schemas/WaitForActiveShards'
style: form
cluster.health::query.wait_for_events:
Expand All @@ -1098,6 +1108,7 @@
description: Whether to wait until there are no relocating shards in the cluster.
schema:
type: boolean
default: false
style: form
cluster.health::query.wait_for_nodes:
in: query
Expand All @@ -1117,6 +1128,7 @@
style: form
cluster.pending_tasks::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: 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).

Check failure on line 1131 in spec/namespaces/cluster.yaml

View workflow job for this annotation

GitHub Actions / check 

[vale] reported by reviewdog 🐶
[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 1131, "column": 142}}}, "severity": "ERROR"}
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
Expand Down Expand Up @@ -1184,6 +1196,7 @@
style: simple
cluster.put_component_template::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: 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).

Check failure on line 1199 in spec/namespaces/cluster.yaml

View workflow job for this annotation

GitHub Actions / check 

[vale] reported by reviewdog 🐶
[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 1199, "column": 142}}}, "severity": "ERROR"}
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
Expand Down Expand Up @@ -1221,13 +1234,14 @@
cluster.put_decommission_awareness::path.awareness_attribute_value:
name: awareness_attribute_value
in: path
description: The value of the awareness attribute.
description: 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.
schema:
type: string
description: The value of the awareness attribute.
description: 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.
required: true
cluster.put_settings::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: 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).

Check failure on line 1244 in spec/namespaces/cluster.yaml

View workflow job for this annotation

GitHub Actions / check 

[vale] reported by reviewdog 🐶
[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'see Common'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 1244, "column": 142}}}, "severity": "ERROR"}
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
Expand Down Expand Up @@ -1258,14 +1272,15 @@
cluster.put_weighted_routing::path.attribute:
name: attribute
in: path
description: The name of the awareness attribute.
description: The name of awareness attribute, usually `zone`.
schema:
type: string
description: The name of the awareness attribute.
description: The name of awareness attribute, usually `zone`.
required: true
cluster.reroute::query.cluster_manager_timeout:
name: cluster_manager_timeout
in: query
description: 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).
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
x-version-added: '2.0'
Expand All @@ -1279,7 +1294,7 @@
cluster.reroute::query.explain:
in: query
name: explain
description: When `true`, the response contains an explanation of why certain commands can or cannot be executed.
description: When `true`, the response contains an explanation of why reroute certain commands can or cannot be executed.
schema:
type: boolean
style: form
Expand Down Expand Up @@ -1342,6 +1357,7 @@
style: form
cluster.state::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: 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).
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
Expand Down
27 changes: 19 additions & 8 deletions spec/schemas/_common.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1059,14 +1059,25 @@ components:
- shards
WaitForEvents:
description: Waits until all currently queued events with the given priority are processed.
type: string
enum:
- high
- immediate
- languid
- low
- normal
- urgent
oneOf:
- type: string
const: immediate
description: Highest priority, processed as soon as possible.
- type: string
const: urgent
description: Very high priority, processed after immediate events.
- type: string
const: high
description: High priority, processed after urgent events.
- type: string
const: normal
description: Default priority, processed after high priority events.
- type: string
const: low
description: Low priority, processed after normal events.
- type: string
const: languid
description: Lowest priority, processed after all other events.
DataStreamName:
type: string
CompletionStats:
Expand Down
39 changes: 28 additions & 11 deletions spec/schemas/cluster.reroute.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,17 +121,34 @@ components:
- node
- shard
Metric:
type: string
enum:
- _all
- blocks
- cluster_manager_node
- master_node
- metadata
- nodes
- routing_nodes
- routing_table
- version
oneOf:
- type: string
const: _all
description: Returns all available metrics.
- type: string
const: blocks
description: Returns information about cluster-level blocks.
- type: string
const: cluster_manager_node
description: Returns information about the current cluster manager node.
- type: string
const: master_node
description: The alias for `cluster_manager_node`. Deprecated, but maintained for backwards compatibility.
- type: string
const: metadata
description: Returns the cluster state metadata.
- type: string
const: nodes
description: Returns information about nodes in the cluster.
- type: string
const: routing_nodes
description: Returns the node-level shard allocations.
- type: string
const: routing_table
description: Returns index-level shard allocations.
- type: string
const: version
description: Returns the cluster state version.
RerouteExplanation:
type: object
properties:
Expand Down
Loading