Skip to content

Commit

Permalink
Add additional technical writer feedback to Cluster APIs
Browse files Browse the repository at this point in the history 
Signed-off-by: Archer <naarcha@amazon.com>
  • Loading branch information
@Naarcha-AWS
Naarcha-AWS committed Feb 26, 2025
1 parent 5ed668d commit 2fa3baa
Show file tree
Hide file tree
Showing 3 changed files with 59 additions and 19 deletions.
32 changes: 24 additions & 8 deletions spec/namespaces/cluster.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -834,7 +834,7 @@ components:
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 @@ components:
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]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units) to wait for a response from the cluster manager node.

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 'of time'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'of time'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 855, "column": 31}}}, "severity": "ERROR"}
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
x-version-added: '2.0'
Expand Down Expand Up @@ -897,6 +897,7 @@ components:
style: simple
cluster.exists_component_template::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: The amount of [time]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units) to wait for a response from the cluster manager node.

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 'of time'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'of time'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 900, "column": 31}}}, "severity": "ERROR"}
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
Expand Down Expand Up @@ -932,14 +933,18 @@ components:
style: simple
cluster.get_component_template::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: The amount of [time]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units) to wait for a response from the cluster manager node.

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 'of time'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'of time'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 936, "column": 31}}}, "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 @@ components:
required: true
cluster.get_settings::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: The amount of [time]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units) to wait for a response from the cluster manager node.

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 'of time'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'of time'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 981, "column": 31}}}, "severity": "ERROR"}
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
Expand Down Expand Up @@ -1033,6 +1039,7 @@ components:
cluster.health::query.cluster_manager_timeout:
name: cluster_manager_timeout
in: query
description: The amount of [time]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units) to wait for a response from the cluster manager node.

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 'of time'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'of time'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 1042, "column": 31}}}, "severity": "ERROR"}
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
x-version-added: '2.0'
Expand All @@ -1041,6 +1048,7 @@ components:
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 @@ components:
cluster.health::query.timeout:
in: query
name: timeout
description:

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

View workflow job for this annotation

GitHub Actions / lint 

Empty mapping values are forbidden
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 @@ components:
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 @@ components:
style: form
cluster.pending_tasks::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: The amount of [time]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units) to wait for a response from the cluster manager node.

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 'of time'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'of time'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 1131, "column": 31}}}, "severity": "ERROR"}
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
Expand Down Expand Up @@ -1184,6 +1196,7 @@ components:
style: simple
cluster.put_component_template::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: The amount of [time]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units) to wait for a response from the cluster manager node.

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 'of time'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'of time'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 1199, "column": 31}}}, "severity": "ERROR"}
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
Expand Down Expand Up @@ -1221,13 +1234,14 @@ components:
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]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units) to wait for a response from the cluster manager node.

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 'of time'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'of time'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 1244, "column": 31}}}, "severity": "ERROR"}
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
Expand Down Expand Up @@ -1258,14 +1272,15 @@ components:
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]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units) to wait for a response from the cluster manager node.

Check failure on line 1283 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 'of time'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'of time'.", "location": {"path": "spec/namespaces/cluster.yaml", "range": {"start": {"line": 1283, "column": 31}}}, "severity": "ERROR"}
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
x-version-added: '2.0'
Expand All @@ -1279,7 +1294,7 @@ components:
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 @@ components:
style: form
cluster.state::query.cluster_manager_timeout:
name: cluster_manager_timeout
description: The amount of [time]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units) to wait for a response from the cluster manager node.
in: query
schema:
$ref: '../schemas/_common.yaml#/components/schemas/Duration'
Expand Down
7 changes: 7 additions & 0 deletions spec/schemas/_common.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1067,6 +1067,13 @@ components:
- low
- normal
- urgent
enumDescriptions:
immediate: The highest priority event, processed as soon as possible.

Check failure on line 1071 in spec/schemas/_common.yaml

View workflow job for this annotation

GitHub Actions / lint 

Expected indentation of 8 spaces but found 7 spaces
urgent: A very high priority event, processed after immediate events.

Check failure on line 1072 in spec/schemas/_common.yaml

View workflow job for this annotation

GitHub Actions / lint 

Expected indentation of 8 spaces but found 7 spaces
high: A high priority event, processed after urgent events.

Check failure on line 1073 in spec/schemas/_common.yaml

View workflow job for this annotation

GitHub Actions / lint 

Expected indentation of 8 spaces but found 7 spaces
normal: The default priority for events, processed after high priority events.

Check failure on line 1074 in spec/schemas/_common.yaml

View workflow job for this annotation

GitHub Actions / lint 

Expected indentation of 8 spaces but found 7 spaces
low: A low priority event, processed after normal events.

Check failure on line 1075 in spec/schemas/_common.yaml

View workflow job for this annotation

GitHub Actions / lint 

Expected indentation of 8 spaces but found 7 spaces
languid: The lowest priority event, processed after all other events.

Check failure on line 1076 in spec/schemas/_common.yaml

View workflow job for this annotation

GitHub Actions / lint 

Expected indentation of 8 spaces but found 7 spaces
DataStreamName:
type: string
CompletionStats:
Expand Down
39 changes: 28 additions & 11 deletions spec/schemas/cluster.reroute.yaml
View file
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

0 comments on commit 2fa3baa

Please sign in to comment.