From 0ab2a7a61612bd3a54dff6296b7507bf19079f3b Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 9 Jun 2025 09:02:24 -0700 Subject: [PATCH] [DOCS] Add link for cluster settings (#4491) (cherry picked from commit 93cbe0b3bcd4996a2939c4ffa1dd7553441e32b5) --- output/openapi/elasticsearch-openapi.json | 11 +++++++++++ output/schema/schema.json | 15 ++++++++++++--- specification/_doc_ids/table.csv | 1 + .../get_settings/ClusterGetSettingsRequest.ts | 1 + .../get_settings/ClusterGetSettingsResponse.ts | 3 +++ .../put_settings/ClusterPutSettingsRequest.ts | 3 +++ 6 files changed, 31 insertions(+), 3 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index c9682de80a..66b311e205 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -4502,6 +4502,9 @@ ], "summary": "Get cluster-wide settings", "description": "By default, it returns only settings that have been explicitly defined.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html" + }, "operationId": "cluster-get-settings", "parameters": [ { @@ -4554,18 +4557,21 @@ "type": "object", "properties": { "persistent": { + "description": "The settings that persist after the cluster restarts.", "type": "object", "additionalProperties": { "type": "object" } }, "transient": { + "description": "The settings that do not persist after the cluster restarts.", "type": "object", "additionalProperties": { "type": "object" } }, "defaults": { + "description": "The default setting values.", "type": "object", "additionalProperties": { "type": "object" @@ -4588,6 +4594,9 @@ ], "summary": "Update the cluster settings", "description": "Configure and update dynamic settings on a running cluster.\nYou can also configure dynamic settings locally on an unstarted or shut down node in `elasticsearch.yml`.\n\nUpdates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart.\nYou can also reset transient or persistent settings by assigning them a null value.\n\nIf you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) `elasticsearch.yml` setting; 4) Default setting value.\nFor example, you can apply a transient setting to override a persistent setting or `elasticsearch.yml` setting.\nHowever, a change to an `elasticsearch.yml` setting will not override a defined transient or persistent setting.\n\nTIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster.\nIf you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings.\nOnly use `elasticsearch.yml` for static cluster settings and node settings.\nThe API doesn’t require a restart and ensures a setting’s value is the same on all nodes.\n\nWARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead.\nIf a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html" + }, "operationId": "cluster-put-settings", "parameters": [ { @@ -4628,12 +4637,14 @@ "type": "object", "properties": { "persistent": { + "description": "The settings that persist after the cluster restarts.", "type": "object", "additionalProperties": { "type": "object" } }, "transient": { + "description": "The settings that do not persist after the cluster restarts.", "type": "object", "additionalProperties": { "type": "object" diff --git a/output/schema/schema.json b/output/schema/schema.json index 84dc7b19e2..c6b41b0e7e 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -2523,6 +2523,8 @@ "description": "Get cluster-wide settings.\nBy default, it returns only settings that have been explicitly defined.", "docId": "cluster-get-settings", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-get-settings.html", + "extDocId": "es-settings", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/settings.html", "name": "cluster.get_settings", "privileges": { "cluster": [ @@ -2768,6 +2770,8 @@ "description": "Update the cluster settings.\n\nConfigure and update dynamic settings on a running cluster.\nYou can also configure dynamic settings locally on an unstarted or shut down node in `elasticsearch.yml`.\n\nUpdates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart.\nYou can also reset transient or persistent settings by assigning them a null value.\n\nIf you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) `elasticsearch.yml` setting; 4) Default setting value.\nFor example, you can apply a transient setting to override a persistent setting or `elasticsearch.yml` setting.\nHowever, a change to an `elasticsearch.yml` setting will not override a defined transient or persistent setting.\n\nTIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster.\nIf you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings.\nOnly use `elasticsearch.yml` for static cluster settings and node settings.\nThe API doesn’t require a restart and ensures a setting’s value is the same on all nodes.\n\nWARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead.\nIf a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.", "docId": "cluster-update-settings", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-update-settings.html", + "extDocId": "es-settings", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/settings.html", "name": "cluster.put_settings", "request": { "name": "Request", @@ -115004,7 +115008,7 @@ } } ], - "specLocation": "cluster/get_settings/ClusterGetSettingsRequest.ts#L23-L63" + "specLocation": "cluster/get_settings/ClusterGetSettingsRequest.ts#L23-L64" }, { "kind": "response", @@ -115012,6 +115016,7 @@ "kind": "properties", "properties": [ { + "description": "The settings that persist after the cluster restarts.", "name": "persistent", "required": true, "type": { @@ -115030,6 +115035,7 @@ } }, { + "description": "The settings that do not persist after the cluster restarts.", "name": "transient", "required": true, "type": { @@ -115048,6 +115054,7 @@ } }, { + "description": "The default setting values.", "name": "defaults", "required": false, "type": { @@ -115071,7 +115078,7 @@ "name": "Response", "namespace": "cluster.get_settings" }, - "specLocation": "cluster/get_settings/ClusterGetSettingsResponse.ts#L23-L29" + "specLocation": "cluster/get_settings/ClusterGetSettingsResponse.ts#L23-L32" }, { "kind": "interface", @@ -116310,6 +116317,7 @@ "kind": "properties", "properties": [ { + "description": "The settings that persist after the cluster restarts.", "name": "persistent", "required": false, "type": { @@ -116328,6 +116336,7 @@ } }, { + "description": "The settings that do not persist after the cluster restarts.", "name": "transient", "required": false, "type": { @@ -116411,7 +116420,7 @@ } } ], - "specLocation": "cluster/put_settings/ClusterPutSettingsRequest.ts#L25-L68" + "specLocation": "cluster/put_settings/ClusterPutSettingsRequest.ts#L25-L71" }, { "kind": "response", diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index e1af17e019..d8c3a2a9f5 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -203,6 +203,7 @@ eql-sequences,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/e eql-missing-events,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql-syntax.html#eql-missing-events eql-syntax,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql-syntax.html eql,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql.html +es-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/settings.html esql,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql.html esql-async-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-async-query-api.html esql-async-query-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/esql-async-query-delete-api.html diff --git a/specification/cluster/get_settings/ClusterGetSettingsRequest.ts b/specification/cluster/get_settings/ClusterGetSettingsRequest.ts index 60ac4bac6f..e9738535fb 100644 --- a/specification/cluster/get_settings/ClusterGetSettingsRequest.ts +++ b/specification/cluster/get_settings/ClusterGetSettingsRequest.ts @@ -28,6 +28,7 @@ import { Duration } from '@_types/Time' * @availability serverless stability=stable visibility=private * @cluster_privileges monitor * @doc_id cluster-get-settings + * @ext_doc_id es-settings */ export interface Request extends RequestBase { urls: [ diff --git a/specification/cluster/get_settings/ClusterGetSettingsResponse.ts b/specification/cluster/get_settings/ClusterGetSettingsResponse.ts index 495135b33f..af5c77c182 100644 --- a/specification/cluster/get_settings/ClusterGetSettingsResponse.ts +++ b/specification/cluster/get_settings/ClusterGetSettingsResponse.ts @@ -22,8 +22,11 @@ import { UserDefinedValue } from '@spec_utils/UserDefinedValue' export class Response { body: { + /** The settings that persist after the cluster restarts. */ persistent: Dictionary + /** The settings that do not persist after the cluster restarts. */ transient: Dictionary + /** The default setting values. */ defaults?: Dictionary } } diff --git a/specification/cluster/put_settings/ClusterPutSettingsRequest.ts b/specification/cluster/put_settings/ClusterPutSettingsRequest.ts index f7429a0d45..ed10c39634 100644 --- a/specification/cluster/put_settings/ClusterPutSettingsRequest.ts +++ b/specification/cluster/put_settings/ClusterPutSettingsRequest.ts @@ -46,6 +46,7 @@ import { UserDefinedValue } from '@spec_utils/UserDefinedValue' * @availability stack stability=stable * @availability serverless stability=stable visibility=private * @doc_id cluster-update-settings + * @ext_doc_id es-settings */ export interface Request extends RequestBase { urls: [ @@ -62,7 +63,9 @@ export interface Request extends RequestBase { timeout?: Duration } body: { + /** The settings that persist after the cluster restarts. */ persistent?: Dictionary + /** The settings that do not persist after the cluster restarts. */ transient?: Dictionary } }