From 2fa3baa2787d22598ef1155a2d0ef9753ec65ac9 Mon Sep 17 00:00:00 2001 From: Archer Date: Wed, 26 Feb 2025 11:15:02 -0600 Subject: [PATCH 1/6] Add additional technical writer feedback to Cluster APIs Signed-off-by: Archer --- spec/namespaces/cluster.yaml | 32 ++++++++++++++++++------- spec/schemas/_common.yaml | 7 ++++++ spec/schemas/cluster.reroute.yaml | 39 ++++++++++++++++++++++--------- 3 files changed, 59 insertions(+), 19 deletions(-) diff --git a/spec/namespaces/cluster.yaml b/spec/namespaces/cluster.yaml index 6bf615b7e..252a8a3d3 100644 --- a/spec/namespaces/cluster.yaml +++ b/spec/namespaces/cluster.yaml @@ -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 @@ -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. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' x-version-added: '2.0' @@ -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. in: query schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -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. 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 @@ -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. in: query schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -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. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' x-version-added: '2.0' @@ -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 @@ -1069,6 +1077,7 @@ components: cluster.health::query.timeout: in: query name: timeout + description: schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' style: form @@ -1076,6 +1085,7 @@ components: 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: @@ -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 @@ -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. in: query schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -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. in: query schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -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. in: query schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' @@ -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. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' x-version-added: '2.0' @@ -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 @@ -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' diff --git a/spec/schemas/_common.yaml b/spec/schemas/_common.yaml index de722eebe..c11d68dc6 100644 --- a/spec/schemas/_common.yaml +++ b/spec/schemas/_common.yaml @@ -1067,6 +1067,13 @@ components: - low - normal - urgent + enumDescriptions: + immediate: The highest priority event, processed as soon as possible. + urgent: A very high priority event, processed after immediate events. + high: A high priority event, processed after urgent events. + normal: The default priority for events, processed after high priority events. + low: A low priority event, processed after normal events. + languid: The lowest priority event, processed after all other events. DataStreamName: type: string CompletionStats: diff --git a/spec/schemas/cluster.reroute.yaml b/spec/schemas/cluster.reroute.yaml index 98de24c49..fe266bc9e 100644 --- a/spec/schemas/cluster.reroute.yaml +++ b/spec/schemas/cluster.reroute.yaml @@ -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: From 8a81ab7f9fd1fdfc80dee1d048fb3550ad0c4562 Mon Sep 17 00:00:00 2001 From: Archer Date: Wed, 26 Feb 2025 11:21:01 -0600 Subject: [PATCH 2/6] Fix missing description Signed-off-by: Archer --- spec/namespaces/cluster.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/namespaces/cluster.yaml b/spec/namespaces/cluster.yaml index 252a8a3d3..a3a45fc17 100644 --- a/spec/namespaces/cluster.yaml +++ b/spec/namespaces/cluster.yaml @@ -1077,7 +1077,7 @@ components: cluster.health::query.timeout: in: query name: timeout - description: + 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. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' style: form From 2bcb5999515f5569aa622e2c816ee36d2c653835 Mon Sep 17 00:00:00 2001 From: Archer Date: Wed, 26 Feb 2025 11:26:54 -0600 Subject: [PATCH 3/6] Fix Enum descriptions in common.yaml Signed-off-by: Archer --- spec/schemas/_common.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/schemas/_common.yaml b/spec/schemas/_common.yaml index c11d68dc6..3064475cf 100644 --- a/spec/schemas/_common.yaml +++ b/spec/schemas/_common.yaml @@ -1068,12 +1068,12 @@ components: - normal - urgent enumDescriptions: - immediate: The highest priority event, processed as soon as possible. - urgent: A very high priority event, processed after immediate events. - high: A high priority event, processed after urgent events. - normal: The default priority for events, processed after high priority events. - low: A low priority event, processed after normal events. - languid: The lowest priority event, processed after all other events. + immediate: The highest priority event, processed as soon as possible. + urgent: A very high priority event, processed after immediate events. + high: A high priority event, processed after urgent events. + normal: The default priority for events, processed after high priority events. + low: A low priority event, processed after normal events. + languid: The lowest priority event, processed after all other events. DataStreamName: type: string CompletionStats: From b7cc5c21d2872c57e73c8d1b817d922de3509d88 Mon Sep 17 00:00:00 2001 From: Archer Date: Wed, 26 Feb 2025 11:31:40 -0600 Subject: [PATCH 4/6] Fix breaking change Signed-off-by: Archer --- spec/schemas/cluster.reroute.yaml | 48 +++++++++++++------------------ 1 file changed, 20 insertions(+), 28 deletions(-) diff --git a/spec/schemas/cluster.reroute.yaml b/spec/schemas/cluster.reroute.yaml index fe266bc9e..5ee38ee85 100644 --- a/spec/schemas/cluster.reroute.yaml +++ b/spec/schemas/cluster.reroute.yaml @@ -121,34 +121,26 @@ components: - node - shard Metric: - 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. + type: string + enum: + - _all + - blocks + - cluster_manager_node + - master_node + - metadata + - nodes + - routing_nodes + - routing_table + - version + enumDescriptions: + _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: An 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. + version: Returns the cluster state version. RerouteExplanation: type: object properties: From 71cd5f9cbec0402865a91740347c719220f5c345 Mon Sep 17 00:00:00 2001 From: Archer Date: Wed, 26 Feb 2025 11:59:38 -0600 Subject: [PATCH 5/6] Fix Spec tests Signed-off-by: Archer --- spec/schemas/_common.yaml | 34 ++++++++++++---------- spec/schemas/cluster.reroute.yaml | 48 ++++++++++++++++++------------- 2 files changed, 47 insertions(+), 35 deletions(-) diff --git a/spec/schemas/_common.yaml b/spec/schemas/_common.yaml index 3064475cf..eb11b56d3 100644 --- a/spec/schemas/_common.yaml +++ b/spec/schemas/_common.yaml @@ -1059,21 +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 - enumDescriptions: - immediate: The highest priority event, processed as soon as possible. - urgent: A very high priority event, processed after immediate events. - high: A high priority event, processed after urgent events. - normal: The default priority for events, processed after high priority events. - low: A low priority event, processed after normal events. - languid: The lowest priority event, processed after all other events. + 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: diff --git a/spec/schemas/cluster.reroute.yaml b/spec/schemas/cluster.reroute.yaml index 5ee38ee85..fe266bc9e 100644 --- a/spec/schemas/cluster.reroute.yaml +++ b/spec/schemas/cluster.reroute.yaml @@ -121,26 +121,34 @@ components: - node - shard Metric: - type: string - enum: - - _all - - blocks - - cluster_manager_node - - master_node - - metadata - - nodes - - routing_nodes - - routing_table - - version - enumDescriptions: - _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: An 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. - version: Returns the cluster state 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: From 1b9f37c4cf3922b69937adc72042c1069d1bf230 Mon Sep 17 00:00:00 2001 From: Archer Date: Wed, 26 Feb 2025 12:19:25 -0600 Subject: [PATCH 6/6] See if changing link location fixes style error Signed-off-by: Archer --- spec/namespaces/cluster.yaml | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/spec/namespaces/cluster.yaml b/spec/namespaces/cluster.yaml index a3a45fc17..8632236e6 100644 --- a/spec/namespaces/cluster.yaml +++ b/spec/namespaces/cluster.yaml @@ -852,7 +852,7 @@ components: cluster.delete_component_template::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. + 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' @@ -897,7 +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. + 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' @@ -933,7 +933,7 @@ 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. + 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' @@ -978,7 +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. + 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' @@ -1039,7 +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. + 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' @@ -1077,7 +1077,7 @@ components: cluster.health::query.timeout: in: query name: 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. + 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' style: form @@ -1128,7 +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. + 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' @@ -1196,7 +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. + 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' @@ -1241,7 +1241,7 @@ components: 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. + 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' @@ -1280,7 +1280,7 @@ components: 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. + 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' @@ -1357,7 +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. + 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'