From cdae60f4e3eac5524b3c6ab12b447586a8071850 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Mon, 16 Dec 2024 18:18:42 +0400 Subject: [PATCH 01/10] Fix update-rest-api-spec for 7.17 branch (#3288) --- .github/workflows/update-rest-api-json.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/update-rest-api-json.yml b/.github/workflows/update-rest-api-json.yml index a112cdf948..00b23f302a 100644 --- a/.github/workflows/update-rest-api-json.yml +++ b/.github/workflows/update-rest-api-json.yml @@ -13,7 +13,7 @@ jobs: strategy: fail-fast: false matrix: - branch: ['main', '8.x', '8.16', '8.17', 7.17'] + branch: ['main', '8.x', '8.16', '8.17', '7.17'] steps: - uses: actions/checkout@v4 From a2e56ab52e1e850d529e850111325b0413812491 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 16 Dec 2024 16:37:35 -0800 Subject: [PATCH 02/10] [DOCS] Edit migration summaries (#3298) --- output/openapi/elasticsearch-openapi.json | 12 +++++--- output/schema/schema.json | 29 +++++++++++++------ .../deprecations/DeprecationInfoRequest.ts | 5 ++++ .../GetFeatureUpgradeStatusRequest.ts | 7 +++++ .../PostFeatureUpgradeRequest.ts | 8 +++++ 5 files changed, 48 insertions(+), 13 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 67c12225ee..18c23fb23f 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -16477,7 +16477,8 @@ "tags": [ "migration" ], - "summary": "Retrieves information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version", + "summary": "Get deprecation information", + "description": "Get information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.\n\nTIP: This APIs is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant.", "operationId": "migration-deprecations", "responses": { "200": { @@ -16492,7 +16493,8 @@ "tags": [ "migration" ], - "summary": "Retrieves information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version", + "summary": "Get deprecation information", + "description": "Get information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.\n\nTIP: This APIs is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant.", "operationId": "migration-deprecations-1", "parameters": [ { @@ -16512,7 +16514,8 @@ "tags": [ "migration" ], - "summary": "Find out whether system features need to be upgraded or not", + "summary": "Get feature migration information", + "description": "Version upgrades sometimes require changes to how features store configuration information and data in system indices.\nCheck which features need to be migrated and the status of any migrations that are in progress.\n\nTIP: This API is designed for indirect use by the Upgrade Assistant.\nWe strongly recommend you use the Upgrade Assistant.", "operationId": "migration-get-feature-upgrade-status", "responses": { "200": { @@ -16547,7 +16550,8 @@ "tags": [ "migration" ], - "summary": "Begin upgrades for system features", + "summary": "Start the feature migration", + "description": "Version upgrades sometimes require changes to how features store configuration information and data in system indices.\nThis API starts the automatic migration process.\n\nSome functionality might be temporarily unavailable during the migration process.\n\nTIP: The API is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant.", "operationId": "migration-post-feature-upgrade", "responses": { "200": { diff --git a/output/schema/schema.json b/output/schema/schema.json index 478520ccf2..aa01964544 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -9546,9 +9546,14 @@ "stability": "stable" } }, - "description": "Retrieves information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.", + "description": "Get deprecation information.\nGet information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.\n\nTIP: This APIs is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/migration-api-deprecation.html", "name": "migration.deprecations", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "migration.deprecations" @@ -9583,10 +9588,13 @@ "stability": "stable" } }, - "description": "Find out whether system features need to be upgraded or not", + "description": "Get feature migration information.\nVersion upgrades sometimes require changes to how features store configuration information and data in system indices.\nCheck which features need to be migrated and the status of any migrations that are in progress.\n\nTIP: This API is designed for indirect use by the Upgrade Assistant.\nWe strongly recommend you use the Upgrade Assistant.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/migration-api-feature-upgrade.html", "name": "migration.get_feature_upgrade_status", "privileges": { + "cluster": [ + "manage" + ], "index": [ "manage" ] @@ -9619,10 +9627,13 @@ "stability": "stable" } }, - "description": "Begin upgrades for system features", + "description": "Start the feature migration.\nVersion upgrades sometimes require changes to how features store configuration information and data in system indices.\nThis API starts the automatic migration process.\n\nSome functionality might be temporarily unavailable during the migration process.\n\nTIP: The API is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/migration-api-feature-upgrade.html", "name": "migration.post_feature_upgrade", "privileges": { + "cluster": [ + "manage" + ], "index": [ "manage" ] @@ -149447,7 +149458,7 @@ "body": { "kind": "no_body" }, - "description": "Retrieves information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.", + "description": "Get deprecation information.\nGet information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.\n\nTIP: This APIs is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant.", "inherits": { "type": { "name": "RequestBase", @@ -149473,7 +149484,7 @@ } ], "query": [], - "specLocation": "migration/deprecations/DeprecationInfoRequest.ts#L23-L32" + "specLocation": "migration/deprecations/DeprecationInfoRequest.ts#L23-L37" }, { "kind": "response", @@ -149710,7 +149721,7 @@ "body": { "kind": "no_body" }, - "description": "Find out whether system features need to be upgraded or not", + "description": "Get feature migration information.\nVersion upgrades sometimes require changes to how features store configuration information and data in system indices.\nCheck which features need to be migrated and the status of any migrations that are in progress.\n\nTIP: This API is designed for indirect use by the Upgrade Assistant.\nWe strongly recommend you use the Upgrade Assistant.", "inherits": { "type": { "name": "RequestBase", @@ -149723,7 +149734,7 @@ }, "path": [], "query": [], - "specLocation": "migration/get_feature_upgrade_status/GetFeatureUpgradeStatusRequest.ts#L22-L27" + "specLocation": "migration/get_feature_upgrade_status/GetFeatureUpgradeStatusRequest.ts#L22-L34" }, { "kind": "response", @@ -149792,7 +149803,7 @@ "body": { "kind": "no_body" }, - "description": "Begin upgrades for system features", + "description": "Start the feature migration.\nVersion upgrades sometimes require changes to how features store configuration information and data in system indices.\nThis API starts the automatic migration process.\n\nSome functionality might be temporarily unavailable during the migration process.\n\nTIP: The API is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant.", "inherits": { "type": { "name": "RequestBase", @@ -149805,7 +149816,7 @@ }, "path": [], "query": [], - "specLocation": "migration/post_feature_upgrade/PostFeatureUpgradeRequest.ts#L22-L27" + "specLocation": "migration/post_feature_upgrade/PostFeatureUpgradeRequest.ts#L22-L35" }, { "kind": "response", diff --git a/specification/migration/deprecations/DeprecationInfoRequest.ts b/specification/migration/deprecations/DeprecationInfoRequest.ts index c901dc6f29..a750d93280 100644 --- a/specification/migration/deprecations/DeprecationInfoRequest.ts +++ b/specification/migration/deprecations/DeprecationInfoRequest.ts @@ -21,8 +21,13 @@ import { RequestBase } from '@_types/Base' import { IndexName } from '@_types/common' /** + * Get deprecation information. + * Get information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version. + * + * TIP: This APIs is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant. * @rest_spec_name migration.deprecations * @availability stack since=6.1.0 stability=stable + * @cluster_privileges manage */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/migration/get_feature_upgrade_status/GetFeatureUpgradeStatusRequest.ts b/specification/migration/get_feature_upgrade_status/GetFeatureUpgradeStatusRequest.ts index 54896f33b1..e953f6b4a5 100644 --- a/specification/migration/get_feature_upgrade_status/GetFeatureUpgradeStatusRequest.ts +++ b/specification/migration/get_feature_upgrade_status/GetFeatureUpgradeStatusRequest.ts @@ -20,8 +20,15 @@ import { RequestBase } from '@_types/Base' /** + * Get feature migration information. + * Version upgrades sometimes require changes to how features store configuration information and data in system indices. + * Check which features need to be migrated and the status of any migrations that are in progress. + * + * TIP: This API is designed for indirect use by the Upgrade Assistant. + * We strongly recommend you use the Upgrade Assistant. * @rest_spec_name migration.get_feature_upgrade_status * @availability stack since=7.16.0 stability=stable * @index_privileges manage + * @cluster_privileges manage */ export interface Request extends RequestBase {} diff --git a/specification/migration/post_feature_upgrade/PostFeatureUpgradeRequest.ts b/specification/migration/post_feature_upgrade/PostFeatureUpgradeRequest.ts index 30c6ff117e..822ecc610d 100644 --- a/specification/migration/post_feature_upgrade/PostFeatureUpgradeRequest.ts +++ b/specification/migration/post_feature_upgrade/PostFeatureUpgradeRequest.ts @@ -20,8 +20,16 @@ import { RequestBase } from '@_types/Base' /** + * Start the feature migration. + * Version upgrades sometimes require changes to how features store configuration information and data in system indices. + * This API starts the automatic migration process. + * + * Some functionality might be temporarily unavailable during the migration process. + * + * TIP: The API is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant. * @rest_spec_name migration.post_feature_upgrade * @availability stack since=7.16.0 stability=stable * @index_privileges manage + * @cluster_privileges manage */ export interface Request extends RequestBase {} From 6d26d93eef84970af49a2e7d413cf58be9f12911 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 16 Dec 2024 16:52:58 -0800 Subject: [PATCH 03/10] [DOCS] Edit machine learning summaries (#3299) --- output/openapi/elasticsearch-openapi.json | 8 ++++---- output/schema/schema.json | 11 ++++++----- specification/ml/info/MlInfoRequest.ts | 4 ++-- .../ml/validate_detector/MlValidateDetectorRequest.ts | 2 ++ 4 files changed, 14 insertions(+), 11 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 18c23fb23f..2d6f3d26e3 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -20413,8 +20413,8 @@ "tags": [ "ml" ], - "summary": "Return ML defaults and limits", - "description": "Returns defaults and limits used by machine learning.\nThis endpoint is designed to be used by a user interface that needs to fully\nunderstand machine learning configurations where some options are not\nspecified, meaning that the defaults should be used. This endpoint may be\nused to find out what those defaults are. It also provides information about\nthe maximum size of machine learning jobs that could run in the current\ncluster configuration.", + "summary": "Get machine learning information", + "description": "Get defaults and limits used by machine learning.\nThis endpoint is designed to be used by a user interface that needs to fully\nunderstand machine learning configurations where some options are not\nspecified, meaning that the defaults should be used. This endpoint may be\nused to find out what those defaults are. It also provides information about\nthe maximum size of machine learning jobs that could run in the current\ncluster configuration.", "operationId": "ml-info", "responses": { "200": { @@ -22590,9 +22590,9 @@ "/_ml/anomaly_detectors/_validate/detector": { "post": { "tags": [ - "ml" + "ml anomaly" ], - "summary": "Validates an anomaly detection detector", + "summary": "Validate an anomaly detection job", "operationId": "ml-validate-detector", "requestBody": { "content": { diff --git a/output/schema/schema.json b/output/schema/schema.json index aa01964544..c7f4430e4a 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -11440,7 +11440,7 @@ "stability": "stable" } }, - "description": "Return ML defaults and limits.\nReturns defaults and limits used by machine learning.\nThis endpoint is designed to be used by a user interface that needs to fully\nunderstand machine learning configurations where some options are not\nspecified, meaning that the defaults should be used. This endpoint may be\nused to find out what those defaults are. It also provides information about\nthe maximum size of machine learning jobs that could run in the current\ncluster configuration.", + "description": "Get machine learning information.\nGet defaults and limits used by machine learning.\nThis endpoint is designed to be used by a user interface that needs to fully\nunderstand machine learning configurations where some options are not\nspecified, meaning that the defaults should be used. This endpoint may be\nused to find out what those defaults are. It also provides information about\nthe maximum size of machine learning jobs that could run in the current\ncluster configuration.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/get-ml-info.html", "name": "ml.info", "privileges": { @@ -12919,7 +12919,8 @@ "visibility": "private" } }, - "description": "Validates an anomaly detection detector.", + "description": "Validate an anomaly detection job.", + "docTag": "ml anomaly", "docUrl": "https://www.elastic.co/guide/en/machine-learning/current/ml-jobs.html", "name": "ml.validate_detector", "request": { @@ -168598,7 +168599,7 @@ "body": { "kind": "no_body" }, - "description": "Return ML defaults and limits.\nReturns defaults and limits used by machine learning.\nThis endpoint is designed to be used by a user interface that needs to fully\nunderstand machine learning configurations where some options are not\nspecified, meaning that the defaults should be used. This endpoint may be\nused to find out what those defaults are. It also provides information about\nthe maximum size of machine learning jobs that could run in the current\ncluster configuration.", + "description": "Get machine learning information.\nGet defaults and limits used by machine learning.\nThis endpoint is designed to be used by a user interface that needs to fully\nunderstand machine learning configurations where some options are not\nspecified, meaning that the defaults should be used. This endpoint may be\nused to find out what those defaults are. It also provides information about\nthe maximum size of machine learning jobs that could run in the current\ncluster configuration.", "inherits": { "type": { "name": "RequestBase", @@ -175150,7 +175151,7 @@ } } }, - "description": "Validates an anomaly detection detector.", + "description": "Validate an anomaly detection job.", "inherits": { "type": { "name": "RequestBase", @@ -175163,7 +175164,7 @@ }, "path": [], "query": [], - "specLocation": "ml/validate_detector/MlValidateDetectorRequest.ts#L23-L31" + "specLocation": "ml/validate_detector/MlValidateDetectorRequest.ts#L23-L33" }, { "kind": "response", diff --git a/specification/ml/info/MlInfoRequest.ts b/specification/ml/info/MlInfoRequest.ts index 17ba0702d3..4f503ed165 100644 --- a/specification/ml/info/MlInfoRequest.ts +++ b/specification/ml/info/MlInfoRequest.ts @@ -20,8 +20,8 @@ import { RequestBase } from '@_types/Base' /** - * Return ML defaults and limits. - * Returns defaults and limits used by machine learning. + * Get machine learning information. + * Get defaults and limits used by machine learning. * This endpoint is designed to be used by a user interface that needs to fully * understand machine learning configurations where some options are not * specified, meaning that the defaults should be used. This endpoint may be diff --git a/specification/ml/validate_detector/MlValidateDetectorRequest.ts b/specification/ml/validate_detector/MlValidateDetectorRequest.ts index fc586c5fb2..e8f6c3a705 100644 --- a/specification/ml/validate_detector/MlValidateDetectorRequest.ts +++ b/specification/ml/validate_detector/MlValidateDetectorRequest.ts @@ -21,9 +21,11 @@ import { Detector } from '@ml/_types/Detector' import { RequestBase } from '@_types/Base' /** + * Validate an anomaly detection job. * @rest_spec_name ml.validate_detector * @availability stack since=5.4.0 stability=stable visibility=private * @availability serverless stability=stable visibility=private + * @doc_tag ml anomaly */ export interface Request extends RequestBase { /** @codegen_name detector */ From 7cf7656ca1ce195f08b70aa4a97a947a250a3068 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 16 Dec 2024 17:00:32 -0800 Subject: [PATCH 04/10] [DOCS] Fix monitoring operation summary and visibility (#3301) --- output/openapi/elasticsearch-openapi.json | 12 ++++++++---- output/schema/schema.json | 9 +++++---- .../monitoring/bulk/BulkMonitoringRequest.ts | 4 +++- 3 files changed, 16 insertions(+), 9 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 2d6f3d26e3..806a29b60c 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -22624,7 +22624,8 @@ "tags": [ "monitoring" ], - "summary": "Used by the monitoring features to send monitoring data", + "summary": "Send monitoring data", + "description": "This API is used by the monitoring features to send monitoring data.", "operationId": "monitoring-bulk-1", "parameters": [ { @@ -22651,7 +22652,8 @@ "tags": [ "monitoring" ], - "summary": "Used by the monitoring features to send monitoring data", + "summary": "Send monitoring data", + "description": "This API is used by the monitoring features to send monitoring data.", "operationId": "monitoring-bulk", "parameters": [ { @@ -22680,7 +22682,8 @@ "tags": [ "monitoring" ], - "summary": "Used by the monitoring features to send monitoring data", + "summary": "Send monitoring data", + "description": "This API is used by the monitoring features to send monitoring data.", "operationId": "monitoring-bulk-3", "parameters": [ { @@ -22710,7 +22713,8 @@ "tags": [ "monitoring" ], - "summary": "Used by the monitoring features to send monitoring data", + "summary": "Send monitoring data", + "description": "This API is used by the monitoring features to send monitoring data.", "operationId": "monitoring-bulk-2", "parameters": [ { diff --git a/output/schema/schema.json b/output/schema/schema.json index c7f4430e4a..314dc8f689 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -12951,10 +12951,11 @@ "availability": { "stack": { "since": "6.3.0", - "stability": "stable" + "stability": "stable", + "visibility": "private" } }, - "description": "Used by the monitoring features to send monitoring data.", + "description": "Send monitoring data.\nThis API is used by the monitoring features to send monitoring data.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/monitor-elasticsearch-cluster.html", "name": "monitoring.bulk", "request": { @@ -175238,7 +175239,7 @@ } } }, - "description": "Used by the monitoring features to send monitoring data.", + "description": "Send monitoring data.\nThis API is used by the monitoring features to send monitoring data.", "generics": [ { "name": "TDocument", @@ -175315,7 +175316,7 @@ } } ], - "specLocation": "monitoring/bulk/BulkMonitoringRequest.ts#L24-L59" + "specLocation": "monitoring/bulk/BulkMonitoringRequest.ts#L24-L61" }, { "kind": "response", diff --git a/specification/monitoring/bulk/BulkMonitoringRequest.ts b/specification/monitoring/bulk/BulkMonitoringRequest.ts index b991d9010e..90346fa55b 100644 --- a/specification/monitoring/bulk/BulkMonitoringRequest.ts +++ b/specification/monitoring/bulk/BulkMonitoringRequest.ts @@ -22,8 +22,10 @@ import { RequestBase } from '@_types/Base' import { Duration } from '@_types/Time' /** + * Send monitoring data. + * This API is used by the monitoring features to send monitoring data. * @rest_spec_name monitoring.bulk - * @availability stack since=6.3.0 stability=stable + * @availability stack since=6.3.0 stability=stable visibility=private */ export interface Request extends RequestBase { path_parts: { From 0a8b60a595343387b55a78e8cf0049b3964034e4 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 16 Dec 2024 17:17:50 -0800 Subject: [PATCH 05/10] [DOCS] Edit node lifecycle summaries (#3309) --- output/openapi/elasticsearch-openapi.json | 16 ++++----- output/schema/schema.json | 33 ++++++++++++++----- .../delete_node/ShutdownDeleteNodeRequest.ts | 10 ++++++ .../get_node/ShutdownGetNodeRequest.ts | 9 +++++ .../put_node/ShutdownPutNodeRequest.ts | 15 +++++++++ 5 files changed, 66 insertions(+), 17 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 806a29b60c..ce5940e0ac 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -30933,8 +30933,8 @@ "tags": [ "shutdown" ], - "summary": "Retrieve status of a node or nodes that are currently marked as shutting down", - "description": "Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "summary": "Get the shutdown status", + "description": "Get information about nodes that are ready to be shut down, have shut down preparations still in progress, or have stalled.\nThe API returns status information for each part of the shut down process.\n\nNOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.", "operationId": "shutdown-get-node-1", "parameters": [ { @@ -30958,8 +30958,8 @@ "tags": [ "shutdown" ], - "summary": "Adds a node to be shut down", - "description": "Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "summary": "Prepare a node to be shut down", + "description": "NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.\n\nThe API migrates ongoing tasks and index shards to other nodes as needed to prepare a node to be restarted or shut down and removed from the cluster.\nThis ensures that Elasticsearch can be stopped safely with minimal disruption to the cluster.\n\nYou must specify the type of shutdown: `restart`, `remove`, or `replace`.\nIf a node is already being prepared for shutdown, you can use this API to change the shutdown type.\n\nIMPORTANT: This API does NOT terminate the Elasticsearch process.\nMonitor the node shutdown status to determine when it is safe to stop Elasticsearch.", "operationId": "shutdown-put-node", "parameters": [ { @@ -31043,8 +31043,8 @@ "tags": [ "shutdown" ], - "summary": "Removes a node from the shutdown list", - "description": "Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "summary": "Cancel node shutdown preparations", + "description": "Remove a node from the shutdown list so it can resume normal operations.\nYou must explicitly clear the shutdown request when a node rejoins the cluster or when a node has permanently left the cluster.\nShutdown requests are never removed automatically by Elasticsearch.\n\nNOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes.\nDirect use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.", "operationId": "shutdown-delete-node", "parameters": [ { @@ -31099,8 +31099,8 @@ "tags": [ "shutdown" ], - "summary": "Retrieve status of a node or nodes that are currently marked as shutting down", - "description": "Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "summary": "Get the shutdown status", + "description": "Get information about nodes that are ready to be shut down, have shut down preparations still in progress, or have stalled.\nThe API returns status information for each part of the shut down process.\n\nNOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.", "operationId": "shutdown-get-node", "parameters": [ { diff --git a/output/schema/schema.json b/output/schema/schema.json index 314dc8f689..c3d734e4c5 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -17686,9 +17686,14 @@ "stability": "stable" } }, - "description": "Removes a node from the shutdown list. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "description": "Cancel node shutdown preparations.\nRemove a node from the shutdown list so it can resume normal operations.\nYou must explicitly clear the shutdown request when a node rejoins the cluster or when a node has permanently left the cluster.\nShutdown requests are never removed automatically by Elasticsearch.\n\nNOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes.\nDirect use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current", "name": "shutdown.delete_node", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "shutdown.delete_node" @@ -17720,9 +17725,14 @@ "stability": "stable" } }, - "description": "Retrieve status of a node or nodes that are currently marked as shutting down. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "description": "Get the shutdown status.\n\nGet information about nodes that are ready to be shut down, have shut down preparations still in progress, or have stalled.\nThe API returns status information for each part of the shut down process.\n\nNOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current", "name": "shutdown.get_node", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "shutdown.get_node" @@ -17760,9 +17770,14 @@ "stability": "stable" } }, - "description": "Adds a node to be shut down. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "description": "Prepare a node to be shut down.\n\nNOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.\n\nThe API migrates ongoing tasks and index shards to other nodes as needed to prepare a node to be restarted or shut down and removed from the cluster.\nThis ensures that Elasticsearch can be stopped safely with minimal disruption to the cluster.\n\nYou must specify the type of shutdown: `restart`, `remove`, or `replace`.\nIf a node is already being prepared for shutdown, you can use this API to change the shutdown type.\n\nIMPORTANT: This API does NOT terminate the Elasticsearch process.\nMonitor the node shutdown status to determine when it is safe to stop Elasticsearch.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current", "name": "shutdown.put_node", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "shutdown.put_node" @@ -199980,7 +199995,7 @@ "body": { "kind": "no_body" }, - "description": "Removes a node from the shutdown list. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "description": "Cancel node shutdown preparations.\nRemove a node from the shutdown list so it can resume normal operations.\nYou must explicitly clear the shutdown request when a node rejoins the cluster or when a node has permanently left the cluster.\nShutdown requests are never removed automatically by Elasticsearch.\n\nNOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes.\nDirect use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.", "inherits": { "type": { "name": "RequestBase", @@ -200033,7 +200048,7 @@ } } ], - "specLocation": "shutdown/delete_node/ShutdownDeleteNodeRequest.ts#L24-L44" + "specLocation": "shutdown/delete_node/ShutdownDeleteNodeRequest.ts#L24-L54" }, { "kind": "response", @@ -200210,7 +200225,7 @@ "body": { "kind": "no_body" }, - "description": "Retrieve status of a node or nodes that are currently marked as shutting down. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "description": "Get the shutdown status.\n\nGet information about nodes that are ready to be shut down, have shut down preparations still in progress, or have stalled.\nThe API returns status information for each part of the shut down process.\n\nNOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.", "inherits": { "type": { "name": "RequestBase", @@ -200263,7 +200278,7 @@ } } ], - "specLocation": "shutdown/get_node/ShutdownGetNodeRequest.ts#L24-L44" + "specLocation": "shutdown/get_node/ShutdownGetNodeRequest.ts#L24-L53" }, { "kind": "response", @@ -200409,7 +200424,7 @@ } ] }, - "description": "Adds a node to be shut down. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "description": "Prepare a node to be shut down.\n\nNOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.\n\nThe API migrates ongoing tasks and index shards to other nodes as needed to prepare a node to be restarted or shut down and removed from the cluster.\nThis ensures that Elasticsearch can be stopped safely with minimal disruption to the cluster.\n\nYou must specify the type of shutdown: `restart`, `remove`, or `replace`.\nIf a node is already being prepared for shutdown, you can use this API to change the shutdown type.\n\nIMPORTANT: This API does NOT terminate the Elasticsearch process.\nMonitor the node shutdown status to determine when it is safe to stop Elasticsearch.", "inherits": { "type": { "name": "RequestBase", @@ -200462,7 +200477,7 @@ } } ], - "specLocation": "shutdown/put_node/ShutdownPutNodeRequest.ts#L25-L76" + "specLocation": "shutdown/put_node/ShutdownPutNodeRequest.ts#L25-L91" }, { "kind": "response", diff --git a/specification/shutdown/delete_node/ShutdownDeleteNodeRequest.ts b/specification/shutdown/delete_node/ShutdownDeleteNodeRequest.ts index 25df4239a5..e84a7d7d28 100644 --- a/specification/shutdown/delete_node/ShutdownDeleteNodeRequest.ts +++ b/specification/shutdown/delete_node/ShutdownDeleteNodeRequest.ts @@ -22,8 +22,18 @@ import { NodeId } from '@_types/common' import { TimeUnit } from '@_types/Time' /** + * Cancel node shutdown preparations. + * Remove a node from the shutdown list so it can resume normal operations. + * You must explicitly clear the shutdown request when a node rejoins the cluster or when a node has permanently left the cluster. + * Shutdown requests are never removed automatically by Elasticsearch. + * + * NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. + * Direct use is not supported. + * + * If the operator privileges feature is enabled, you must be an operator to use this API. * @rest_spec_name shutdown.delete_node * @availability stack since=7.13.0 stability=stable + * @cluster_privileges manage */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/shutdown/get_node/ShutdownGetNodeRequest.ts b/specification/shutdown/get_node/ShutdownGetNodeRequest.ts index 63fed84660..e74fa31743 100644 --- a/specification/shutdown/get_node/ShutdownGetNodeRequest.ts +++ b/specification/shutdown/get_node/ShutdownGetNodeRequest.ts @@ -22,8 +22,17 @@ import { NodeIds } from '@_types/common' import { TimeUnit } from '@_types/Time' /** + * Get the shutdown status. + * + * Get information about nodes that are ready to be shut down, have shut down preparations still in progress, or have stalled. + * The API returns status information for each part of the shut down process. + * + * NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported. + * + * If the operator privileges feature is enabled, you must be an operator to use this API. * @rest_spec_name shutdown.get_node * @availability stack since=7.13.0 stability=stable + * @cluster_privileges manage */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/shutdown/put_node/ShutdownPutNodeRequest.ts b/specification/shutdown/put_node/ShutdownPutNodeRequest.ts index 6ab62d3eb5..318f9128b5 100644 --- a/specification/shutdown/put_node/ShutdownPutNodeRequest.ts +++ b/specification/shutdown/put_node/ShutdownPutNodeRequest.ts @@ -23,8 +23,23 @@ import { TimeUnit } from '@_types/Time' import { Type } from '../_types/types' /** + * Prepare a node to be shut down. + * + * NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported. + * + * If the operator privileges feature is enabled, you must be an operator to use this API. + * + * The API migrates ongoing tasks and index shards to other nodes as needed to prepare a node to be restarted or shut down and removed from the cluster. + * This ensures that Elasticsearch can be stopped safely with minimal disruption to the cluster. + * + * You must specify the type of shutdown: `restart`, `remove`, or `replace`. + * If a node is already being prepared for shutdown, you can use this API to change the shutdown type. + * + * IMPORTANT: This API does NOT terminate the Elasticsearch process. + * Monitor the node shutdown status to determine when it is safe to stop Elasticsearch. * @rest_spec_name shutdown.put_node * @availability stack since=7.13.0 stability=stable + * @cluster_privileges manage */ export interface Request extends RequestBase { path_parts: { From 89d1b0e5cc0673b7eb3933b1fb772953dcc8e085 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 16 Dec 2024 17:40:03 -0800 Subject: [PATCH 06/10] [DOCS] Edit snapshot lifecycle management summaries (#3317) --- output/openapi/elasticsearch-openapi.json | 31 +++--- output/schema/schema.json | 99 +++++++++++++------ .../DeleteSnapshotLifecycleRequest.ts | 4 + .../ExecuteSnapshotLifecycleRequest.ts | 4 + .../ExecuteRetentionRequest.ts | 4 + .../GetSnapshotLifecycleRequest.ts | 6 ++ .../GetSnapshotLifecycleStatsRequest.ts | 3 + ...napshotLifecycleManagementStatusRequest.ts | 2 + .../PutSnapshotLifecycleRequest.ts | 8 +- ...StartSnapshotLifecycleManagementRequest.ts | 4 + .../StopSnapshotLifecycleManagementRequest.ts | 8 ++ 11 files changed, 133 insertions(+), 40 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index ce5940e0ac..96e83e4d63 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -31123,7 +31123,8 @@ "tags": [ "slm" ], - "summary": "Retrieves one or more snapshot lifecycle policy definitions and information about the latest snapshot attempts", + "summary": "Get policy information", + "description": "Get snapshot lifecycle policy definitions and information about the latest snapshot attempts.", "operationId": "slm-get-lifecycle", "parameters": [ { @@ -31141,13 +31142,14 @@ "tags": [ "slm" ], - "summary": "Creates or updates a snapshot lifecycle policy", + "summary": "Create or update a policy", + "description": "Create or update a snapshot lifecycle policy.\nIf the policy already exists, this request increments the policy version.\nOnly the latest version of a policy is stored.", "operationId": "slm-put-lifecycle", "parameters": [ { "in": "path", "name": "policy_id", - "description": "ID for the snapshot lifecycle policy you want to create or update.", + "description": "The identifier for the snapshot lifecycle policy you want to create or update.", "required": true, "deprecated": false, "schema": { @@ -31221,7 +31223,8 @@ "tags": [ "slm" ], - "summary": "Deletes an existing snapshot lifecycle policy", + "summary": "Delete a policy", + "description": "Delete a snapshot lifecycle policy definition.\nThis operation prevents any future snapshots from being taken but does not cancel in-progress snapshots or remove previously-taken snapshots.", "operationId": "slm-delete-lifecycle", "parameters": [ { @@ -31256,7 +31259,8 @@ "tags": [ "slm" ], - "summary": "Immediately creates a snapshot according to the lifecycle policy, without waiting for the scheduled time", + "summary": "Run a policy", + "description": "Immediately create a snapshot according to the snapshot lifecycle policy without waiting for the scheduled time.\nThe snapshot policy is normally applied according to its schedule, but you might want to manually run a policy before performing an upgrade or other maintenance.", "operationId": "slm-execute-lifecycle", "parameters": [ { @@ -31299,7 +31303,8 @@ "tags": [ "slm" ], - "summary": "Deletes any snapshots that are expired according to the policy's retention rules", + "summary": "Run a retention policy", + "description": "Manually apply the retention policy to force immediate removal of snapshots that are expired according to the snapshot lifecycle policy retention rules.\nThe retention policy is normally applied according to its schedule.", "operationId": "slm-execute-retention", "responses": { "200": { @@ -31321,7 +31326,8 @@ "tags": [ "slm" ], - "summary": "Retrieves one or more snapshot lifecycle policy definitions and information about the latest snapshot attempts", + "summary": "Get policy information", + "description": "Get snapshot lifecycle policy definitions and information about the latest snapshot attempts.", "operationId": "slm-get-lifecycle-1", "responses": { "200": { @@ -31336,7 +31342,8 @@ "tags": [ "slm" ], - "summary": "Returns global and policy-level statistics about actions taken by snapshot lifecycle management", + "summary": "Get snapshot lifecycle management statistics", + "description": "Get global and policy-level statistics about actions taken by snapshot lifecycle management.", "operationId": "slm-get-stats", "responses": { "200": { @@ -31405,7 +31412,7 @@ "tags": [ "slm" ], - "summary": "Retrieves the status of snapshot lifecycle management (SLM)", + "summary": "Get the snapshot lifecycle management status", "operationId": "slm-get-status", "responses": { "200": { @@ -31435,7 +31442,8 @@ "tags": [ "slm" ], - "summary": "Turns on snapshot lifecycle management (SLM)", + "summary": "Start snapshot lifecycle management", + "description": "Snapshot lifecycle management (SLM) starts automatically when a cluster is formed.\nManually starting SLM is necessary only if it has been stopped using the stop SLM API.", "operationId": "slm-start", "responses": { "200": { @@ -31457,7 +31465,8 @@ "tags": [ "slm" ], - "summary": "Turns off snapshot lifecycle management (SLM)", + "summary": "Stop snapshot lifecycle management", + "description": "Stop all snapshot lifecycle management (SLM) operations and the SLM plugin.\nThis API is useful when you are performing maintenance on a cluster and need to prevent SLM from performing any actions on your data streams or indices.\nStopping SLM does not stop any snapshots that are in progress.\nYou can manually trigger snapshots with the run snapshot lifecycle policy API even if SLM is stopped.\n\nThe API returns a response as soon as the request is acknowledged, but the plugin might continue to run until in-progress operations complete and it can be safely stopped.\nUse the get snapshot lifecycle management status API to see if SLM is running.", "operationId": "slm-stop", "responses": { "200": { diff --git a/output/schema/schema.json b/output/schema/schema.json index c3d734e4c5..0ebda07466 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -17849,9 +17849,14 @@ "stability": "stable" } }, - "description": "Deletes an existing snapshot lifecycle policy.", + "description": "Delete a policy.\nDelete a snapshot lifecycle policy definition.\nThis operation prevents any future snapshots from being taken but does not cancel in-progress snapshots or remove previously-taken snapshots.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-delete-policy.html", "name": "slm.delete_lifecycle", + "privileges": { + "cluster": [ + "manage_slm" + ] + }, "request": { "name": "Request", "namespace": "slm.delete_lifecycle" @@ -17884,9 +17889,14 @@ "stability": "stable" } }, - "description": "Immediately creates a snapshot according to the lifecycle policy, without waiting for the scheduled time.", + "description": "Run a policy.\nImmediately create a snapshot according to the snapshot lifecycle policy without waiting for the scheduled time.\nThe snapshot policy is normally applied according to its schedule, but you might want to manually run a policy before performing an upgrade or other maintenance.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-execute-lifecycle.html", "name": "slm.execute_lifecycle", + "privileges": { + "cluster": [ + "manage_slm" + ] + }, "request": { "name": "Request", "namespace": "slm.execute_lifecycle" @@ -17919,9 +17929,14 @@ "stability": "stable" } }, - "description": "Deletes any snapshots that are expired according to the policy's retention rules.", + "description": "Run a retention policy.\nManually apply the retention policy to force immediate removal of snapshots that are expired according to the snapshot lifecycle policy retention rules.\nThe retention policy is normally applied according to its schedule.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-execute-retention.html", "name": "slm.execute_retention", + "privileges": { + "cluster": [ + "manage_slm" + ] + }, "request": { "name": "Request", "namespace": "slm.execute_retention" @@ -17954,9 +17969,14 @@ "stability": "stable" } }, - "description": "Retrieves one or more snapshot lifecycle policy definitions and information about the latest snapshot attempts.", + "description": "Get policy information.\nGet snapshot lifecycle policy definitions and information about the latest snapshot attempts.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-get-policy.html", "name": "slm.get_lifecycle", + "privileges": { + "cluster": [ + "manage_slm" + ] + }, "request": { "name": "Request", "namespace": "slm.get_lifecycle" @@ -17995,9 +18015,14 @@ "stability": "stable" } }, - "description": "Returns global and policy-level statistics about actions taken by snapshot lifecycle management.", + "description": "Get snapshot lifecycle management statistics.\nGet global and policy-level statistics about actions taken by snapshot lifecycle management.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/slm-api-get-stats.html", "name": "slm.get_stats", + "privileges": { + "cluster": [ + "manage_slm" + ] + }, "request": { "name": "Request", "namespace": "slm.get_stats" @@ -18030,9 +18055,14 @@ "stability": "stable" } }, - "description": "Retrieves the status of snapshot lifecycle management (SLM).", + "description": "Get the snapshot lifecycle management status.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-get-status.html", "name": "slm.get_status", + "privileges": { + "cluster": [ + "read_slm" + ] + }, "request": { "name": "Request", "namespace": "slm.get_status" @@ -18065,9 +18095,17 @@ "stability": "stable" } }, - "description": "Creates or updates a snapshot lifecycle policy.", + "description": "Create or update a policy.\nCreate or update a snapshot lifecycle policy.\nIf the policy already exists, this request increments the policy version.\nOnly the latest version of a policy is stored.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-put-policy.html", "name": "slm.put_lifecycle", + "privileges": { + "cluster": [ + "manage_slm" + ], + "index": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "slm.put_lifecycle" @@ -18103,9 +18141,14 @@ "stability": "stable" } }, - "description": "Turns on snapshot lifecycle management (SLM).", + "description": "Start snapshot lifecycle management.\nSnapshot lifecycle management (SLM) starts automatically when a cluster is formed.\nManually starting SLM is necessary only if it has been stopped using the stop SLM API.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-start.html", "name": "slm.start", + "privileges": { + "cluster": [ + "manage_slm" + ] + }, "request": { "name": "Request", "namespace": "slm.start" @@ -18138,7 +18181,7 @@ "stability": "stable" } }, - "description": "Turns off snapshot lifecycle management (SLM).", + "description": "Stop snapshot lifecycle management.\nStop all snapshot lifecycle management (SLM) operations and the SLM plugin.\nThis API is useful when you are performing maintenance on a cluster and need to prevent SLM from performing any actions on your data streams or indices.\nStopping SLM does not stop any snapshots that are in progress.\nYou can manually trigger snapshots with the run snapshot lifecycle policy API even if SLM is stopped.\n\nThe API returns a response as soon as the request is acknowledged, but the plugin might continue to run until in-progress operations complete and it can be safely stopped.\nUse the get snapshot lifecycle management status API to see if SLM is running.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-stop.html", "name": "slm.stop", "request": { @@ -201078,7 +201121,7 @@ "body": { "kind": "no_body" }, - "description": "Deletes an existing snapshot lifecycle policy.", + "description": "Delete a policy.\nDelete a snapshot lifecycle policy definition.\nThis operation prevents any future snapshots from being taken but does not cancel in-progress snapshots or remove previously-taken snapshots.", "inherits": { "type": { "name": "RequestBase", @@ -201104,7 +201147,7 @@ } ], "query": [], - "specLocation": "slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts#L23-L32" + "specLocation": "slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts#L23-L36" }, { "kind": "response", @@ -201132,7 +201175,7 @@ "body": { "kind": "no_body" }, - "description": "Immediately creates a snapshot according to the lifecycle policy, without waiting for the scheduled time.", + "description": "Run a policy.\nImmediately create a snapshot according to the snapshot lifecycle policy without waiting for the scheduled time.\nThe snapshot policy is normally applied according to its schedule, but you might want to manually run a policy before performing an upgrade or other maintenance.", "inherits": { "type": { "name": "RequestBase", @@ -201158,7 +201201,7 @@ } ], "query": [], - "specLocation": "slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts#L23-L32" + "specLocation": "slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts#L23-L36" }, { "kind": "response", @@ -201192,7 +201235,7 @@ "body": { "kind": "no_body" }, - "description": "Deletes any snapshots that are expired according to the policy's retention rules.", + "description": "Run a retention policy.\nManually apply the retention policy to force immediate removal of snapshots that are expired according to the snapshot lifecycle policy retention rules.\nThe retention policy is normally applied according to its schedule.", "inherits": { "type": { "name": "RequestBase", @@ -201205,7 +201248,7 @@ }, "path": [], "query": [], - "specLocation": "slm/execute_retention/ExecuteRetentionRequest.ts#L22-L27" + "specLocation": "slm/execute_retention/ExecuteRetentionRequest.ts#L22-L31" }, { "kind": "response", @@ -201233,7 +201276,7 @@ "body": { "kind": "no_body" }, - "description": "Retrieves one or more snapshot lifecycle policy definitions and information about the latest snapshot attempts.", + "description": "Get policy information.\nGet snapshot lifecycle policy definitions and information about the latest snapshot attempts.", "inherits": { "type": { "name": "RequestBase", @@ -201259,7 +201302,7 @@ } ], "query": [], - "specLocation": "slm/get_lifecycle/GetSnapshotLifecycleRequest.ts#L23-L32" + "specLocation": "slm/get_lifecycle/GetSnapshotLifecycleRequest.ts#L23-L38" }, { "kind": "response", @@ -201298,7 +201341,7 @@ "body": { "kind": "no_body" }, - "description": "Returns global and policy-level statistics about actions taken by snapshot lifecycle management.", + "description": "Get snapshot lifecycle management statistics.\nGet global and policy-level statistics about actions taken by snapshot lifecycle management.", "inherits": { "type": { "name": "RequestBase", @@ -201311,7 +201354,7 @@ }, "path": [], "query": [], - "specLocation": "slm/get_stats/GetSnapshotLifecycleStatsRequest.ts#L22-L27" + "specLocation": "slm/get_stats/GetSnapshotLifecycleStatsRequest.ts#L22-L30" }, { "kind": "response", @@ -201456,7 +201499,7 @@ "body": { "kind": "no_body" }, - "description": "Retrieves the status of snapshot lifecycle management (SLM).", + "description": "Get the snapshot lifecycle management status.", "inherits": { "type": { "name": "RequestBase", @@ -201469,7 +201512,7 @@ }, "path": [], "query": [], - "specLocation": "slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts#L22-L27" + "specLocation": "slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts#L22-L29" }, { "kind": "response", @@ -201565,7 +201608,7 @@ } ] }, - "description": "Creates or updates a snapshot lifecycle policy.", + "description": "Create or update a policy.\nCreate or update a snapshot lifecycle policy.\nIf the policy already exists, this request increments the policy version.\nOnly the latest version of a policy is stored.", "inherits": { "type": { "name": "RequestBase", @@ -201578,7 +201621,7 @@ }, "path": [ { - "description": "ID for the snapshot lifecycle policy you want to create or update.", + "description": "The identifier for the snapshot lifecycle policy you want to create or update.", "name": "policy_id", "required": true, "type": { @@ -201618,7 +201661,7 @@ } } ], - "specLocation": "slm/put_lifecycle/PutSnapshotLifecycleRequest.ts#L26-L72" + "specLocation": "slm/put_lifecycle/PutSnapshotLifecycleRequest.ts#L26-L78" }, { "kind": "response", @@ -201646,7 +201689,7 @@ "body": { "kind": "no_body" }, - "description": "Turns on snapshot lifecycle management (SLM).", + "description": "Start snapshot lifecycle management.\nSnapshot lifecycle management (SLM) starts automatically when a cluster is formed.\nManually starting SLM is necessary only if it has been stopped using the stop SLM API.", "inherits": { "type": { "name": "RequestBase", @@ -201659,7 +201702,7 @@ }, "path": [], "query": [], - "specLocation": "slm/start/StartSnapshotLifecycleManagementRequest.ts#L22-L27" + "specLocation": "slm/start/StartSnapshotLifecycleManagementRequest.ts#L22-L31" }, { "kind": "response", @@ -201687,7 +201730,7 @@ "body": { "kind": "no_body" }, - "description": "Turns off snapshot lifecycle management (SLM).", + "description": "Stop snapshot lifecycle management.\nStop all snapshot lifecycle management (SLM) operations and the SLM plugin.\nThis API is useful when you are performing maintenance on a cluster and need to prevent SLM from performing any actions on your data streams or indices.\nStopping SLM does not stop any snapshots that are in progress.\nYou can manually trigger snapshots with the run snapshot lifecycle policy API even if SLM is stopped.\n\nThe API returns a response as soon as the request is acknowledged, but the plugin might continue to run until in-progress operations complete and it can be safely stopped.\nUse the get snapshot lifecycle management status API to see if SLM is running.", "inherits": { "type": { "name": "RequestBase", @@ -201700,7 +201743,7 @@ }, "path": [], "query": [], - "specLocation": "slm/stop/StopSnapshotLifecycleManagementRequest.ts#L22-L27" + "specLocation": "slm/stop/StopSnapshotLifecycleManagementRequest.ts#L22-L35" }, { "kind": "response", diff --git a/specification/slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts b/specification/slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts index b7226560a6..3699ce3608 100644 --- a/specification/slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts +++ b/specification/slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts @@ -21,9 +21,13 @@ import { RequestBase } from '@_types/Base' import { Name } from '@_types/common' /** + * Delete a policy. + * Delete a snapshot lifecycle policy definition. + * This operation prevents any future snapshots from being taken but does not cancel in-progress snapshots or remove previously-taken snapshots. * @rest_spec_name slm.delete_lifecycle * @availability stack since=7.4.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage_slm */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts b/specification/slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts index 487930b114..5ca42d3cce 100644 --- a/specification/slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts +++ b/specification/slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts @@ -21,9 +21,13 @@ import { RequestBase } from '@_types/Base' import { Name } from '@_types/common' /** + * Run a policy. + * Immediately create a snapshot according to the snapshot lifecycle policy without waiting for the scheduled time. + * The snapshot policy is normally applied according to its schedule, but you might want to manually run a policy before performing an upgrade or other maintenance. * @rest_spec_name slm.execute_lifecycle * @availability stack since=7.4.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage_slm */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/slm/execute_retention/ExecuteRetentionRequest.ts b/specification/slm/execute_retention/ExecuteRetentionRequest.ts index 9c672d8a1f..458fd23372 100644 --- a/specification/slm/execute_retention/ExecuteRetentionRequest.ts +++ b/specification/slm/execute_retention/ExecuteRetentionRequest.ts @@ -20,8 +20,12 @@ import { RequestBase } from '@_types/Base' /** + * Run a retention policy. + * Manually apply the retention policy to force immediate removal of snapshots that are expired according to the snapshot lifecycle policy retention rules. + * The retention policy is normally applied according to its schedule. * @rest_spec_name slm.execute_retention * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage_slm */ export interface Request extends RequestBase {} diff --git a/specification/slm/get_lifecycle/GetSnapshotLifecycleRequest.ts b/specification/slm/get_lifecycle/GetSnapshotLifecycleRequest.ts index c61c32337e..b1e6ad614d 100644 --- a/specification/slm/get_lifecycle/GetSnapshotLifecycleRequest.ts +++ b/specification/slm/get_lifecycle/GetSnapshotLifecycleRequest.ts @@ -21,12 +21,18 @@ import { RequestBase } from '@_types/Base' import { Names } from '@_types/common' /** + * Get policy information. + * Get snapshot lifecycle policy definitions and information about the latest snapshot attempts. * @rest_spec_name slm.get_lifecycle * @availability stack since=7.4.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage_slm */ export interface Request extends RequestBase { path_parts: { + /* + A comma-separate list of snapshot lifecycle policy identifiers. + */ policy_id?: Names } } diff --git a/specification/slm/get_stats/GetSnapshotLifecycleStatsRequest.ts b/specification/slm/get_stats/GetSnapshotLifecycleStatsRequest.ts index 178ca6b4e6..fc55ea2ef9 100644 --- a/specification/slm/get_stats/GetSnapshotLifecycleStatsRequest.ts +++ b/specification/slm/get_stats/GetSnapshotLifecycleStatsRequest.ts @@ -20,8 +20,11 @@ import { RequestBase } from '@_types/Base' /** + * Get snapshot lifecycle management statistics. + * Get global and policy-level statistics about actions taken by snapshot lifecycle management. * @rest_spec_name slm.get_stats * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage_slm */ export interface Request extends RequestBase {} diff --git a/specification/slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts b/specification/slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts index 5c162fe0a6..7ffec86da8 100644 --- a/specification/slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts +++ b/specification/slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts @@ -20,8 +20,10 @@ import { RequestBase } from '@_types/Base' /** + * Get the snapshot lifecycle management status. * @rest_spec_name slm.get_status * @availability stack since=7.6.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges read_slm */ export interface Request extends RequestBase {} diff --git a/specification/slm/put_lifecycle/PutSnapshotLifecycleRequest.ts b/specification/slm/put_lifecycle/PutSnapshotLifecycleRequest.ts index b6b79b47df..66e107f2ca 100644 --- a/specification/slm/put_lifecycle/PutSnapshotLifecycleRequest.ts +++ b/specification/slm/put_lifecycle/PutSnapshotLifecycleRequest.ts @@ -24,14 +24,20 @@ import { Name } from '@_types/common' import { Duration } from '@_types/Time' /** + * Create or update a policy. + * Create or update a snapshot lifecycle policy. + * If the policy already exists, this request increments the policy version. + * Only the latest version of a policy is stored. * @rest_spec_name slm.put_lifecycle * @availability stack since=7.4.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage_slm + * @index_privileges manage */ export interface Request extends RequestBase { path_parts: { /** - * ID for the snapshot lifecycle policy you want to create or update. + * The identifier for the snapshot lifecycle policy you want to create or update. */ policy_id: Name } diff --git a/specification/slm/start/StartSnapshotLifecycleManagementRequest.ts b/specification/slm/start/StartSnapshotLifecycleManagementRequest.ts index 1f0d8106ff..04612c9ee1 100644 --- a/specification/slm/start/StartSnapshotLifecycleManagementRequest.ts +++ b/specification/slm/start/StartSnapshotLifecycleManagementRequest.ts @@ -20,8 +20,12 @@ import { RequestBase } from '@_types/Base' /** + * Start snapshot lifecycle management. + * Snapshot lifecycle management (SLM) starts automatically when a cluster is formed. + * Manually starting SLM is necessary only if it has been stopped using the stop SLM API. * @rest_spec_name slm.start * @availability stack since=7.6.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage_slm */ export interface Request extends RequestBase {} diff --git a/specification/slm/stop/StopSnapshotLifecycleManagementRequest.ts b/specification/slm/stop/StopSnapshotLifecycleManagementRequest.ts index eb5e8ede10..32a9ea2062 100644 --- a/specification/slm/stop/StopSnapshotLifecycleManagementRequest.ts +++ b/specification/slm/stop/StopSnapshotLifecycleManagementRequest.ts @@ -20,6 +20,14 @@ import { RequestBase } from '@_types/Base' /** + * Stop snapshot lifecycle management. + * Stop all snapshot lifecycle management (SLM) operations and the SLM plugin. + * This API is useful when you are performing maintenance on a cluster and need to prevent SLM from performing any actions on your data streams or indices. + * Stopping SLM does not stop any snapshots that are in progress. + * You can manually trigger snapshots with the run snapshot lifecycle policy API even if SLM is stopped. + * + * The API returns a response as soon as the request is acknowledged, but the plugin might continue to run until in-progress operations complete and it can be safely stopped. + * Use the get snapshot lifecycle management status API to see if SLM is running. * @rest_spec_name slm.stop * @availability stack since=7.6.0 stability=stable * @availability serverless stability=stable visibility=private From b1b8b2fe8188b29a06f9e491e158f971f17356f4 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 16 Dec 2024 17:44:50 -0800 Subject: [PATCH 07/10] [DOCS] Edit searchable snapshot summaries (#3312) --- output/openapi/elasticsearch-openapi.json | 19 ++++--- output/schema/schema.json | 53 ++++++++++++++----- .../cache_stats/Request.ts | 3 ++ .../SearchableSnapshotsClearCacheRequest.ts | 4 ++ .../mount/SearchableSnapshotsMountRequest.ts | 6 +++ .../stats/SearchableSnapshotsStatsRequest.ts | 3 ++ 6 files changed, 69 insertions(+), 19 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 96e83e4d63..19a89be86a 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -27118,7 +27118,8 @@ "tags": [ "searchable_snapshots" ], - "summary": "Retrieve node-level cache statistics about searchable snapshots", + "summary": "Get cache statistics", + "description": "Get statistics about the shared cache for partially mounted indices.", "operationId": "searchable-snapshots-cache-stats", "parameters": [ { @@ -27138,7 +27139,8 @@ "tags": [ "searchable_snapshots" ], - "summary": "Retrieve node-level cache statistics about searchable snapshots", + "summary": "Get cache statistics", + "description": "Get statistics about the shared cache for partially mounted indices.", "operationId": "searchable-snapshots-cache-stats-1", "parameters": [ { @@ -27161,7 +27163,8 @@ "tags": [ "searchable_snapshots" ], - "summary": "Clear the cache of searchable snapshots", + "summary": "Clear the cache", + "description": "Clear indices and data streams from the shared cache for partially mounted indices.", "operationId": "searchable-snapshots-clear-cache", "parameters": [ { @@ -27193,7 +27196,8 @@ "tags": [ "searchable_snapshots" ], - "summary": "Clear the cache of searchable snapshots", + "summary": "Clear the cache", + "description": "Clear indices and data streams from the shared cache for partially mounted indices.", "operationId": "searchable-snapshots-clear-cache-1", "parameters": [ { @@ -27228,7 +27232,8 @@ "tags": [ "searchable_snapshots" ], - "summary": "Mount a snapshot as a searchable index", + "summary": "Mount a snapshot", + "description": "Mount a snapshot as a searchable snapshot index.\nDo not use this API for snapshots managed by index lifecycle management (ILM).\nManually mounting ILM-managed snapshots can interfere with ILM processes.", "operationId": "searchable-snapshots-mount", "parameters": [ { @@ -27345,7 +27350,7 @@ "tags": [ "searchable_snapshots" ], - "summary": "Retrieve shard-level statistics about searchable snapshots", + "summary": "Get searchable snapshot statistics", "operationId": "searchable-snapshots-stats", "parameters": [ { @@ -27365,7 +27370,7 @@ "tags": [ "searchable_snapshots" ], - "summary": "Retrieve shard-level statistics about searchable snapshots", + "summary": "Get searchable snapshot statistics", "operationId": "searchable-snapshots-stats-1", "parameters": [ { diff --git a/output/schema/schema.json b/output/schema/schema.json index 0ebda07466..17c16de508 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -15110,9 +15110,14 @@ "stability": "experimental" } }, - "description": "Retrieve node-level cache statistics about searchable snapshots.", + "description": "Get cache statistics.\nGet statistics about the shared cache for partially mounted indices.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/searchable-snapshots-apis.html", "name": "searchable_snapshots.cache_stats", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "searchable_snapshots.cache_stats" @@ -15147,9 +15152,17 @@ "stability": "experimental" } }, - "description": "Clear the cache of searchable snapshots.", + "description": "Clear the cache.\nClear indices and data streams from the shared cache for partially mounted indices.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/searchable-snapshots-apis.html", "name": "searchable_snapshots.clear_cache", + "privileges": { + "cluster": [ + "manage" + ], + "index": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "searchable_snapshots.clear_cache" @@ -15184,9 +15197,17 @@ "stability": "stable" } }, - "description": "Mount a snapshot as a searchable index.", + "description": "Mount a snapshot.\nMount a snapshot as a searchable snapshot index.\nDo not use this API for snapshots managed by index lifecycle management (ILM).\nManually mounting ILM-managed snapshots can interfere with ILM processes.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/searchable-snapshots-api-mount-snapshot.html", "name": "searchable_snapshots.mount", + "privileges": { + "cluster": [ + "manage" + ], + "index": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "searchable_snapshots.mount" @@ -15218,9 +15239,17 @@ "stability": "stable" } }, - "description": "Retrieve shard-level statistics about searchable snapshots.", + "description": "Get searchable snapshot statistics.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/searchable-snapshots-apis.html", "name": "searchable_snapshots.stats", + "privileges": { + "cluster": [ + "manage" + ], + "index": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "searchable_snapshots.stats" @@ -187765,7 +187794,7 @@ "body": { "kind": "no_body" }, - "description": "Retrieve node-level cache statistics about searchable snapshots.", + "description": "Get cache statistics.\nGet statistics about the shared cache for partially mounted indices.", "inherits": { "type": { "name": "RequestBase", @@ -187803,7 +187832,7 @@ } } ], - "specLocation": "searchable_snapshots/cache_stats/Request.ts#L24-L35" + "specLocation": "searchable_snapshots/cache_stats/Request.ts#L24-L38" }, { "kind": "response", @@ -187946,7 +187975,7 @@ "body": { "kind": "no_body" }, - "description": "Clear the cache of searchable snapshots.", + "description": "Clear the cache.\nClear indices and data streams from the shared cache for partially mounted indices.", "inherits": { "type": { "name": "RequestBase", @@ -188031,7 +188060,7 @@ } } ], - "specLocation": "searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts#L23-L38" + "specLocation": "searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts#L23-L42" }, { "kind": "response", @@ -188154,7 +188183,7 @@ } ] }, - "description": "Mount a snapshot as a searchable index.", + "description": "Mount a snapshot.\nMount a snapshot as a searchable snapshot index.\nDo not use this API for snapshots managed by index lifecycle management (ILM).\nManually mounting ILM-managed snapshots can interfere with ILM processes.", "inherits": { "type": { "name": "RequestBase", @@ -188232,7 +188261,7 @@ } } ], - "specLocation": "searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts#L26-L49" + "specLocation": "searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts#L26-L55" }, { "kind": "response", @@ -188266,7 +188295,7 @@ "body": { "kind": "no_body" }, - "description": "Retrieve shard-level statistics about searchable snapshots.", + "description": "Get searchable snapshot statistics.", "inherits": { "type": { "name": "RequestBase", @@ -188305,7 +188334,7 @@ } } ], - "specLocation": "searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts#L24-L35" + "specLocation": "searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts#L24-L38" }, { "kind": "response", diff --git a/specification/searchable_snapshots/cache_stats/Request.ts b/specification/searchable_snapshots/cache_stats/Request.ts index 9d482258d9..7ef9bc1781 100644 --- a/specification/searchable_snapshots/cache_stats/Request.ts +++ b/specification/searchable_snapshots/cache_stats/Request.ts @@ -22,8 +22,11 @@ import { NodeIds } from '@_types/common' import { Duration } from '@_types/Time' /** + * Get cache statistics. + * Get statistics about the shared cache for partially mounted indices. * @rest_spec_name searchable_snapshots.cache_stats * @availability stack since=7.13.0 stability=experimental + * @cluster_privileges manage */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts b/specification/searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts index 13300556a9..5c50a67828 100644 --- a/specification/searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts +++ b/specification/searchable_snapshots/clear_cache/SearchableSnapshotsClearCacheRequest.ts @@ -21,8 +21,12 @@ import { RequestBase } from '@_types/Base' import { ExpandWildcards, Indices } from '@_types/common' /** + * Clear the cache. + * Clear indices and data streams from the shared cache for partially mounted indices. * @rest_spec_name searchable_snapshots.clear_cache * @availability stack since=7.10.0 stability=experimental + * @cluster_privileges manage + * @index_privileges manage */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts b/specification/searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts index 9455ee41d9..fcc880e756 100644 --- a/specification/searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts +++ b/specification/searchable_snapshots/mount/SearchableSnapshotsMountRequest.ts @@ -24,8 +24,14 @@ import { IndexName, Name } from '@_types/common' import { Duration } from '@_types/Time' /** + * Mount a snapshot. + * Mount a snapshot as a searchable snapshot index. + * Do not use this API for snapshots managed by index lifecycle management (ILM). + * Manually mounting ILM-managed snapshots can interfere with ILM processes. * @rest_spec_name searchable_snapshots.mount * @availability stack since=7.10.0 stability=stable + * @cluster_privileges manage + * @index_privileges manage */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts b/specification/searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts index bdc4fdffa5..872a7c71c7 100644 --- a/specification/searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts +++ b/specification/searchable_snapshots/stats/SearchableSnapshotsStatsRequest.ts @@ -22,8 +22,11 @@ import { Indices } from '@_types/common' import { StatsLevel } from '../_types/stats' /** + * Get searchable snapshot statistics. * @rest_spec_name searchable_snapshots.stats * @availability stack since=7.10.0 stability=stable + * @cluster_privileges manage + * @index_privileges manage */ export interface Request extends RequestBase { path_parts: { From 2d37c01d26b17cc0cbeeb8633beb4f7a83b70bd1 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 16 Dec 2024 18:29:45 -0800 Subject: [PATCH 08/10] [DOCS] Edit snapshot and restore summaries and descriptions (#3314) Co-authored-by: Karen Metts <35154725+karenzone@users.noreply.github.com> --- output/openapi/elasticsearch-openapi.json | 68 ++++++--- output/schema/schema.json | 142 +++++++++++++----- specification/_doc_ids/table.csv | 4 + .../SnapshotCleanupRepositoryRequest.ts | 5 +- .../snapshot/clone/SnapshotCloneRequest.ts | 3 + .../snapshot/create/SnapshotCreateRequest.ts | 4 + .../SnapshotCreateRepositoryRequest.ts | 6 + .../snapshot/delete/SnapshotDeleteRequest.ts | 2 + .../SnapshotDeleteRepositoryRequest.ts | 4 + .../snapshot/get/SnapshotGetRequest.ts | 2 + .../SnapshotGetRepositoryRequest.ts | 2 + ...napshotRepositoryVerifyIntegrityRequest.ts | 29 ++++ .../restore/SnapshotRestoreRequest.ts | 20 +++ .../snapshot/status/SnapshotStatusRequest.ts | 12 ++ .../SnapshotVerifyRepositoryRequest.ts | 4 + 15 files changed, 253 insertions(+), 54 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 19a89be86a..ea68fe1207 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -31493,7 +31493,11 @@ "tags": [ "snapshot" ], - "summary": "Triggers the review of a snapshot repository’s contents and deletes any stale data not referenced by existing snapshots", + "summary": "Clean up the snapshot repository", + "description": "Trigger the review of the contents of a snapshot repository and delete any stale data not referenced by existing snapshots.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-register-repository.html#snapshots-repository-cleanup" + }, "operationId": "snapshot-cleanup-repository", "parameters": [ { @@ -31556,7 +31560,8 @@ "tags": [ "snapshot" ], - "summary": "Clones indices from one snapshot into another snapshot in the same repository", + "summary": "Clone a snapshot", + "description": "Clone part of all of a snapshot into another snapshot in the same repository.", "operationId": "snapshot-clone", "parameters": [ { @@ -31650,7 +31655,7 @@ "tags": [ "snapshot" ], - "summary": "Returns information about a snapshot", + "summary": "Get snapshot information", "operationId": "snapshot-get", "parameters": [ { @@ -31850,7 +31855,11 @@ "tags": [ "snapshot" ], - "summary": "Creates a snapshot in a repository", + "summary": "Create a snapshot", + "description": "Take a snapshot of a cluster or of data streams and indices.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-take-snapshot.html" + }, "operationId": "snapshot-create", "parameters": [ { @@ -31880,7 +31889,11 @@ "tags": [ "snapshot" ], - "summary": "Creates a snapshot in a repository", + "summary": "Create a snapshot", + "description": "Take a snapshot of a cluster or of data streams and indices.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-take-snapshot.html" + }, "operationId": "snapshot-create-1", "parameters": [ { @@ -31910,7 +31923,7 @@ "tags": [ "snapshot" ], - "summary": "Deletes one or more snapshots", + "summary": "Delete snapshots", "operationId": "snapshot-delete", "parameters": [ { @@ -31965,7 +31978,7 @@ "tags": [ "snapshot" ], - "summary": "Returns information about a repository", + "summary": "Get snapshot repository information", "operationId": "snapshot-get-repository-1", "parameters": [ { @@ -31989,7 +32002,11 @@ "tags": [ "snapshot" ], - "summary": "Creates a repository", + "summary": "Create or update a snapshot repository", + "description": "IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.\nTo register a snapshot repository, the cluster's global metadata must be writeable.\nEnsure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-register-repository.html" + }, "operationId": "snapshot-create-repository", "parameters": [ { @@ -32019,7 +32036,11 @@ "tags": [ "snapshot" ], - "summary": "Creates a repository", + "summary": "Create or update a snapshot repository", + "description": "IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.\nTo register a snapshot repository, the cluster's global metadata must be writeable.\nEnsure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-register-repository.html" + }, "operationId": "snapshot-create-repository-1", "parameters": [ { @@ -32049,7 +32070,8 @@ "tags": [ "snapshot" ], - "summary": "Deletes a repository", + "summary": "Delete snapshot repositories", + "description": "When a repository is unregistered, Elasticsearch removes only the reference to the location where the repository is storing the snapshots.\nThe snapshots themselves are left untouched and in place.", "operationId": "snapshot-delete-repository", "parameters": [ { @@ -32104,7 +32126,7 @@ "tags": [ "snapshot" ], - "summary": "Returns information about a repository", + "summary": "Get snapshot repository information", "operationId": "snapshot-get-repository", "parameters": [ { @@ -32127,7 +32149,8 @@ "tags": [ "snapshot" ], - "summary": "Verifies the integrity of the contents of a snapshot repository", + "summary": "Verify the repository integrity", + "description": "Verify the integrity of the contents of a snapshot repository.\n\nThis API enables you to perform a comprehensive check of the contents of a repository, looking for any anomalies in its data or metadata which might prevent you from restoring snapshots from the repository or which might cause future snapshot create or delete operations to fail.\n\nIf you suspect the integrity of the contents of one of your snapshot repositories, cease all write activity to this repository immediately, set its `read_only` option to `true`, and use this API to verify its integrity.\nUntil you do so:\n\n* It may not be possible to restore some snapshots from this repository.\n* Searchable snapshots may report errors when searched or may have unassigned shards.\n* Taking snapshots into this repository may fail or may appear to succeed but have created a snapshot which cannot be restored.\n* Deleting snapshots from this repository may fail or may appear to succeed but leave the underlying data on disk.\n* Continuing to write to the repository while it is in an invalid state may causing additional damage to its contents.\n\nIf the API finds any problems with the integrity of the contents of your repository, Elasticsearch will not be able to repair the damage.\nThe only way to bring the repository back into a fully working state after its contents have been damaged is by restoring its contents from a repository backup which was taken before the damage occurred.\nYou must also identify what caused the damage and take action to prevent it from happening again.\n\nIf you cannot restore a repository backup, register a new repository and use this for all future snapshot operations.\nIn some cases it may be possible to recover some of the contents of a damaged repository, either by restoring as many of its snapshots as needed and taking new snapshots of the restored data, or by using the reindex API to copy data from any searchable snapshots mounted from the damaged repository.\n\nAvoid all operations which write to the repository while the verify repository integrity API is running.\nIf something changes the repository contents while an integrity verification is running then Elasticsearch may incorrectly report having detected some anomalies in its contents due to the concurrent writes.\nIt may also incorrectly fail to report some anomalies that the concurrent writes prevented it from detecting.\n\nNOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions.\n\nNOTE: This API may not work correctly in a mixed-version cluster.", "operationId": "snapshot-repository-verify-integrity", "parameters": [ { @@ -32242,7 +32265,11 @@ "tags": [ "snapshot" ], - "summary": "Restores a snapshot", + "summary": "Restore a snapshot", + "description": "Restore a snapshot of a cluster or data streams and indices.\n\nYou can restore a snapshot only to a running cluster with an elected master node.\nThe snapshot repository must be registered and available to the cluster.\nThe snapshot and cluster versions must be compatible.\n\nTo restore a snapshot, the cluster's global metadata must be writable. Ensure there are't any cluster blocks that prevent writes. The restore operation ignores index blocks.\n\nBefore you restore a data stream, ensure the cluster contains a matching index template with data streams enabled. To check, use the index management feature in Kibana or the get index template API:\n\n```\nGET _index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream\n```\n\nIf no such template exists, you can create one or restore a cluster state that contains one. Without a matching index template, a data stream can't roll over or create backing indices.\n\nIf your snapshot contains data from App Search or Workplace Search, you must restore the Enterprise Search encryption key before you restore the snapshot.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-restore-snapshot.html" + }, "operationId": "snapshot-restore", "parameters": [ { @@ -32363,7 +32390,8 @@ "tags": [ "snapshot" ], - "summary": "Returns information about the status of a snapshot", + "summary": "Get the snapshot status", + "description": "Get a detailed description of the current state for each shard participating in the snapshot.\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "operationId": "snapshot-status", "parameters": [ { @@ -32386,7 +32414,8 @@ "tags": [ "snapshot" ], - "summary": "Returns information about the status of a snapshot", + "summary": "Get the snapshot status", + "description": "Get a detailed description of the current state for each shard participating in the snapshot.\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "operationId": "snapshot-status-1", "parameters": [ { @@ -32412,7 +32441,8 @@ "tags": [ "snapshot" ], - "summary": "Returns information about the status of a snapshot", + "summary": "Get the snapshot status", + "description": "Get a detailed description of the current state for each shard participating in the snapshot.\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "operationId": "snapshot-status-2", "parameters": [ { @@ -32441,7 +32471,11 @@ "tags": [ "snapshot" ], - "summary": "Verifies a repository", + "summary": "Verify a snapshot repository", + "description": "Check for common misconfigurations in a snapshot repository.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-register-repository.html#snapshots-repository-verification" + }, "operationId": "snapshot-verify-repository", "parameters": [ { diff --git a/output/schema/schema.json b/output/schema/schema.json index 17c16de508..0a1985d4a6 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -18245,9 +18245,16 @@ "stability": "stable" } }, - "description": "Triggers the review of a snapshot repository’s contents and deletes any stale data not referenced by existing snapshots.", + "description": "Clean up the snapshot repository.\nTrigger the review of the contents of a snapshot repository and delete any stale data not referenced by existing snapshots.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/clean-up-snapshot-repo-api.html", + "extDocId": "clean-up-snapshot-repo", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html#snapshots-repository-cleanup", "name": "snapshot.cleanup_repository", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "snapshot.cleanup_repository" @@ -18280,9 +18287,14 @@ "stability": "stable" } }, - "description": "Clones indices from one snapshot into another snapshot in the same repository.", + "description": "Clone a snapshot.\nClone part of all of a snapshot into another snapshot in the same repository.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", "name": "snapshot.clone", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "snapshot.clone" @@ -18318,9 +18330,16 @@ "stability": "stable" } }, - "description": "Creates a snapshot in a repository.", + "description": "Create a snapshot.\nTake a snapshot of a cluster or of data streams and indices.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", + "extDocId": "snapshot-create", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-take-snapshot.html", "name": "snapshot.create", + "privileges": { + "cluster": [ + "create_snapshot" + ] + }, "request": { "name": "Request", "namespace": "snapshot.create" @@ -18357,9 +18376,16 @@ "stability": "stable" } }, - "description": "Creates a repository.", + "description": "Create or update a snapshot repository.\nIMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.\nTo register a snapshot repository, the cluster's global metadata must be writeable.\nEnsure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", + "extDocId": "register-repository", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html", "name": "snapshot.create_repository", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "snapshot.create_repository" @@ -18395,9 +18421,14 @@ "stability": "stable" } }, - "description": "Deletes one or more snapshots.", + "description": "Delete snapshots.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", "name": "snapshot.delete", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "snapshot.delete" @@ -18430,9 +18461,14 @@ "stability": "stable" } }, - "description": "Deletes a repository.", + "description": "Delete snapshot repositories.\nWhen a repository is unregistered, Elasticsearch removes only the reference to the location where the repository is storing the snapshots.\nThe snapshots themselves are left untouched and in place.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", "name": "snapshot.delete_repository", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "snapshot.delete_repository" @@ -18465,9 +18501,14 @@ "stability": "stable" } }, - "description": "Returns information about a snapshot.", + "description": "Get snapshot information.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", "name": "snapshot.get", + "privileges": { + "cluster": [ + "monitor_snapshot" + ] + }, "request": { "name": "Request", "namespace": "snapshot.get" @@ -18500,9 +18541,14 @@ "stability": "stable" } }, - "description": "Returns information about a repository.", + "description": "Get snapshot repository information.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", "name": "snapshot.get_repository", + "privileges": { + "cluster": [ + "monitor_snapshot" + ] + }, "request": { "name": "Request", "namespace": "snapshot.get_repository" @@ -18563,9 +18609,14 @@ "visibility": "private" } }, - "description": "Verifies the integrity of the contents of a snapshot repository", + "description": "Verify the repository integrity.\nVerify the integrity of the contents of a snapshot repository.\n\nThis API enables you to perform a comprehensive check of the contents of a repository, looking for any anomalies in its data or metadata which might prevent you from restoring snapshots from the repository or which might cause future snapshot create or delete operations to fail.\n\nIf you suspect the integrity of the contents of one of your snapshot repositories, cease all write activity to this repository immediately, set its `read_only` option to `true`, and use this API to verify its integrity.\nUntil you do so:\n\n* It may not be possible to restore some snapshots from this repository.\n* Searchable snapshots may report errors when searched or may have unassigned shards.\n* Taking snapshots into this repository may fail or may appear to succeed but have created a snapshot which cannot be restored.\n* Deleting snapshots from this repository may fail or may appear to succeed but leave the underlying data on disk.\n* Continuing to write to the repository while it is in an invalid state may causing additional damage to its contents.\n\nIf the API finds any problems with the integrity of the contents of your repository, Elasticsearch will not be able to repair the damage.\nThe only way to bring the repository back into a fully working state after its contents have been damaged is by restoring its contents from a repository backup which was taken before the damage occurred.\nYou must also identify what caused the damage and take action to prevent it from happening again.\n\nIf you cannot restore a repository backup, register a new repository and use this for all future snapshot operations.\nIn some cases it may be possible to recover some of the contents of a damaged repository, either by restoring as many of its snapshots as needed and taking new snapshots of the restored data, or by using the reindex API to copy data from any searchable snapshots mounted from the damaged repository.\n\nAvoid all operations which write to the repository while the verify repository integrity API is running.\nIf something changes the repository contents while an integrity verification is running then Elasticsearch may incorrectly report having detected some anomalies in its contents due to the concurrent writes.\nIt may also incorrectly fail to report some anomalies that the concurrent writes prevented it from detecting.\n\nNOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions.\n\nNOTE: This API may not work correctly in a mixed-version cluster.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", "name": "snapshot.repository_verify_integrity", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "snapshot.repository_verify_integrity" @@ -18598,9 +18649,16 @@ "stability": "stable" } }, - "description": "Restores a snapshot.", + "description": "Restore a snapshot.\nRestore a snapshot of a cluster or data streams and indices.\n\nYou can restore a snapshot only to a running cluster with an elected master node.\nThe snapshot repository must be registered and available to the cluster.\nThe snapshot and cluster versions must be compatible.\n\nTo restore a snapshot, the cluster's global metadata must be writable. Ensure there are't any cluster blocks that prevent writes. The restore operation ignores index blocks.\n\nBefore you restore a data stream, ensure the cluster contains a matching index template with data streams enabled. To check, use the index management feature in Kibana or the get index template API:\n\n```\nGET _index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream\n```\n\nIf no such template exists, you can create one or restore a cluster state that contains one. Without a matching index template, a data stream can't roll over or create backing indices.\n\nIf your snapshot contains data from App Search or Workplace Search, you must restore the Enterprise Search encryption key before you restore the snapshot.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", + "extDocId": "restore-snapshot", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-restore-snapshot.html", "name": "snapshot.restore", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "snapshot.restore" @@ -18636,9 +18694,14 @@ "stability": "stable" } }, - "description": "Returns information about the status of a snapshot.", + "description": "Get the snapshot status.\nGet a detailed description of the current state for each shard participating in the snapshot.\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", "name": "snapshot.status", + "privileges": { + "cluster": [ + "monitor_snapshot" + ] + }, "request": { "name": "Request", "namespace": "snapshot.status" @@ -18683,9 +18746,16 @@ "stability": "stable" } }, - "description": "Verifies a repository.", + "description": "Verify a snapshot repository.\nCheck for common misconfigurations in a snapshot repository.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", + "extDocId": "verify-repository", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html#snapshots-repository-verification", "name": "snapshot.verify_repository", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "snapshot.verify_repository" @@ -203631,7 +203701,7 @@ "body": { "kind": "no_body" }, - "description": "Triggers the review of a snapshot repository’s contents and deletes any stale data not referenced by existing snapshots.", + "description": "Clean up the snapshot repository.\nTrigger the review of the contents of a snapshot repository and delete any stale data not referenced by existing snapshots.", "inherits": { "type": { "name": "RequestBase", @@ -203685,7 +203755,7 @@ } } ], - "specLocation": "snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts#L24-L49" + "specLocation": "snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts#L24-L52" }, { "kind": "response", @@ -203733,7 +203803,7 @@ } ] }, - "description": "Clones indices from one snapshot into another snapshot in the same repository.", + "description": "Clone a snapshot.\nClone part of all of a snapshot into another snapshot in the same repository.", "inherits": { "type": { "name": "RequestBase", @@ -203807,7 +203877,7 @@ } } ], - "specLocation": "snapshot/clone/SnapshotCloneRequest.ts#L24-L42" + "specLocation": "snapshot/clone/SnapshotCloneRequest.ts#L24-L45" }, { "kind": "response", @@ -203915,7 +203985,7 @@ } ] }, - "description": "Creates a snapshot in a repository.", + "description": "Create a snapshot.\nTake a snapshot of a cluster or of data streams and indices.", "inherits": { "type": { "name": "RequestBase", @@ -203980,7 +204050,7 @@ } } ], - "specLocation": "snapshot/create/SnapshotCreateRequest.ts#L24-L81" + "specLocation": "snapshot/create/SnapshotCreateRequest.ts#L24-L85" }, { "kind": "response", @@ -204041,7 +204111,7 @@ } } }, - "description": "Creates a repository.", + "description": "Create or update a snapshot repository.\nIMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.\nTo register a snapshot repository, the cluster's global metadata must be writeable.\nEnsure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.", "inherits": { "type": { "name": "RequestBase", @@ -204105,7 +204175,7 @@ } } ], - "specLocation": "snapshot/create_repository/SnapshotCreateRepositoryRequest.ts#L25-L42" + "specLocation": "snapshot/create_repository/SnapshotCreateRepositoryRequest.ts#L25-L48" }, { "kind": "response", @@ -204133,7 +204203,7 @@ "body": { "kind": "no_body" }, - "description": "Deletes one or more snapshots.", + "description": "Delete snapshots.", "inherits": { "type": { "name": "RequestBase", @@ -204184,7 +204254,7 @@ } } ], - "specLocation": "snapshot/delete/SnapshotDeleteRequest.ts#L24-L37" + "specLocation": "snapshot/delete/SnapshotDeleteRequest.ts#L24-L39" }, { "kind": "response", @@ -204212,7 +204282,7 @@ "body": { "kind": "no_body" }, - "description": "Deletes a repository.", + "description": "Delete snapshot repositories.\nWhen a repository is unregistered, Elasticsearch removes only the reference to the location where the repository is storing the snapshots.\nThe snapshots themselves are left untouched and in place.", "inherits": { "type": { "name": "RequestBase", @@ -204264,7 +204334,7 @@ } } ], - "specLocation": "snapshot/delete_repository/SnapshotDeleteRepositoryRequest.ts#L24-L38" + "specLocation": "snapshot/delete_repository/SnapshotDeleteRepositoryRequest.ts#L24-L42" }, { "kind": "response", @@ -204292,7 +204362,7 @@ "body": { "kind": "no_body" }, - "description": "Returns information about a snapshot.", + "description": "Get snapshot information.", "inherits": { "type": { "name": "RequestBase", @@ -204551,7 +204621,7 @@ } } ], - "specLocation": "snapshot/get/SnapshotGetRequest.ts#L27-L127" + "specLocation": "snapshot/get/SnapshotGetRequest.ts#L27-L129" }, { "kind": "response", @@ -204684,7 +204754,7 @@ "body": { "kind": "no_body" }, - "description": "Returns information about a repository.", + "description": "Get snapshot repository information.", "inherits": { "type": { "name": "RequestBase", @@ -204736,7 +204806,7 @@ } } ], - "specLocation": "snapshot/get_repository/SnapshotGetRepositoryRequest.ts#L24-L38" + "specLocation": "snapshot/get_repository/SnapshotGetRepositoryRequest.ts#L24-L40" }, { "kind": "response", @@ -204775,7 +204845,7 @@ "body": { "kind": "no_body" }, - "description": "Verifies the integrity of the contents of a snapshot repository", + "description": "Verify the repository integrity.\nVerify the integrity of the contents of a snapshot repository.\n\nThis API enables you to perform a comprehensive check of the contents of a repository, looking for any anomalies in its data or metadata which might prevent you from restoring snapshots from the repository or which might cause future snapshot create or delete operations to fail.\n\nIf you suspect the integrity of the contents of one of your snapshot repositories, cease all write activity to this repository immediately, set its `read_only` option to `true`, and use this API to verify its integrity.\nUntil you do so:\n\n* It may not be possible to restore some snapshots from this repository.\n* Searchable snapshots may report errors when searched or may have unassigned shards.\n* Taking snapshots into this repository may fail or may appear to succeed but have created a snapshot which cannot be restored.\n* Deleting snapshots from this repository may fail or may appear to succeed but leave the underlying data on disk.\n* Continuing to write to the repository while it is in an invalid state may causing additional damage to its contents.\n\nIf the API finds any problems with the integrity of the contents of your repository, Elasticsearch will not be able to repair the damage.\nThe only way to bring the repository back into a fully working state after its contents have been damaged is by restoring its contents from a repository backup which was taken before the damage occurred.\nYou must also identify what caused the damage and take action to prevent it from happening again.\n\nIf you cannot restore a repository backup, register a new repository and use this for all future snapshot operations.\nIn some cases it may be possible to recover some of the contents of a damaged repository, either by restoring as many of its snapshots as needed and taking new snapshots of the restored data, or by using the reindex API to copy data from any searchable snapshots mounted from the damaged repository.\n\nAvoid all operations which write to the repository while the verify repository integrity API is running.\nIf something changes the repository contents while an integrity verification is running then Elasticsearch may incorrectly report having detected some anomalies in its contents due to the concurrent writes.\nIt may also incorrectly fail to report some anomalies that the concurrent writes prevented it from detecting.\n\nNOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions.\n\nNOTE: This API may not work correctly in a mixed-version cluster.", "inherits": { "type": { "name": "RequestBase", @@ -204899,7 +204969,7 @@ } } ], - "specLocation": "snapshot/repository_verify_integrity/SnapshotRepositoryVerifyIntegrityRequest.ts#L24-L43" + "specLocation": "snapshot/repository_verify_integrity/SnapshotRepositoryVerifyIntegrityRequest.ts#L24-L72" }, { "kind": "response", @@ -205041,7 +205111,7 @@ } ] }, - "description": "Restores a snapshot.", + "description": "Restore a snapshot.\nRestore a snapshot of a cluster or data streams and indices.\n\nYou can restore a snapshot only to a running cluster with an elected master node.\nThe snapshot repository must be registered and available to the cluster.\nThe snapshot and cluster versions must be compatible.\n\nTo restore a snapshot, the cluster's global metadata must be writable. Ensure there are't any cluster blocks that prevent writes. The restore operation ignores index blocks.\n\nBefore you restore a data stream, ensure the cluster contains a matching index template with data streams enabled. To check, use the index management feature in Kibana or the get index template API:\n\n```\nGET _index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream\n```\n\nIf no such template exists, you can create one or restore a cluster state that contains one. Without a matching index template, a data stream can't roll over or create backing indices.\n\nIf your snapshot contains data from App Search or Workplace Search, you must restore the Enterprise Search encryption key before you restore the snapshot.", "inherits": { "type": { "name": "RequestBase", @@ -205104,7 +205174,7 @@ } } ], - "specLocation": "snapshot/restore/SnapshotRestoreRequest.ts#L25-L51" + "specLocation": "snapshot/restore/SnapshotRestoreRequest.ts#L25-L71" }, { "kind": "response", @@ -205195,7 +205265,7 @@ "body": { "kind": "no_body" }, - "description": "Returns information about the status of a snapshot.", + "description": "Get the snapshot status.\nGet a detailed description of the current state for each shard participating in the snapshot.\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "inherits": { "type": { "name": "RequestBase", @@ -205258,7 +205328,7 @@ } } ], - "specLocation": "snapshot/status/SnapshotStatusRequest.ts#L24-L38" + "specLocation": "snapshot/status/SnapshotStatusRequest.ts#L24-L50" }, { "kind": "response", @@ -205316,7 +205386,7 @@ "body": { "kind": "no_body" }, - "description": "Verifies a repository.", + "description": "Verify a snapshot repository.\nCheck for common misconfigurations in a snapshot repository.", "inherits": { "type": { "name": "RequestBase", @@ -205368,7 +205438,7 @@ } } ], - "specLocation": "snapshot/verify_repository/SnapshotVerifyRepositoryRequest.ts#L24-L38" + "specLocation": "snapshot/verify_repository/SnapshotVerifyRepositoryRequest.ts#L24-L42" }, { "kind": "response", diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 1e7fac6559..16601f3352 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -61,6 +61,7 @@ ccr-put-auto-follow-pattern,https://www.elastic.co/guide/en/elasticsearch/refere ccr-put-follow,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ccr-put-follow.html ccr-resume-auto-follow-pattern,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ccr-resume-auto-follow-pattern.html ccs-network-delays,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html#ccs-network-delays +clean-up-snapshot-repo,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html#snapshots-repository-cleanup clean-up-snapshot-repo-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clean-up-snapshot-repo-api.html clear-repositories-metering-archive-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-repositories-metering-archive-api.html clear-scroll-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-scroll-api.html @@ -428,6 +429,7 @@ query-rule,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sear realtime,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#realtime redact-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/redact-processor.html regexp-syntax,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/regexp-syntax.html +register-repository,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html registered-domain-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/registered-domain-processor.html remove-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/remove-processor.html remote-clusters-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/remote-clusters-api-key.html @@ -435,6 +437,7 @@ rename-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch reroute-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/reroute-processor.html render-search-template-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/render-search-template-api.html reset-transform,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/reset-transform.html +restore-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-restore-snapshot.html rollup-delete-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-delete-job.html rollup-get-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-get-job.html rollup-get-rollup-caps,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-get-rollup-caps.html @@ -640,6 +643,7 @@ urldecode-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{bra usage-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/usage-api.html user-agent-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/user-agent-processor.html user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/user-profile.html +verify-repository,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html#snapshots-repository-verification voting-config-exclusions,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/voting-config-exclusions.html watcher-api-ack-watch,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-ack-watch.html watcher-api-activate-watch,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-activate-watch.html diff --git a/specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts b/specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts index 7b69025470..4ad18c81e0 100644 --- a/specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts +++ b/specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts @@ -22,10 +22,13 @@ import { Name } from '@_types/common' import { Duration } from '@_types/Time' /** - * Triggers the review of a snapshot repository’s contents and deletes any stale data not referenced by existing snapshots. + * Clean up the snapshot repository. + * Trigger the review of the contents of a snapshot repository and delete any stale data not referenced by existing snapshots. * @rest_spec_name snapshot.cleanup_repository * @availability stack since=7.4.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage + * @ext_doc_id clean-up-snapshot-repo */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/snapshot/clone/SnapshotCloneRequest.ts b/specification/snapshot/clone/SnapshotCloneRequest.ts index 8cf780a4e0..4141fb04b6 100644 --- a/specification/snapshot/clone/SnapshotCloneRequest.ts +++ b/specification/snapshot/clone/SnapshotCloneRequest.ts @@ -22,9 +22,12 @@ import { Name } from '@_types/common' import { Duration } from '@_types/Time' /** + * Clone a snapshot. + * Clone part of all of a snapshot into another snapshot in the same repository. * @rest_spec_name snapshot.clone * @availability stack since=7.10.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/snapshot/create/SnapshotCreateRequest.ts b/specification/snapshot/create/SnapshotCreateRequest.ts index 7fff18df5d..86ae28ecc7 100644 --- a/specification/snapshot/create/SnapshotCreateRequest.ts +++ b/specification/snapshot/create/SnapshotCreateRequest.ts @@ -22,9 +22,13 @@ import { Indices, Metadata, Name } from '@_types/common' import { Duration } from '@_types/Time' /** + * Create a snapshot. + * Take a snapshot of a cluster or of data streams and indices. * @rest_spec_name snapshot.create * @availability stack since=0.0.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges create_snapshot + * @ext_doc_id snapshot-create */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/snapshot/create_repository/SnapshotCreateRepositoryRequest.ts b/specification/snapshot/create_repository/SnapshotCreateRepositoryRequest.ts index 93e836180e..b5eb7782bd 100644 --- a/specification/snapshot/create_repository/SnapshotCreateRepositoryRequest.ts +++ b/specification/snapshot/create_repository/SnapshotCreateRepositoryRequest.ts @@ -23,9 +23,15 @@ import { Name } from '@_types/common' import { Duration } from '@_types/Time' /** + * Create or update a snapshot repository. + * IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters. + * To register a snapshot repository, the cluster's global metadata must be writeable. + * Ensure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access. * @rest_spec_name snapshot.create_repository * @availability stack since=0.0.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage + * @ext_doc_id register-repository */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/snapshot/delete/SnapshotDeleteRequest.ts b/specification/snapshot/delete/SnapshotDeleteRequest.ts index e9194337f4..4ba1ed9fc9 100644 --- a/specification/snapshot/delete/SnapshotDeleteRequest.ts +++ b/specification/snapshot/delete/SnapshotDeleteRequest.ts @@ -22,9 +22,11 @@ import { Name } from '@_types/common' import { Duration } from '@_types/Time' /** + * Delete snapshots. * @rest_spec_name snapshot.delete * @availability stack stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/snapshot/delete_repository/SnapshotDeleteRepositoryRequest.ts b/specification/snapshot/delete_repository/SnapshotDeleteRepositoryRequest.ts index 84ff3aea05..b5e274a232 100644 --- a/specification/snapshot/delete_repository/SnapshotDeleteRepositoryRequest.ts +++ b/specification/snapshot/delete_repository/SnapshotDeleteRepositoryRequest.ts @@ -22,9 +22,13 @@ import { Names } from '@_types/common' import { Duration } from '@_types/Time' /** + * Delete snapshot repositories. + * When a repository is unregistered, Elasticsearch removes only the reference to the location where the repository is storing the snapshots. + * The snapshots themselves are left untouched and in place. * @rest_spec_name snapshot.delete_repository * @availability stack since=0.0.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/snapshot/get/SnapshotGetRequest.ts b/specification/snapshot/get/SnapshotGetRequest.ts index 0ecdcd1281..fd096bb030 100644 --- a/specification/snapshot/get/SnapshotGetRequest.ts +++ b/specification/snapshot/get/SnapshotGetRequest.ts @@ -25,9 +25,11 @@ import { SortOrder } from '@_types/sort' import { Duration } from '@_types/Time' /** + * Get snapshot information. * @rest_spec_name snapshot.get * @availability stack since=0.0.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges monitor_snapshot */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/snapshot/get_repository/SnapshotGetRepositoryRequest.ts b/specification/snapshot/get_repository/SnapshotGetRepositoryRequest.ts index b620870113..4d42c890c8 100644 --- a/specification/snapshot/get_repository/SnapshotGetRepositoryRequest.ts +++ b/specification/snapshot/get_repository/SnapshotGetRepositoryRequest.ts @@ -22,9 +22,11 @@ import { Names } from '@_types/common' import { Duration } from '@_types/Time' /** + * Get snapshot repository information. * @rest_spec_name snapshot.get_repository * @availability stack since=0.0.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges monitor_snapshot */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/snapshot/repository_verify_integrity/SnapshotRepositoryVerifyIntegrityRequest.ts b/specification/snapshot/repository_verify_integrity/SnapshotRepositoryVerifyIntegrityRequest.ts index 2c77b1476a..5e493327d4 100644 --- a/specification/snapshot/repository_verify_integrity/SnapshotRepositoryVerifyIntegrityRequest.ts +++ b/specification/snapshot/repository_verify_integrity/SnapshotRepositoryVerifyIntegrityRequest.ts @@ -22,8 +22,37 @@ import { Names } from '@_types/common' import { integer } from '@_types/Numeric' /** + * Verify the repository integrity. + * Verify the integrity of the contents of a snapshot repository. + * + * This API enables you to perform a comprehensive check of the contents of a repository, looking for any anomalies in its data or metadata which might prevent you from restoring snapshots from the repository or which might cause future snapshot create or delete operations to fail. + * + * If you suspect the integrity of the contents of one of your snapshot repositories, cease all write activity to this repository immediately, set its `read_only` option to `true`, and use this API to verify its integrity. + * Until you do so: + * + * * It may not be possible to restore some snapshots from this repository. + * * Searchable snapshots may report errors when searched or may have unassigned shards. + * * Taking snapshots into this repository may fail or may appear to succeed but have created a snapshot which cannot be restored. + * * Deleting snapshots from this repository may fail or may appear to succeed but leave the underlying data on disk. + * * Continuing to write to the repository while it is in an invalid state may causing additional damage to its contents. + * + * If the API finds any problems with the integrity of the contents of your repository, Elasticsearch will not be able to repair the damage. + * The only way to bring the repository back into a fully working state after its contents have been damaged is by restoring its contents from a repository backup which was taken before the damage occurred. + * You must also identify what caused the damage and take action to prevent it from happening again. + * + * If you cannot restore a repository backup, register a new repository and use this for all future snapshot operations. + * In some cases it may be possible to recover some of the contents of a damaged repository, either by restoring as many of its snapshots as needed and taking new snapshots of the restored data, or by using the reindex API to copy data from any searchable snapshots mounted from the damaged repository. + * + * Avoid all operations which write to the repository while the verify repository integrity API is running. + * If something changes the repository contents while an integrity verification is running then Elasticsearch may incorrectly report having detected some anomalies in its contents due to the concurrent writes. + * It may also incorrectly fail to report some anomalies that the concurrent writes prevented it from detecting. + * + * NOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions. + * + * NOTE: This API may not work correctly in a mixed-version cluster. * @rest_spec_name snapshot.repository_verify_integrity * @availability stack since=8.16.0 stability=experimental visibility=private + * @cluster_privileges manage */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/snapshot/restore/SnapshotRestoreRequest.ts b/specification/snapshot/restore/SnapshotRestoreRequest.ts index bedf603476..a982b26fe6 100644 --- a/specification/snapshot/restore/SnapshotRestoreRequest.ts +++ b/specification/snapshot/restore/SnapshotRestoreRequest.ts @@ -23,9 +23,29 @@ import { Indices, Name } from '@_types/common' import { Duration } from '@_types/Time' /** + * Restore a snapshot. + * Restore a snapshot of a cluster or data streams and indices. + * + * You can restore a snapshot only to a running cluster with an elected master node. + * The snapshot repository must be registered and available to the cluster. + * The snapshot and cluster versions must be compatible. + * + * To restore a snapshot, the cluster's global metadata must be writable. Ensure there are't any cluster blocks that prevent writes. The restore operation ignores index blocks. + * + * Before you restore a data stream, ensure the cluster contains a matching index template with data streams enabled. To check, use the index management feature in Kibana or the get index template API: + * + * ``` + * GET _index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream + * ``` + * + * If no such template exists, you can create one or restore a cluster state that contains one. Without a matching index template, a data stream can't roll over or create backing indices. + * + * If your snapshot contains data from App Search or Workplace Search, you must restore the Enterprise Search encryption key before you restore the snapshot. * @rest_spec_name snapshot.restore * @availability stack since=0.0.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage + * @ext_doc_id restore-snapshot */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/snapshot/status/SnapshotStatusRequest.ts b/specification/snapshot/status/SnapshotStatusRequest.ts index 747f5bd2cb..44a7f74489 100644 --- a/specification/snapshot/status/SnapshotStatusRequest.ts +++ b/specification/snapshot/status/SnapshotStatusRequest.ts @@ -22,9 +22,21 @@ import { Name, Names } from '@_types/common' import { Duration } from '@_types/Time' /** + * Get the snapshot status. + * Get a detailed description of the current state for each shard participating in the snapshot. + * Note that this API should be used only to obtain detailed shard-level information for ongoing snapshots. + * If this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API. + * + * WARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive. + * The API requires a read from the repository for each shard in each snapshot. + * For example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards). + * + * Depending on the latency of your storage, such requests can take an extremely long time to return results. + * These requests can also tax machine resources and, when using cloud storage, incur high processing costs. * @rest_spec_name snapshot.status * @availability stack since=7.8.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges monitor_snapshot */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/snapshot/verify_repository/SnapshotVerifyRepositoryRequest.ts b/specification/snapshot/verify_repository/SnapshotVerifyRepositoryRequest.ts index ec97297dc9..951a55bb5a 100644 --- a/specification/snapshot/verify_repository/SnapshotVerifyRepositoryRequest.ts +++ b/specification/snapshot/verify_repository/SnapshotVerifyRepositoryRequest.ts @@ -22,9 +22,13 @@ import { Name } from '@_types/common' import { Duration } from '@_types/Time' /** + * Verify a snapshot repository. + * Check for common misconfigurations in a snapshot repository. * @rest_spec_name snapshot.verify_repository * @availability stack since=0.0.0 stability=stable * @availability serverless stability=stable visibility=private + * @cluster_privileges manage + * @ext_doc_id verify-repository */ export interface Request extends RequestBase { path_parts: { From dd538c9ba2761afd3a0d3590351752269dfe273e Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 16 Dec 2024 18:31:53 -0800 Subject: [PATCH 09/10] [OpenAPI] Edits Logstash pipeline APIs (#3073) --- output/openapi/elasticsearch-openapi.json | 57 +++++++++----- .../elasticsearch-serverless-openapi.json | 57 +++++++++----- output/schema/schema.json | 76 ++++++++++--------- output/typescript/types.ts | 4 +- specification/_doc_ids/table.csv | 1 + specification/logstash/_types/Pipeline.ts | 31 ++++---- .../LogstashDeletePipelineRequest.ts | 7 +- .../LogstashGetPipelineRequest.ts | 7 +- .../LogstashPutPipelineRequest.ts | 9 ++- 9 files changed, 152 insertions(+), 97 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index ea68fe1207..c05c51ec01 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -16180,7 +16180,11 @@ "tags": [ "logstash" ], - "summary": "Retrieves pipelines used for Logstash Central Management", + "summary": "Get Logstash pipelines", + "description": "Get pipelines that are used for Logstash Central Management.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/logstash/current/logstash-centralized-pipeline-management.html" + }, "operationId": "logstash-get-pipeline-1", "parameters": [ { @@ -16198,13 +16202,17 @@ "tags": [ "logstash" ], - "summary": "Creates or updates a pipeline used for Logstash Central Management", + "summary": "Create or update a Logstash pipeline", + "description": "Create a pipeline that is used for Logstash Central Management.\nIf the specified pipeline exists, it is replaced.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/logstash/current/logstash-centralized-pipeline-management.html" + }, "operationId": "logstash-put-pipeline", "parameters": [ { "in": "path", "name": "id", - "description": "Identifier for the pipeline.", + "description": "An identifier for the pipeline.", "required": true, "deprecated": false, "schema": { @@ -16237,13 +16245,17 @@ "tags": [ "logstash" ], - "summary": "Deletes a pipeline used for Logstash Central Management", + "summary": "Delete a Logstash pipeline", + "description": "Delete a pipeline that is used for Logstash Central Management.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/logstash/current/logstash-centralized-pipeline-management.html" + }, "operationId": "logstash-delete-pipeline", "parameters": [ { "in": "path", "name": "id", - "description": "Identifier for the pipeline.", + "description": "An identifier for the pipeline.", "required": true, "deprecated": false, "schema": { @@ -16268,7 +16280,11 @@ "tags": [ "logstash" ], - "summary": "Retrieves pipelines used for Logstash Central Management", + "summary": "Get Logstash pipelines", + "description": "Get pipelines that are used for Logstash Central Management.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/logstash/current/logstash-centralized-pipeline-management.html" + }, "operationId": "logstash-get-pipeline", "responses": { "200": { @@ -72388,34 +72404,37 @@ "type": "object", "properties": { "description": { - "description": "Description of the pipeline.\nThis description is not used by Elasticsearch or Logstash.", + "description": "A description of the pipeline.\nThis description is not used by Elasticsearch or Logstash.", "type": "string" }, "last_modified": { "$ref": "#/components/schemas/_types:DateTime" }, - "pipeline_metadata": { - "$ref": "#/components/schemas/logstash._types:PipelineMetadata" - }, - "username": { - "description": "User who last updated the pipeline.", - "type": "string" - }, "pipeline": { - "description": "Configuration for the pipeline.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/logstash/current/configuration-file-structure.html" + }, + "description": "The configuration for the pipeline.", "type": "string" }, + "pipeline_metadata": { + "$ref": "#/components/schemas/logstash._types:PipelineMetadata" + }, "pipeline_settings": { "$ref": "#/components/schemas/logstash._types:PipelineSettings" + }, + "username": { + "description": "The user who last updated the pipeline.", + "type": "string" } }, "required": [ "description", "last_modified", - "pipeline_metadata", - "username", "pipeline", - "pipeline_settings" + "pipeline_metadata", + "pipeline_settings", + "username" ] }, "logstash._types:PipelineMetadata": { @@ -98322,7 +98341,7 @@ "logstash.get_pipeline#id": { "in": "path", "name": "id", - "description": "Comma-separated list of pipeline identifiers.", + "description": "A comma-separated list of pipeline identifiers.", "required": true, "deprecated": false, "schema": { diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index 7e639ab6c6..d6cc466caa 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -9235,7 +9235,11 @@ "tags": [ "logstash" ], - "summary": "Retrieves pipelines used for Logstash Central Management", + "summary": "Get Logstash pipelines", + "description": "Get pipelines that are used for Logstash Central Management.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/logstash/current/logstash-centralized-pipeline-management.html" + }, "operationId": "logstash-get-pipeline-1", "parameters": [ { @@ -9253,13 +9257,17 @@ "tags": [ "logstash" ], - "summary": "Creates or updates a pipeline used for Logstash Central Management", + "summary": "Create or update a Logstash pipeline", + "description": "Create a pipeline that is used for Logstash Central Management.\nIf the specified pipeline exists, it is replaced.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/logstash/current/logstash-centralized-pipeline-management.html" + }, "operationId": "logstash-put-pipeline", "parameters": [ { "in": "path", "name": "id", - "description": "Identifier for the pipeline.", + "description": "An identifier for the pipeline.", "required": true, "deprecated": false, "schema": { @@ -9292,13 +9300,17 @@ "tags": [ "logstash" ], - "summary": "Deletes a pipeline used for Logstash Central Management", + "summary": "Delete a Logstash pipeline", + "description": "Delete a pipeline that is used for Logstash Central Management.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/logstash/current/logstash-centralized-pipeline-management.html" + }, "operationId": "logstash-delete-pipeline", "parameters": [ { "in": "path", "name": "id", - "description": "Identifier for the pipeline.", + "description": "An identifier for the pipeline.", "required": true, "deprecated": false, "schema": { @@ -9323,7 +9335,11 @@ "tags": [ "logstash" ], - "summary": "Retrieves pipelines used for Logstash Central Management", + "summary": "Get Logstash pipelines", + "description": "Get pipelines that are used for Logstash Central Management.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/logstash/current/logstash-centralized-pipeline-management.html" + }, "operationId": "logstash-get-pipeline", "responses": { "200": { @@ -47991,34 +48007,37 @@ "type": "object", "properties": { "description": { - "description": "Description of the pipeline.\nThis description is not used by Elasticsearch or Logstash.", + "description": "A description of the pipeline.\nThis description is not used by Elasticsearch or Logstash.", "type": "string" }, "last_modified": { "$ref": "#/components/schemas/_types:DateTime" }, - "pipeline_metadata": { - "$ref": "#/components/schemas/logstash._types:PipelineMetadata" - }, - "username": { - "description": "User who last updated the pipeline.", - "type": "string" - }, "pipeline": { - "description": "Configuration for the pipeline.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/logstash/current/configuration-file-structure.html" + }, + "description": "The configuration for the pipeline.", "type": "string" }, + "pipeline_metadata": { + "$ref": "#/components/schemas/logstash._types:PipelineMetadata" + }, "pipeline_settings": { "$ref": "#/components/schemas/logstash._types:PipelineSettings" + }, + "username": { + "description": "The user who last updated the pipeline.", + "type": "string" } }, "required": [ "description", "last_modified", - "pipeline_metadata", - "username", "pipeline", - "pipeline_settings" + "pipeline_metadata", + "pipeline_settings", + "username" ] }, "logstash._types:PipelineMetadata": { @@ -60098,7 +60117,7 @@ "logstash.get_pipeline#id": { "in": "path", "name": "id", - "description": "Comma-separated list of pipeline identifiers.", + "description": "A comma-separated list of pipeline identifiers.", "required": true, "deprecated": false, "schema": { diff --git a/output/schema/schema.json b/output/schema/schema.json index 0a1985d4a6..ab3801981e 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -9369,8 +9369,10 @@ "stability": "stable" } }, - "description": "Deletes a pipeline used for Logstash Central Management.", + "description": "Delete a Logstash pipeline.\n\nDelete a pipeline that is used for Logstash Central Management.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/logstash-api-delete-pipeline.html", + "extDocId": "logstash-centralized-pipeline-management", + "extDocUrl": "https://www.elastic.co/guide/en/logstash/{branch}/logstash-centralized-pipeline-management.html", "name": "logstash.delete_pipeline", "privileges": { "cluster": [ @@ -9409,8 +9411,10 @@ "stability": "stable" } }, - "description": "Retrieves pipelines used for Logstash Central Management.", + "description": "Get Logstash pipelines.\n\nGet pipelines that are used for Logstash Central Management.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/logstash-api-get-pipeline.html", + "extDocId": "logstash-centralized-pipeline-management", + "extDocUrl": "https://www.elastic.co/guide/en/logstash/{branch}/logstash-centralized-pipeline-management.html", "name": "logstash.get_pipeline", "privileges": { "cluster": [ @@ -9455,8 +9459,10 @@ "stability": "stable" } }, - "description": "Creates or updates a pipeline used for Logstash Central Management.", + "description": "Create or update a Logstash pipeline.\n\nCreate a pipeline that is used for Logstash Central Management.\nIf the specified pipeline exists, it is replaced.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/logstash-api-put-pipeline.html", + "extDocId": "logstash-centralized-pipeline-management", + "extDocUrl": "https://www.elastic.co/guide/en/logstash/{branch}/logstash-centralized-pipeline-management.html", "name": "logstash.put_pipeline", "privileges": { "cluster": [ @@ -149126,7 +149132,7 @@ }, "properties": [ { - "description": "Description of the pipeline.\nThis description is not used by Elasticsearch or Logstash.", + "description": "A description of the pipeline.\nThis description is not used by Elasticsearch or Logstash.", "name": "description", "required": true, "type": { @@ -149138,7 +149144,7 @@ } }, { - "description": "Date the pipeline was last updated.\nMust be in the `yyyy-MM-dd'T'HH:mm:ss.SSSZZ` strict_date_time format.", + "description": "The date the pipeline was last updated.\nIt must be in the `yyyy-MM-dd'T'HH:mm:ss.SSSZZ` strict_date_time format.", "name": "last_modified", "required": true, "type": { @@ -149150,59 +149156,59 @@ } }, { - "description": "Optional metadata about the pipeline.\nMay have any contents.\nThis metadata is not generated or used by Elasticsearch or Logstash.", - "name": "pipeline_metadata", + "description": "The configuration for the pipeline.", + "extDocId": "logstash-configuration-file-structure", + "extDocUrl": "https://www.elastic.co/guide/en/logstash/{branch}/configuration-file-structure.html", + "name": "pipeline", "required": true, "type": { "kind": "instance_of", "type": { - "name": "PipelineMetadata", - "namespace": "logstash._types" + "name": "string", + "namespace": "_builtins" } } }, { - "description": "User who last updated the pipeline.", - "name": "username", + "description": "Optional metadata about the pipeline, which can have any contents.\nThis metadata is not generated or used by Elasticsearch or Logstash.", + "name": "pipeline_metadata", "required": true, "type": { "kind": "instance_of", "type": { - "name": "string", - "namespace": "_builtins" + "name": "PipelineMetadata", + "namespace": "logstash._types" } } }, { - "description": "Configuration for the pipeline.", - "docId": "logstash-configuration-file-structure", - "docUrl": "https://www.elastic.co/guide/en/logstash/{branch}/configuration-file-structure.html", - "name": "pipeline", + "description": "Settings for the pipeline.\nIt supports only flat keys in dot notation.", + "extDocId": "logstash-logstash-settings-file", + "extDocUrl": "https://www.elastic.co/guide/en/logstash/{branch}/logstash-settings-file.html", + "name": "pipeline_settings", "required": true, "type": { "kind": "instance_of", "type": { - "name": "string", - "namespace": "_builtins" + "name": "PipelineSettings", + "namespace": "logstash._types" } } }, { - "description": "Settings for the pipeline.\nSupports only flat keys in dot notation.", - "docId": "logstash-logstash-settings-file", - "docUrl": "https://www.elastic.co/guide/en/logstash/{branch}/logstash-settings-file.html", - "name": "pipeline_settings", + "description": "The user who last updated the pipeline.", + "name": "username", "required": true, "type": { "kind": "instance_of", "type": { - "name": "PipelineSettings", - "namespace": "logstash._types" + "name": "string", + "namespace": "_builtins" } } } ], - "specLocation": "logstash/_types/Pipeline.ts#L60-L92" + "specLocation": "logstash/_types/Pipeline.ts#L60-L91" }, { "kind": "interface", @@ -149342,7 +149348,7 @@ "body": { "kind": "no_body" }, - "description": "Deletes a pipeline used for Logstash Central Management.", + "description": "Delete a Logstash pipeline.\n\nDelete a pipeline that is used for Logstash Central Management.", "inherits": { "type": { "name": "RequestBase", @@ -149355,7 +149361,7 @@ }, "path": [ { - "description": "Identifier for the pipeline.", + "description": "An identifier for the pipeline.", "name": "id", "required": true, "type": { @@ -149368,7 +149374,7 @@ } ], "query": [], - "specLocation": "logstash/delete_pipeline/LogstashDeletePipelineRequest.ts#L23-L37" + "specLocation": "logstash/delete_pipeline/LogstashDeletePipelineRequest.ts#L23-L40" }, { "kind": "response", @@ -149389,7 +149395,7 @@ "body": { "kind": "no_body" }, - "description": "Retrieves pipelines used for Logstash Central Management.", + "description": "Get Logstash pipelines.\n\nGet pipelines that are used for Logstash Central Management.", "inherits": { "type": { "name": "RequestBase", @@ -149402,7 +149408,7 @@ }, "path": [ { - "description": "Comma-separated list of pipeline identifiers.", + "description": "A comma-separated list of pipeline identifiers.", "name": "id", "required": false, "type": { @@ -149415,7 +149421,7 @@ } ], "query": [], - "specLocation": "logstash/get_pipeline/LogstashGetPipelineRequest.ts#L23-L37" + "specLocation": "logstash/get_pipeline/LogstashGetPipelineRequest.ts#L23-L40" }, { "kind": "response", @@ -149462,7 +149468,7 @@ } } }, - "description": "Creates or updates a pipeline used for Logstash Central Management.", + "description": "Create or update a Logstash pipeline.\n\nCreate a pipeline that is used for Logstash Central Management.\nIf the specified pipeline exists, it is replaced.", "inherits": { "type": { "name": "RequestBase", @@ -149475,7 +149481,7 @@ }, "path": [ { - "description": "Identifier for the pipeline.", + "description": "An identifier for the pipeline.", "name": "id", "required": true, "type": { @@ -149488,7 +149494,7 @@ } ], "query": [], - "specLocation": "logstash/put_pipeline/LogstashPutPipelineRequest.ts#L24-L39" + "specLocation": "logstash/put_pipeline/LogstashPutPipelineRequest.ts#L24-L44" }, { "kind": "response", diff --git a/output/typescript/types.ts b/output/typescript/types.ts index 074d11f89d..2de101888b 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -13530,10 +13530,10 @@ export interface LicensePostStartTrialResponse { export interface LogstashPipeline { description: string last_modified: DateTime - pipeline_metadata: LogstashPipelineMetadata - username: string pipeline: string + pipeline_metadata: LogstashPipelineMetadata pipeline_settings: LogstashPipelineSettings + username: string } export interface LogstashPipelineMetadata { diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 16601f3352..afbdb888e1 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -266,6 +266,7 @@ license-management,https://www.elastic.co/guide/en/kibana/{branch}/managing-lice logstash-api-delete-pipeline,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/logstash-api-delete-pipeline.html logstash-api-get-pipeline,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/logstash-api-get-pipeline.html logstash-api-put-pipeline,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/logstash-api-put-pipeline.html +logstash-centralized-pipeline-management,https://www.elastic.co/guide/en/logstash/{branch}/logstash-centralized-pipeline-management.html logstash-configuration-file-structure,https://www.elastic.co/guide/en/logstash/{branch}/configuration-file-structure.html logstash-logstash-settings-file,https://www.elastic.co/guide/en/logstash/{branch}/logstash-settings-file.html lowercase-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/lowercase-processor.html diff --git a/specification/logstash/_types/Pipeline.ts b/specification/logstash/_types/Pipeline.ts index 0e82c10bf2..76ff608407 100644 --- a/specification/logstash/_types/Pipeline.ts +++ b/specification/logstash/_types/Pipeline.ts @@ -59,34 +59,33 @@ export class PipelineSettings { } export class Pipeline { /** - * Description of the pipeline. + * A description of the pipeline. * This description is not used by Elasticsearch or Logstash. */ description: string /** - * Date the pipeline was last updated. - * Must be in the `yyyy-MM-dd'T'HH:mm:ss.SSSZZ` strict_date_time format. + * The date the pipeline was last updated. + * It must be in the `yyyy-MM-dd'T'HH:mm:ss.SSSZZ` strict_date_time format. */ last_modified: DateTime /** - * Optional metadata about the pipeline. - * May have any contents. - * This metadata is not generated or used by Elasticsearch or Logstash. - */ - pipeline_metadata: PipelineMetadata - /** - * User who last updated the pipeline. + * The configuration for the pipeline. + * @ext_doc_id logstash-configuration-file-structure */ - username: string + pipeline: string /** - * Configuration for the pipeline. - * @doc_id logstash-configuration-file-structure + * Optional metadata about the pipeline, which can have any contents. + * This metadata is not generated or used by Elasticsearch or Logstash. */ - pipeline: string + pipeline_metadata: PipelineMetadata /** * Settings for the pipeline. - * Supports only flat keys in dot notation. - * @doc_id logstash-logstash-settings-file + * It supports only flat keys in dot notation. + * @ext_doc_id logstash-logstash-settings-file */ pipeline_settings: PipelineSettings + /** + * The user who last updated the pipeline. + */ + username: string } diff --git a/specification/logstash/delete_pipeline/LogstashDeletePipelineRequest.ts b/specification/logstash/delete_pipeline/LogstashDeletePipelineRequest.ts index bc35272839..a94dc2b20e 100644 --- a/specification/logstash/delete_pipeline/LogstashDeletePipelineRequest.ts +++ b/specification/logstash/delete_pipeline/LogstashDeletePipelineRequest.ts @@ -21,16 +21,19 @@ import { RequestBase } from '@_types/Base' import { Id } from '@_types/common' /** - * Deletes a pipeline used for Logstash Central Management. + * Delete a Logstash pipeline. + * + * Delete a pipeline that is used for Logstash Central Management. * @rest_spec_name logstash.delete_pipeline * @availability stack since=7.12.0 stability=stable * @availability serverless stability=stable visibility=public * @cluster_privileges manage_logstash_pipelines + * @ext_doc_id logstash-centralized-pipeline-management */ export interface Request extends RequestBase { path_parts: { /** - * Identifier for the pipeline. + * An identifier for the pipeline. */ id: Id } diff --git a/specification/logstash/get_pipeline/LogstashGetPipelineRequest.ts b/specification/logstash/get_pipeline/LogstashGetPipelineRequest.ts index e5865df54b..52b59d2706 100644 --- a/specification/logstash/get_pipeline/LogstashGetPipelineRequest.ts +++ b/specification/logstash/get_pipeline/LogstashGetPipelineRequest.ts @@ -21,16 +21,19 @@ import { RequestBase } from '@_types/Base' import { Ids } from '@_types/common' /** - * Retrieves pipelines used for Logstash Central Management. + * Get Logstash pipelines. + * + * Get pipelines that are used for Logstash Central Management. * @rest_spec_name logstash.get_pipeline * @availability stack since=7.12.0 stability=stable * @availability serverless stability=stable visibility=public * @cluster_privileges manage_logstash_pipelines + * @ext_doc_id logstash-centralized-pipeline-management */ export interface Request extends RequestBase { path_parts: { /** - * Comma-separated list of pipeline identifiers. + * A comma-separated list of pipeline identifiers. */ id?: Ids } diff --git a/specification/logstash/put_pipeline/LogstashPutPipelineRequest.ts b/specification/logstash/put_pipeline/LogstashPutPipelineRequest.ts index 4a41853425..aac5048de2 100644 --- a/specification/logstash/put_pipeline/LogstashPutPipelineRequest.ts +++ b/specification/logstash/put_pipeline/LogstashPutPipelineRequest.ts @@ -21,16 +21,21 @@ import { Pipeline } from '@logstash/_types/Pipeline' import { RequestBase } from '@_types/Base' import { Id } from '@_types/common' -/** Creates or updates a pipeline used for Logstash Central Management. +/** + * Create or update a Logstash pipeline. + * + * Create a pipeline that is used for Logstash Central Management. + * If the specified pipeline exists, it is replaced. * @rest_spec_name logstash.put_pipeline * @availability stack since=7.12.0 stability=stable * @availability serverless stability=stable visibility=public * @cluster_privileges manage_logstash_pipelines + * @ext_doc_id logstash-centralized-pipeline-management */ export interface Request extends RequestBase { path_parts: { /** - * Identifier for the pipeline. + * An identifier for the pipeline. */ id: Id } From dd4ec30bb982154fd2f909f04c7cea6f2c199174 Mon Sep 17 00:00:00 2001 From: Elastic Machine Date: Tue, 17 Dec 2024 02:32:31 +0000 Subject: [PATCH 10/10] Update specification output --- output/schema/schema-serverless.json | 76 +++++++++++++++------------- 1 file changed, 41 insertions(+), 35 deletions(-) diff --git a/output/schema/schema-serverless.json b/output/schema/schema-serverless.json index 360ee95471..19430f8333 100644 --- a/output/schema/schema-serverless.json +++ b/output/schema/schema-serverless.json @@ -4610,8 +4610,10 @@ "stability": "stable" } }, - "description": "Deletes a pipeline used for Logstash Central Management.", + "description": "Delete a Logstash pipeline.\n\nDelete a pipeline that is used for Logstash Central Management.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/logstash-api-delete-pipeline.html", + "extDocId": "logstash-centralized-pipeline-management", + "extDocUrl": "https://www.elastic.co/guide/en/logstash/{branch}/logstash-centralized-pipeline-management.html", "name": "logstash.delete_pipeline", "privileges": { "cluster": [ @@ -4650,8 +4652,10 @@ "stability": "stable" } }, - "description": "Retrieves pipelines used for Logstash Central Management.", + "description": "Get Logstash pipelines.\n\nGet pipelines that are used for Logstash Central Management.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/logstash-api-get-pipeline.html", + "extDocId": "logstash-centralized-pipeline-management", + "extDocUrl": "https://www.elastic.co/guide/en/logstash/{branch}/logstash-centralized-pipeline-management.html", "name": "logstash.get_pipeline", "privileges": { "cluster": [ @@ -4696,8 +4700,10 @@ "stability": "stable" } }, - "description": "Creates or updates a pipeline used for Logstash Central Management.", + "description": "Create or update a Logstash pipeline.\n\nCreate a pipeline that is used for Logstash Central Management.\nIf the specified pipeline exists, it is replaced.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/logstash-api-put-pipeline.html", + "extDocId": "logstash-centralized-pipeline-management", + "extDocUrl": "https://www.elastic.co/guide/en/logstash/{branch}/logstash-centralized-pipeline-management.html", "name": "logstash.put_pipeline", "privileges": { "cluster": [ @@ -25403,7 +25409,7 @@ "body": { "kind": "no_body" }, - "description": "Deletes a pipeline used for Logstash Central Management.", + "description": "Delete a Logstash pipeline.\n\nDelete a pipeline that is used for Logstash Central Management.", "inherits": { "type": { "name": "RequestBase", @@ -25417,7 +25423,7 @@ }, "path": [ { - "description": "Identifier for the pipeline.", + "description": "An identifier for the pipeline.", "name": "id", "required": true, "type": { @@ -25430,7 +25436,7 @@ } ], "query": [], - "specLocation": "logstash/delete_pipeline/LogstashDeletePipelineRequest.ts#L23-L37" + "specLocation": "logstash/delete_pipeline/LogstashDeletePipelineRequest.ts#L23-L40" }, { "body": { @@ -25450,7 +25456,7 @@ "body": { "kind": "no_body" }, - "description": "Retrieves pipelines used for Logstash Central Management.", + "description": "Get Logstash pipelines.\n\nGet pipelines that are used for Logstash Central Management.", "inherits": { "type": { "name": "RequestBase", @@ -25464,7 +25470,7 @@ }, "path": [ { - "description": "Comma-separated list of pipeline identifiers.", + "description": "A comma-separated list of pipeline identifiers.", "name": "id", "required": false, "type": { @@ -25477,7 +25483,7 @@ } ], "query": [], - "specLocation": "logstash/get_pipeline/LogstashGetPipelineRequest.ts#L23-L37" + "specLocation": "logstash/get_pipeline/LogstashGetPipelineRequest.ts#L23-L40" }, { "body": { @@ -25523,7 +25529,7 @@ } } }, - "description": "Creates or updates a pipeline used for Logstash Central Management.", + "description": "Create or update a Logstash pipeline.\n\nCreate a pipeline that is used for Logstash Central Management.\nIf the specified pipeline exists, it is replaced.", "inherits": { "type": { "name": "RequestBase", @@ -25537,7 +25543,7 @@ }, "path": [ { - "description": "Identifier for the pipeline.", + "description": "An identifier for the pipeline.", "name": "id", "required": true, "type": { @@ -25550,7 +25556,7 @@ } ], "query": [], - "specLocation": "logstash/put_pipeline/LogstashPutPipelineRequest.ts#L24-L39" + "specLocation": "logstash/put_pipeline/LogstashPutPipelineRequest.ts#L24-L44" }, { "body": { @@ -126214,7 +126220,7 @@ }, "properties": [ { - "description": "Description of the pipeline.\nThis description is not used by Elasticsearch or Logstash.", + "description": "A description of the pipeline.\nThis description is not used by Elasticsearch or Logstash.", "name": "description", "required": true, "type": { @@ -126226,7 +126232,7 @@ } }, { - "description": "Date the pipeline was last updated.\nMust be in the `yyyy-MM-dd'T'HH:mm:ss.SSSZZ` strict_date_time format.", + "description": "The date the pipeline was last updated.\nIt must be in the `yyyy-MM-dd'T'HH:mm:ss.SSSZZ` strict_date_time format.", "name": "last_modified", "required": true, "type": { @@ -126238,59 +126244,59 @@ } }, { - "description": "Optional metadata about the pipeline.\nMay have any contents.\nThis metadata is not generated or used by Elasticsearch or Logstash.", - "name": "pipeline_metadata", + "description": "The configuration for the pipeline.", + "extDocId": "logstash-configuration-file-structure", + "extDocUrl": "https://www.elastic.co/guide/en/logstash/{branch}/configuration-file-structure.html", + "name": "pipeline", "required": true, "type": { "kind": "instance_of", "type": { - "name": "PipelineMetadata", - "namespace": "logstash._types" + "name": "string", + "namespace": "_builtins" } } }, { - "description": "User who last updated the pipeline.", - "name": "username", + "description": "Optional metadata about the pipeline, which can have any contents.\nThis metadata is not generated or used by Elasticsearch or Logstash.", + "name": "pipeline_metadata", "required": true, "type": { "kind": "instance_of", "type": { - "name": "string", - "namespace": "_builtins" + "name": "PipelineMetadata", + "namespace": "logstash._types" } } }, { - "description": "Configuration for the pipeline.", - "docId": "logstash-configuration-file-structure", - "docUrl": "https://www.elastic.co/guide/en/logstash/{branch}/configuration-file-structure.html", - "name": "pipeline", + "description": "Settings for the pipeline.\nIt supports only flat keys in dot notation.", + "extDocId": "logstash-logstash-settings-file", + "extDocUrl": "https://www.elastic.co/guide/en/logstash/{branch}/logstash-settings-file.html", + "name": "pipeline_settings", "required": true, "type": { "kind": "instance_of", "type": { - "name": "string", - "namespace": "_builtins" + "name": "PipelineSettings", + "namespace": "logstash._types" } } }, { - "description": "Settings for the pipeline.\nSupports only flat keys in dot notation.", - "docId": "logstash-logstash-settings-file", - "docUrl": "https://www.elastic.co/guide/en/logstash/{branch}/logstash-settings-file.html", - "name": "pipeline_settings", + "description": "The user who last updated the pipeline.", + "name": "username", "required": true, "type": { "kind": "instance_of", "type": { - "name": "PipelineSettings", - "namespace": "logstash._types" + "name": "string", + "namespace": "_builtins" } } } ], - "specLocation": "logstash/_types/Pipeline.ts#L60-L92" + "specLocation": "logstash/_types/Pipeline.ts#L60-L91" }, { "kind": "interface",