From 1dac3c987f7eb63dad985287a9d885f09ca67bed Mon Sep 17 00:00:00 2001 From: Thomas Farr Date: Sat, 28 Dec 2024 01:22:55 +1300 Subject: [PATCH] Fix cluster schemas (#754) * Fix cluster schemas Signed-off-by: Thomas Farr * changelog Signed-off-by: Thomas Farr * Fix vale Signed-off-by: Thomas Farr --------- Signed-off-by: Thomas Farr --- CHANGELOG.md | 1 + spec/namespaces/cluster.yaml | 76 +++++--- spec/schemas/cluster.allocation_explain.yaml | 12 +- spec/schemas/cluster.health.yaml | 81 +++++--- spec/schemas/cluster.pending_tasks.yaml | 3 +- spec/schemas/cluster.remote_info.yaml | 12 +- spec/schemas/cluster.reroute.yaml | 49 ++++- spec/schemas/cluster.stats.yaml | 184 ++++++++++--------- spec/schemas/nodes._common.yaml | 1 + 9 files changed, 269 insertions(+), 150 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 75190ad26..52954a1d2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -82,6 +82,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - Fixed request body for `/_search/scroll/{scroll_id}` ([#732](https://github.com/opensearch-project/opensearch-api-specification/pull/732)) - Fixed type in `_msearch/template` ([#735](https://github.com/opensearch-project/opensearch-api-specification/pull/735)) - Fixed indices API schemas ([#750](https://github.com/opensearch-project/opensearch-api-specification/pull/750)) +- Fixed cluster API schemas ([#754](https://github.com/opensearch-project/opensearch-api-specification/pull/754)) ### Changed - Changed `tasks._common:TaskInfo` and `tasks._common:TaskGroup` to be composed of a `tasks._common:TaskInfoBase` ([#683](https://github.com/opensearch-project/opensearch-api-specification/pull/683)) diff --git a/spec/namespaces/cluster.yaml b/spec/namespaces/cluster.yaml index 3ae08403a..566cf3176 100644 --- a/spec/namespaces/cluster.yaml +++ b/spec/namespaces/cluster.yaml @@ -401,6 +401,7 @@ paths: url: https://opensearch.org/docs/latest parameters: - $ref: '#/components/parameters/cluster.get_component_template::query.cluster_manager_timeout' + - $ref: '#/components/parameters/cluster.get_component_template::query.flat_settings' - $ref: '#/components/parameters/cluster.get_component_template::query.local' - $ref: '#/components/parameters/cluster.get_component_template::query.master_timeout' responses: @@ -417,6 +418,7 @@ paths: parameters: - $ref: '#/components/parameters/cluster.get_component_template::path.name' - $ref: '#/components/parameters/cluster.get_component_template::query.cluster_manager_timeout' + - $ref: '#/components/parameters/cluster.get_component_template::query.flat_settings' - $ref: '#/components/parameters/cluster.get_component_template::query.local' - $ref: '#/components/parameters/cluster.get_component_template::query.master_timeout' responses: @@ -528,7 +530,8 @@ components: type: boolean shard: description: Specifies the ID of the shard that you would like an explanation for. - type: number + type: integer + format: int32 description: The index, shard, and primary flag to explain. Empty means 'explain the first unassigned shard' cluster.put_component_template: content: @@ -637,7 +640,8 @@ components: remaining_delay_in_millis: $ref: '../schemas/_common.yaml#/components/schemas/DurationValueUnitMillis' shard: - type: number + type: integer + format: int32 unassigned_info: $ref: '../schemas/cluster.allocation_explain.yaml#/components/schemas/UnassignedInformation' note: @@ -772,32 +776,54 @@ components: content: application/json: schema: - type: object - properties: - acknowledged: - type: boolean - explanations: - type: array - items: - $ref: '../schemas/cluster.reroute.yaml#/components/schemas/RerouteExplanation' - state: - description: |- - There aren't any guarantees on the output/structure of the raw cluster state. - Here you will find the internal representation of the cluster, which can - differ from the external representation. - type: object - required: - - acknowledged + allOf: + - $ref: '../schemas/_common.yaml#/components/schemas/AcknowledgedResponseBase' + - type: object + properties: + explanations: + type: array + items: + $ref: '../schemas/cluster.reroute.yaml#/components/schemas/RerouteExplanation' + state: + description: |- + There aren't any guarantees on the output/structure of the raw cluster state. + Here you will find the internal representation of the cluster, which can + differ from the external representation. cluster.state@200: content: application/json: - schema: - type: object + schema: {} cluster.stats@200: content: application/json: schema: - $ref: '../schemas/cluster.stats.yaml#/components/schemas/StatsResponseBase' + allOf: + - $ref: '../schemas/nodes._common.yaml#/components/schemas/NodesResponseBase' + - type: object + properties: + cluster_name: + description: Name of the cluster, based on the Cluster name setting setting. + $ref: '../schemas/_common.yaml#/components/schemas/Name' + cluster_uuid: + description: Unique identifier for the cluster. + $ref: '../schemas/_common.yaml#/components/schemas/Uuid' + indices: + description: Contains statistics about indexes with shards assigned to selected nodes. + $ref: '../schemas/cluster.stats.yaml#/components/schemas/ClusterIndices' + nodes: + description: Contains statistics about nodes selected by the request's node filters. + $ref: '../schemas/cluster.stats.yaml#/components/schemas/ClusterNodes' + status: + description: Health status of the cluster, based on the state of its primary and replica shards. + $ref: '../schemas/_common.yaml#/components/schemas/HealthStatus' + timestamp: + description: Unix timestamp, in milliseconds, for the last time the cluster statistics were refreshed. + $ref: '../schemas/_common.yaml#/components/schemas/EpochTimeUnitMillis' + required: + - cluster_name + - cluster_uuid + - status + - timestamp parameters: cluster.allocation_explain::query.include_disk_info: in: query @@ -924,6 +950,14 @@ components: schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' 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. + schema: + type: boolean + default: false + style: form cluster.get_component_template::query.local: in: query name: local diff --git a/spec/schemas/cluster.allocation_explain.yaml b/spec/schemas/cluster.allocation_explain.yaml index f90f94d7d..defad809b 100644 --- a/spec/schemas/cluster.allocation_explain.yaml +++ b/spec/schemas/cluster.allocation_explain.yaml @@ -116,7 +116,8 @@ components: path: type: string total: - type: number + type: integer + format: int64 shards: type: array items: @@ -140,7 +141,8 @@ components: transport_address: $ref: '_common.yaml#/components/schemas/TransportAddress' weight_ranking: - type: number + type: integer + format: int32 required: - attributes - id @@ -169,7 +171,8 @@ components: transport_address: $ref: '_common.yaml#/components/schemas/TransportAddress' weight_ranking: - type: number + type: integer + format: int32 required: - deciders - node_attributes @@ -211,7 +214,8 @@ components: details: type: string failed_allocation_attempts: - type: number + type: integer + format: int32 delayed: type: boolean allocation_status: diff --git a/spec/schemas/cluster.health.yaml b/spec/schemas/cluster.health.yaml index c62ccbb37..1776ac780 100644 --- a/spec/schemas/cluster.health.yaml +++ b/spec/schemas/cluster.health.yaml @@ -11,10 +11,12 @@ components: properties: active_primary_shards: description: The number of active primary shards. - type: number + type: integer + format: int32 active_shards: description: The total number of active primary and replica shards. - type: number + type: integer + format: int32 active_shards_percent: $ref: '_common.yaml#/components/schemas/PercentageString' active_shards_percent_as_number: @@ -29,7 +31,8 @@ components: $ref: '_common.yaml#/components/schemas/Name' delayed_unassigned_shards: description: The number of shards whose allocation has been delayed by the timeout settings. - type: number + type: integer + format: int32 discovered_master: description: True if the cluster-manager node has been discovered. type: boolean @@ -44,22 +47,28 @@ components: $ref: '#/components/schemas/IndexHealthStats' initializing_shards: description: The number of shards that are under initialization. - type: number + type: integer + format: int32 number_of_data_nodes: description: The number of nodes that are dedicated data nodes. - type: number + type: integer + format: int32 number_of_in_flight_fetch: description: The number of unfinished fetches. - type: number + type: integer + format: int32 number_of_nodes: description: The number of nodes within the cluster. - type: number + type: integer + format: int32 number_of_pending_tasks: description: The number of cluster-level changes that have not yet been executed. - type: number + type: integer + format: int32 relocating_shards: description: The number of shards that are under relocation. - type: number + type: integer + format: int32 status: $ref: '_common.yaml#/components/schemas/HealthStatus' task_max_waiting_in_queue: @@ -71,7 +80,8 @@ components: type: boolean unassigned_shards: description: The number of shards that are not allocated. - type: number + type: integer + format: int32 required: - active_primary_shards - active_shards @@ -92,17 +102,23 @@ components: type: object properties: active_primary_shards: - type: number + type: integer + format: int32 active_shards: - type: number + type: integer + format: int32 initializing_shards: - type: number + type: integer + format: int32 number_of_replicas: - type: number + type: integer + format: int32 number_of_shards: - type: number + type: integer + format: int32 relocating_shards: - type: number + type: integer + format: int32 shards: type: object additionalProperties: @@ -110,7 +126,8 @@ components: status: $ref: '_common.yaml#/components/schemas/HealthStatus' unassigned_shards: - type: number + type: integer + format: int32 required: - active_primary_shards - active_shards @@ -132,32 +149,42 @@ components: x-version-added: '2.5' properties: active_shards: - type: number + type: integer + format: int32 initializing_shards: - type: number + type: integer + format: int32 relocating_shards: - type: number + type: integer + format: int32 unassigned_shards: - type: number + type: integer + format: int32 data_nodes: - type: number + type: integer + format: int32 weight: - type: number + type: integer + format: int32 ShardHealthStats: type: object properties: active_shards: - type: number + type: integer + format: int32 initializing_shards: - type: number + type: integer + format: int32 primary_active: type: boolean relocating_shards: - type: number + type: integer + format: int32 status: $ref: '_common.yaml#/components/schemas/HealthStatus' unassigned_shards: - type: number + type: integer + format: int32 required: - active_shards - initializing_shards diff --git a/spec/schemas/cluster.pending_tasks.yaml b/spec/schemas/cluster.pending_tasks.yaml index efe552281..de5d9dc8f 100644 --- a/spec/schemas/cluster.pending_tasks.yaml +++ b/spec/schemas/cluster.pending_tasks.yaml @@ -14,7 +14,8 @@ components: type: boolean insert_order: description: The number that represents when the task has been inserted into the task queue. - type: number + type: integer + format: int32 priority: description: |- The priority of the pending task. diff --git a/spec/schemas/cluster.remote_info.yaml b/spec/schemas/cluster.remote_info.yaml index a92160bc8..82b8fac62 100644 --- a/spec/schemas/cluster.remote_info.yaml +++ b/spec/schemas/cluster.remote_info.yaml @@ -23,9 +23,11 @@ components: connected: type: boolean max_connections_per_cluster: - type: number + type: integer + format: int32 num_nodes_connected: - type: number + type: integer + format: int64 initial_connect_timeout: $ref: '_common.yaml#/components/schemas/Duration' skip_unavailable: @@ -60,9 +62,11 @@ components: server_name: type: string num_proxy_sockets_connected: - type: number + type: integer + format: int32 max_proxy_socket_connections: - type: number + type: integer + format: int32 required: - connected - initial_connect_timeout diff --git a/spec/schemas/cluster.reroute.yaml b/spec/schemas/cluster.reroute.yaml index 55ac62278..98de24c49 100644 --- a/spec/schemas/cluster.reroute.yaml +++ b/spec/schemas/cluster.reroute.yaml @@ -10,14 +10,48 @@ components: type: object properties: cancel: + description: |- + Cancel allocation of a shard (or recovery). Accepts `index` and `shard` for index + name and shard number, and `node` for the node to cancel the shard allocation + on. This can be used to force resynchronization of existing replicas from the + primary shard by cancelling them and allowing them to be reinitialized + through the standard recovery process. By default only replica shard + allocations can be cancelled. If it is necessary to cancel the allocation of + a primary shard then the `allow_primary` flag must also be included in the + request. $ref: '#/components/schemas/CommandCancelAction' move: + description: |- + Move a started shard from one node to another node. Accepts `index` and `shard` + for index name and shard number, `from_node` for the node to move the shard + from, and `to_node` for the node to move the shard to. $ref: '#/components/schemas/CommandMoveAction' allocate_replica: + description: |- + Allocate an unassigned replica shard to a node. Accepts `index` and `shard` for + index name and shard number, and `node` to allocate the shard to. Takes + allocation deciders into account. $ref: '#/components/schemas/CommandAllocateReplicaAction' allocate_stale_primary: + description: |- + Allocate a primary shard to a node that holds a stale copy. Accepts `index` + and `shard` for index name and shard number, and `node` to allocate the shard to. + Using this command may lead to data loss for the provided shard id. If a node + which has the good copy of the data rejoins the cluster later on, that data + will be deleted or overwritten with the data of the stale copy that was + forcefully allocated with this command. To ensure that these implications are + well-understood, this command requires the flag `accept_data_loss` to be + explicitly set to true. $ref: '#/components/schemas/CommandAllocatePrimaryAction' allocate_empty_primary: + description: |- + Allocate an empty primary shard to a node. Accepts `index` and `shard` for + index name and shard number, and `node` to allocate the shard to. Using this + command leads to a complete loss of all data that was indexed into this + shard, if it was previously started. If a node which has a copy of the data + rejoins the cluster later on, that data will be deleted. To ensure that these + implications are well-understood, this command requires the flag + `accept_data_loss` to be explicitly set to true. $ref: '#/components/schemas/CommandAllocatePrimaryAction' CommandCancelAction: type: object @@ -25,7 +59,8 @@ components: index: $ref: '_common.yaml#/components/schemas/IndexName' shard: - type: number + type: integer + format: int32 node: type: string allow_primary: @@ -40,7 +75,8 @@ components: index: $ref: '_common.yaml#/components/schemas/IndexName' shard: - type: number + type: integer + format: int32 from_node: description: The node to move the shard from type: string @@ -58,7 +94,8 @@ components: index: $ref: '_common.yaml#/components/schemas/IndexName' shard: - type: number + type: integer + format: int32 node: type: string required: @@ -71,7 +108,8 @@ components: index: $ref: '_common.yaml#/components/schemas/IndexName' shard: - type: number + type: integer + format: int32 node: type: string accept_data_loss: @@ -132,7 +170,8 @@ components: node: $ref: '_common.yaml#/components/schemas/NodeName' shard: - type: number + type: integer + format: int32 from_node: $ref: '_common.yaml#/components/schemas/NodeName' to_node: diff --git a/spec/schemas/cluster.stats.yaml b/spec/schemas/cluster.stats.yaml index 70cab97e5..669dc85d6 100644 --- a/spec/schemas/cluster.stats.yaml +++ b/spec/schemas/cluster.stats.yaml @@ -6,29 +6,6 @@ info: paths: {} components: schemas: - StatsResponseBase: - allOf: - - $ref: 'nodes._common.yaml#/components/schemas/NodesResponseBase' - - type: object - properties: - cluster_name: - $ref: '_common.yaml#/components/schemas/Name' - cluster_uuid: - $ref: '_common.yaml#/components/schemas/Uuid' - indices: - $ref: '#/components/schemas/ClusterIndices' - nodes: - $ref: '#/components/schemas/ClusterNodes' - status: - $ref: '_common.yaml#/components/schemas/HealthStatus' - timestamp: - description: Unix timestamp, in milliseconds, for the last time the cluster statistics were refreshed. - type: number - required: - - cluster_name - - cluster_uuid - - status - - timestamp ClusterIndices: type: object properties: @@ -38,7 +15,8 @@ components: $ref: '_common.yaml#/components/schemas/CompletionStats' count: description: Total number of indexes with shards assigned to selected nodes. - type: number + type: integer + format: int64 docs: $ref: '_common.yaml#/components/schemas/DocStats' fielddata: @@ -117,22 +95,12 @@ components: $ref: '_common.yaml#/components/schemas/Name' count: description: The number of occurrences of the field type in selected nodes. - type: number + type: integer + format: int32 index_count: description: The number of indexes containing the field type in selected nodes. - type: number - indexed_vector_count: - description: For `dense_vector` field types, number of indexed vector types in selected nodes. - type: number - indexed_vector_dim_max: - description: For `dense_vector` field types, the maximum dimension of all indexed vector types in selected nodes. - type: number - indexed_vector_dim_min: - description: For `dense_vector` field types, the minimum dimension of all indexed vector types in selected nodes. - type: number - script_count: - description: The number of fields that declare a script. - type: number + type: integer + format: int32 required: - count - index_count @@ -144,21 +112,27 @@ components: $ref: '#/components/schemas/ClusterIndicesShardsIndex' primaries: description: Number of primary shards assigned to selected nodes. - type: number + type: integer + format: int32 replication: description: Ratio of replica shards to primary shards across all selected nodes. - type: number + type: integer + format: int32 total: description: Total number of shards assigned to selected nodes. - type: number + type: integer + format: int32 ClusterIndicesShardsIndex: type: object properties: primaries: + description: Contains statistics about the number of primary shards assigned to selected nodes. $ref: '#/components/schemas/ClusterShardMetrics' replication: + description: Contains statistics about the number of replication shards assigned to selected nodes. $ref: '#/components/schemas/ClusterShardMetrics' shards: + description: Contains statistics about the number of shards assigned to selected nodes. $ref: '#/components/schemas/ClusterShardMetrics' required: - primaries @@ -170,12 +144,15 @@ components: avg: description: Mean number of shards in an index, counting only shards assigned to selected nodes. type: number + format: double max: description: Maximum number of shards in an index, counting only shards assigned to selected nodes. type: number + format: double min: description: Minimum number of shards in an index, counting only shards assigned to selected nodes. type: number + format: double required: - avg - max @@ -188,26 +165,17 @@ components: type: array items: $ref: '#/components/schemas/FieldTypes' - total_field_count: - description: Total number of fields in all non-system indexes. - type: number - total_deduplicated_field_count: - description: Total number of fields in all non-system indexes, accounting for mapping deduplication. - type: number - total_deduplicated_mapping_size: - $ref: '_common.yaml#/components/schemas/HumanReadableByteCount' - total_deduplicated_mapping_size_in_bytes: - description: Total size of all mappings, in bytes, after deduplication and compression. - $ref: '_common.yaml#/components/schemas/ByteCount' required: - field_types IndicesVersions: type: object properties: index_count: - type: number + type: integer + format: int32 primary_shard_count: - type: number + type: integer + format: int32 total_primary_bytes: $ref: '_common.yaml#/components/schemas/ByteCount' version: @@ -221,23 +189,29 @@ components: type: object properties: count: + description: Contains counts for nodes selected by the request's node filters. $ref: '#/components/schemas/ClusterNodeCount' discovery_types: description: Contains statistics about the discovery types used by selected nodes. type: object additionalProperties: - type: number + type: integer + format: int32 fs: + description: Contains statistics about file stores by selected nodes. $ref: '#/components/schemas/ClusterFileSystem' indexing_pressure: $ref: '#/components/schemas/IndexingPressure' ingest: $ref: '#/components/schemas/ClusterIngest' jvm: + description: Contains statistics about the Java Virtual Machines (JVMs) used by selected nodes. $ref: '#/components/schemas/ClusterJvm' network_types: + description: Contains statistics about the transport and HTTP networks used by selected nodes. $ref: '#/components/schemas/ClusterNetworkTypes' os: + description: Contains statistics about the operating systems used by selected nodes. $ref: '#/components/schemas/ClusterOperatingSystem' packaging_types: description: Contains statistics about OpenSearch distributions installed on selected nodes. @@ -252,6 +226,7 @@ components: items: $ref: '_common.yaml#/components/schemas/PluginStats' process: + description: Contains statistics about processes used by selected nodes. $ref: '#/components/schemas/ClusterProcess' versions: description: Array of OpenSearch versions used on selected nodes. @@ -262,39 +237,55 @@ components: type: object properties: coordinating_only: - type: number + type: integer + format: int32 data: - type: number + type: integer + format: int32 data_cold: - type: number + type: integer + format: int32 data_content: - type: number + type: integer + format: int32 data_frozen: - type: number + type: integer + format: int32 data_hot: - type: number + type: integer + format: int32 data_warm: - type: number + type: integer + format: int32 ingest: - type: number + type: integer + format: int32 master: - type: number + type: integer + format: int32 cluster_manager: - type: number + type: integer + format: int32 x-version-added: '2.0' ml: - type: number + type: integer + format: int32 remote_cluster_client: - type: number + type: integer + format: int32 search: - type: number + type: integer + format: int32 x-version-added: '2.4' total: - type: number + type: integer + format: int32 transform: - type: number + type: integer + format: int32 voting_only: - type: number + type: integer + format: int32 required: - coordinating_only - data @@ -390,7 +381,8 @@ components: type: object properties: number_of_pipelines: - type: number + type: integer + format: int32 processor_stats: type: object additionalProperties: @@ -402,11 +394,14 @@ components: type: object properties: count: - type: number + type: integer + format: int64 current: - type: number + type: integer + format: int64 failed: - type: number + type: integer + format: int64 time: $ref: '_common.yaml#/components/schemas/Duration' time_in_millis: @@ -427,7 +422,8 @@ components: $ref: '#/components/schemas/ClusterJvmMemory' threads: description: Number of active threads in use by JVM across all selected nodes. - type: number + type: integer + format: int64 versions: description: Contains statistics about the JVM versions used by selected nodes. type: array @@ -464,7 +460,8 @@ components: type: boolean count: description: Total number of selected nodes using JVM. - type: number + type: integer + format: int32 using_bundled_jdk: description: If `true`, a bundled JDK is in use by JVM. type: boolean @@ -493,12 +490,14 @@ components: description: Contains statistics about the HTTP network types used by selected nodes. type: object additionalProperties: - type: number + type: integer + format: int32 transport_types: description: Contains statistics about the transport network types used by selected nodes. type: object additionalProperties: - type: number + type: integer + format: int32 required: - http_types - transport_types @@ -510,7 +509,8 @@ components: Number of processors used to calculate thread pool size across all selected nodes. This number can be set with the processors setting of a node and defaults to the number of processors reported by the operating system. In both cases, this number will never be larger than 32. - type: number + type: integer + format: int32 architectures: description: Contains statistics about processor architectures (for example, x86_64 or aarch64) used by selected nodes. type: array @@ -518,7 +518,8 @@ components: $ref: '#/components/schemas/ClusterOperatingSystemArchitecture' available_processors: description: Number of processors available to JVM across all selected nodes. - type: number + type: integer + format: int32 mem: $ref: '#/components/schemas/OperatingSystemMemoryInfo' names: @@ -545,7 +546,8 @@ components: type: string count: description: Number of selected nodes using the architecture. - type: number + type: integer + format: int32 required: - arch - count @@ -590,7 +592,8 @@ components: properties: count: description: Number of selected nodes using the operating system. - type: number + type: integer + format: int32 name: $ref: '_common.yaml#/components/schemas/Name' required: @@ -601,7 +604,8 @@ components: properties: count: description: Number of selected nodes using the operating system. - type: number + type: integer + format: int32 pretty_name: $ref: '_common.yaml#/components/schemas/Name' required: @@ -612,7 +616,8 @@ components: properties: count: description: Number of selected nodes using the distribution flavor and file type. - type: number + type: integer + format: int32 flavor: description: Type of OpenSearch distribution. This is always `default`. type: string @@ -649,17 +654,20 @@ components: description: |- Average number of concurrently open file descriptors. Returns `-1` if not supported. - type: number + type: integer + format: int64 max: description: |- Maximum number of concurrently open file descriptors allowed across all selected nodes. Returns `-1` if not supported. - type: number + type: integer + format: int64 min: description: |- Minimum number of concurrently open file descriptors across all selected nodes. Returns -1 if not supported. - type: number + type: integer + format: int64 required: - avg - max diff --git a/spec/schemas/nodes._common.yaml b/spec/schemas/nodes._common.yaml index 31a4317c3..7640634ab 100644 --- a/spec/schemas/nodes._common.yaml +++ b/spec/schemas/nodes._common.yaml @@ -185,6 +185,7 @@ components: type: object properties: _nodes: + description: Contains statistics about the number of nodes selected by the request's node filters. $ref: '_common.yaml#/components/schemas/NodeStatistics' NodeReloadResult: anyOf: