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 diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 19cbf53ecf..2e1aa65035 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": { @@ -20409,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": { @@ -22586,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": { @@ -22620,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": [ { @@ -22647,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": [ { @@ -22676,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": [ { @@ -22706,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": [ { @@ -30936,8 +30944,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": [ { @@ -30961,8 +30969,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": [ { @@ -31046,8 +31054,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": [ { @@ -31102,8 +31110,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": [ { @@ -31126,7 +31134,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": [ { @@ -31144,13 +31153,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": { @@ -31224,7 +31234,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": [ { @@ -31259,7 +31270,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": [ { @@ -31302,7 +31314,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": { @@ -31324,7 +31337,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": { @@ -31339,7 +31353,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": { @@ -31408,7 +31423,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": { @@ -31438,7 +31453,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": { @@ -31460,7 +31476,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 6c48ad6670..1dfdbfa67f 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" ] @@ -11429,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": { @@ -12908,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": { @@ -12939,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": { @@ -17703,9 +17716,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" @@ -17737,9 +17755,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" @@ -17777,9 +17800,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" @@ -17851,9 +17879,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" @@ -17886,9 +17919,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" @@ -17921,9 +17959,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" @@ -17956,9 +17999,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" @@ -17997,9 +18045,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" @@ -18032,9 +18085,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" @@ -18067,9 +18125,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" @@ -18105,9 +18171,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" @@ -18140,7 +18211,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": { @@ -149477,7 +149548,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", @@ -149503,7 +149574,7 @@ } ], "query": [], - "specLocation": "migration/deprecations/DeprecationInfoRequest.ts#L23-L32" + "specLocation": "migration/deprecations/DeprecationInfoRequest.ts#L23-L37" }, { "kind": "response", @@ -149740,7 +149811,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", @@ -149753,7 +149824,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", @@ -149822,7 +149893,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", @@ -149835,7 +149906,7 @@ }, "path": [], "query": [], - "specLocation": "migration/post_feature_upgrade/PostFeatureUpgradeRequest.ts#L22-L27" + "specLocation": "migration/post_feature_upgrade/PostFeatureUpgradeRequest.ts#L22-L35" }, { "kind": "response", @@ -168617,7 +168688,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", @@ -175169,7 +175240,7 @@ } } }, - "description": "Validates an anomaly detection detector.", + "description": "Validate an anomaly detection job.", "inherits": { "type": { "name": "RequestBase", @@ -175182,7 +175253,7 @@ }, "path": [], "query": [], - "specLocation": "ml/validate_detector/MlValidateDetectorRequest.ts#L23-L31" + "specLocation": "ml/validate_detector/MlValidateDetectorRequest.ts#L23-L33" }, { "kind": "response", @@ -175256,7 +175327,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", @@ -175333,7 +175404,7 @@ } } ], - "specLocation": "monitoring/bulk/BulkMonitoringRequest.ts#L24-L59" + "specLocation": "monitoring/bulk/BulkMonitoringRequest.ts#L24-L61" }, { "kind": "response", @@ -199997,7 +200068,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", @@ -200050,7 +200121,7 @@ } } ], - "specLocation": "shutdown/delete_node/ShutdownDeleteNodeRequest.ts#L24-L44" + "specLocation": "shutdown/delete_node/ShutdownDeleteNodeRequest.ts#L24-L54" }, { "kind": "response", @@ -200227,7 +200298,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", @@ -200280,7 +200351,7 @@ } } ], - "specLocation": "shutdown/get_node/ShutdownGetNodeRequest.ts#L24-L44" + "specLocation": "shutdown/get_node/ShutdownGetNodeRequest.ts#L24-L53" }, { "kind": "response", @@ -200426,7 +200497,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", @@ -200479,7 +200550,7 @@ } } ], - "specLocation": "shutdown/put_node/ShutdownPutNodeRequest.ts#L25-L76" + "specLocation": "shutdown/put_node/ShutdownPutNodeRequest.ts#L25-L91" }, { "kind": "response", @@ -201080,7 +201151,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", @@ -201106,7 +201177,7 @@ } ], "query": [], - "specLocation": "slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts#L23-L32" + "specLocation": "slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts#L23-L36" }, { "kind": "response", @@ -201134,7 +201205,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", @@ -201160,7 +201231,7 @@ } ], "query": [], - "specLocation": "slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts#L23-L32" + "specLocation": "slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts#L23-L36" }, { "kind": "response", @@ -201194,7 +201265,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", @@ -201207,7 +201278,7 @@ }, "path": [], "query": [], - "specLocation": "slm/execute_retention/ExecuteRetentionRequest.ts#L22-L27" + "specLocation": "slm/execute_retention/ExecuteRetentionRequest.ts#L22-L31" }, { "kind": "response", @@ -201235,7 +201306,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", @@ -201261,7 +201332,7 @@ } ], "query": [], - "specLocation": "slm/get_lifecycle/GetSnapshotLifecycleRequest.ts#L23-L32" + "specLocation": "slm/get_lifecycle/GetSnapshotLifecycleRequest.ts#L23-L38" }, { "kind": "response", @@ -201300,7 +201371,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", @@ -201313,7 +201384,7 @@ }, "path": [], "query": [], - "specLocation": "slm/get_stats/GetSnapshotLifecycleStatsRequest.ts#L22-L27" + "specLocation": "slm/get_stats/GetSnapshotLifecycleStatsRequest.ts#L22-L30" }, { "kind": "response", @@ -201458,7 +201529,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", @@ -201471,7 +201542,7 @@ }, "path": [], "query": [], - "specLocation": "slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts#L22-L27" + "specLocation": "slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts#L22-L29" }, { "kind": "response", @@ -201567,7 +201638,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", @@ -201580,7 +201651,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": { @@ -201620,7 +201691,7 @@ } } ], - "specLocation": "slm/put_lifecycle/PutSnapshotLifecycleRequest.ts#L26-L72" + "specLocation": "slm/put_lifecycle/PutSnapshotLifecycleRequest.ts#L26-L78" }, { "kind": "response", @@ -201648,7 +201719,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", @@ -201661,7 +201732,7 @@ }, "path": [], "query": [], - "specLocation": "slm/start/StartSnapshotLifecycleManagementRequest.ts#L22-L27" + "specLocation": "slm/start/StartSnapshotLifecycleManagementRequest.ts#L22-L31" }, { "kind": "response", @@ -201689,7 +201760,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", @@ -201702,7 +201773,7 @@ }, "path": [], "query": [], - "specLocation": "slm/stop/StopSnapshotLifecycleManagementRequest.ts#L22-L27" + "specLocation": "slm/stop/StopSnapshotLifecycleManagementRequest.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 {} 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 */ 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: { 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: { 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