From 80bc514945d4927450802554424e55016bce49b2 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 11 Dec 2024 10:10:38 -0800 Subject: [PATCH] [DOCS] Edit ILM operation summaries (#3270) (#3275) (cherry picked from commit af56c0e01376faefcdac40781ac40c23431feac5) Co-authored-by: Lisa Cawley --- output/openapi/elasticsearch-openapi.json | 44 +++++--- .../elasticsearch-serverless-openapi.json | 2 +- output/schema/schema.json | 100 ++++++++++++------ specification/_doc_ids/table.csv | 2 + .../DeleteLifecycleRequest.ts | 4 +- .../ExplainLifecycleRequest.ts | 6 +- .../ilm/get_lifecycle/GetLifecycleRequest.ts | 2 +- .../ilm/get_status/GetIlmStatusRequest.ts | 3 + .../ilm/migrate_to_data_tiers/Request.ts | 15 ++- .../ilm/move_to_step/MoveToStepRequest.ts | 15 +++ .../ilm/put_lifecycle/PutLifecycleRequest.ts | 6 +- .../ilm/remove_policy/RemovePolicyRequest.ts | 4 + specification/ilm/retry/RetryIlmRequest.ts | 5 + specification/ilm/start/StartIlmRequest.ts | 5 + specification/ilm/stop/StopIlmRequest.ts | 7 ++ .../IndicesExplainDataLifecycleRequest.ts | 2 +- 16 files changed, 164 insertions(+), 58 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 75449ae08e..cefb9125dc 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -9343,7 +9343,7 @@ "tags": [ "ilm" ], - "summary": "Retrieves a lifecycle policy", + "summary": "Get lifecycle policies", "operationId": "ilm-get-lifecycle", "parameters": [ { @@ -9367,8 +9367,11 @@ "tags": [ "ilm" ], - "summary": "Creates a lifecycle policy", - "description": "If the specified policy exists, the policy is replaced and the policy version is incremented.", + "summary": "Create or update a lifecycle policy", + "description": "If the specified policy exists, it is replaced and the policy version is incremented.\n\nNOTE: Only the latest version of the policy is stored, you cannot revert to previous versions.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-index-lifecycle.html" + }, "operationId": "ilm-put-lifecycle", "parameters": [ { @@ -9435,7 +9438,7 @@ "tags": [ "ilm" ], - "summary": "Deletes the specified lifecycle policy definition", + "summary": "Delete a lifecycle policy", "description": "You cannot delete policies that are currently in use. If the policy is being used to manage any indices, the request fails and returns an error.", "operationId": "ilm-delete-lifecycle", "parameters": [ @@ -9491,8 +9494,8 @@ "tags": [ "ilm" ], - "summary": "Retrieves information about the index’s current lifecycle state, such as the currently executing phase, action, and step", - "description": "Shows when the index entered each one, the definition of the running phase, and information about any failures.", + "summary": "Explain the lifecycle state", + "description": "Get the current lifecycle status for one or more indices.\nFor data streams, the API retrieves the current lifecycle status for the stream's backing indices.\n\nThe response indicates when the index entered each lifecycle state, provides the definition of the running phase, and information about any failures.", "operationId": "ilm-explain-lifecycle", "parameters": [ { @@ -9578,7 +9581,7 @@ "tags": [ "ilm" ], - "summary": "Retrieves a lifecycle policy", + "summary": "Get lifecycle policies", "operationId": "ilm-get-lifecycle-1", "parameters": [ { @@ -9601,7 +9604,8 @@ "tags": [ "ilm" ], - "summary": "Retrieves the current index lifecycle management (ILM) status", + "summary": "Get the ILM status", + "description": "Get the current index lifecycle management status.", "operationId": "ilm-get-status", "responses": { "200": { @@ -9631,8 +9635,11 @@ "tags": [ "ilm" ], - "summary": "Switches the indices, ILM policies, and legacy, composable and component templates from using custom node attributes and\n", - "description": "attribute-based allocation filters to using data tiers, and optionally deletes one legacy index template.+\nUsing node roles enables ILM to automatically move the indices between data tiers.", + "summary": "Migrate to data tiers routing", + "description": "Switch the indices, ILM policies, and legacy, composable, and component templates from using custom node attributes and attribute-based allocation filters to using data tiers.\nOptionally, delete one legacy index template.\nUsing node roles enables ILM to automatically move the indices between data tiers.\n\nMigrating away from custom node attributes routing can be manually performed.\nThis API provides an automated way of performing three out of the four manual steps listed in the migration guide:\n\n1. Stop setting the custom hot attribute on new indices.\n1. Remove custom allocation settings from existing ILM policies.\n1. Replace custom allocation settings from existing indices with the corresponding tier preference.\n\nILM must be stopped before performing the migration.\nUse the stop ILM and get ILM status APIs to wait until the reported operation mode is `STOPPED`.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/migrate-index-allocation-filters.html" + }, "operationId": "ilm-migrate-to-data-tiers", "parameters": [ { @@ -9727,7 +9734,8 @@ "tags": [ "ilm" ], - "summary": "Manually moves an index into the specified step and executes that step", + "summary": "Move to a lifecycle step", + "description": "Manually move an index into a specific step in the lifecycle policy and run that step.\n\nWARNING: This operation can result in the loss of data. Manually moving an index into a specific step runs that step even if it has already been performed. This is a potentially destructive action and this should be considered an expert level API.\n\nYou must specify both the current step and the step to be executed in the body of the request.\nThe request will fail if the current step does not match the step currently running for the index\nThis is to prevent the index from being moved from an unexpected step into the next step.\n\nWhen specifying the target (`next_step`) to which the index will be moved, either the name or both the action and name fields are optional.\nIf only the phase is specified, the index will move to the first step of the first action in the target phase.\nIf the phase and action are specified, the index will move to the first step of the specified action in the specified phase.\nOnly actions specified in the ILM policy are considered valid.\nAn index cannot move to a step that is not part of its policy.", "operationId": "ilm-move-to-step", "parameters": [ { @@ -9783,7 +9791,8 @@ "tags": [ "ilm" ], - "summary": "Removes the assigned lifecycle policy and stops managing the specified index", + "summary": "Remove policies from an index", + "description": "Remove the assigned lifecycle policies from an index or a data stream's backing indices.\nIt also stops managing the indices.", "operationId": "ilm-remove-policy", "parameters": [ { @@ -9833,7 +9842,8 @@ "tags": [ "ilm" ], - "summary": "Retries executing the policy for an index that is in the ERROR step", + "summary": "Retry a policy", + "description": "Retry running the lifecycle policy for an index that is in the ERROR step.\nThe API sets the policy back to the step where the error occurred and runs the step.\nUse the explain lifecycle state API to determine whether an index is in the ERROR step.", "operationId": "ilm-retry", "parameters": [ { @@ -9868,7 +9878,8 @@ "tags": [ "ilm" ], - "summary": "Start the index lifecycle management (ILM) plugin", + "summary": "Start the ILM plugin", + "description": "Start the index lifecycle management plugin if it is currently stopped.\nILM is started automatically when the cluster is formed.\nRestarting ILM is necessary only when it has been stopped using the stop ILM API.", "operationId": "ilm-start", "parameters": [ { @@ -9910,7 +9921,8 @@ "tags": [ "ilm" ], - "summary": "Halts all lifecycle management operations and stops the index lifecycle management (ILM) plugin", + "summary": "Stop the ILM plugin", + "description": "Halt all lifecycle management operations and stop the index lifecycle management plugin.\nThis is useful when you are performing maintenance on the cluster and need to prevent ILM from performing any actions on your indices.\n\nThe API returns as soon as the stop request has been acknowledged, but the plugin might continue to run until in-progress operations complete and the plugin can be safely stopped.\nUse the get ILM status API to check whether ILM is running.", "operationId": "ilm-stop", "parameters": [ { @@ -12105,7 +12117,7 @@ "indices" ], "summary": "Get the status for a data stream lifecycle", - "description": "Retrieves information about an index or data stream’s current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.", + "description": "Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.", "operationId": "indices-explain-data-lifecycle", "parameters": [ { diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index a31ff6004e..24acb18c7f 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -7325,7 +7325,7 @@ "indices" ], "summary": "Get the status for a data stream lifecycle", - "description": "Retrieves information about an index or data stream’s current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.", + "description": "Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.", "operationId": "indices-explain-data-lifecycle", "parameters": [ { diff --git a/output/schema/schema.json b/output/schema/schema.json index 19858f968f..59efe72c35 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -5531,7 +5531,7 @@ "stability": "stable" } }, - "description": "Deletes the specified lifecycle policy definition. You cannot delete policies that are currently in use. If the policy is being used to manage any indices, the request fails and returns an error.", + "description": "Delete a lifecycle policy.\nYou cannot delete policies that are currently in use. If the policy is being used to manage any indices, the request fails and returns an error.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-delete-lifecycle.html", "name": "ilm.delete_lifecycle", "privileges": { @@ -5567,7 +5567,7 @@ "stability": "stable" } }, - "description": "Retrieves information about the index’s current lifecycle state, such as the currently executing phase, action, and step. Shows when the index entered each one, the definition of the running phase, and information about any failures.", + "description": "Explain the lifecycle state.\nGet the current lifecycle status for one or more indices.\nFor data streams, the API retrieves the current lifecycle status for the stream's backing indices.\n\nThe response indicates when the index entered each lifecycle state, provides the definition of the running phase, and information about any failures.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-explain-lifecycle.html", "name": "ilm.explain_lifecycle", "privileges": { @@ -5604,7 +5604,7 @@ "stability": "stable" } }, - "description": "Retrieves a lifecycle policy.", + "description": "Get lifecycle policies.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-get-lifecycle.html", "name": "ilm.get_lifecycle", "privileges": { @@ -5647,9 +5647,14 @@ "stability": "stable" } }, - "description": "Retrieves the current index lifecycle management (ILM) status.", + "description": "Get the ILM status.\nGet the current index lifecycle management status.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-get-status.html", "name": "ilm.get_status", + "privileges": { + "cluster": [ + "read_ilm" + ] + }, "request": { "name": "Request", "namespace": "ilm.get_status" @@ -5678,8 +5683,10 @@ "stability": "stable" } }, - "description": "Switches the indices, ILM policies, and legacy, composable and component templates from using custom node attributes and\nattribute-based allocation filters to using data tiers, and optionally deletes one legacy index template.+\nUsing node roles enables ILM to automatically move the indices between data tiers.", + "description": "Migrate to data tiers routing.\nSwitch the indices, ILM policies, and legacy, composable, and component templates from using custom node attributes and attribute-based allocation filters to using data tiers.\nOptionally, delete one legacy index template.\nUsing node roles enables ILM to automatically move the indices between data tiers.\n\nMigrating away from custom node attributes routing can be manually performed.\nThis API provides an automated way of performing three out of the four manual steps listed in the migration guide:\n\n1. Stop setting the custom hot attribute on new indices.\n1. Remove custom allocation settings from existing ILM policies.\n1. Replace custom allocation settings from existing indices with the corresponding tier preference.\n\nILM must be stopped before performing the migration.\nUse the stop ILM and get ILM status APIs to wait until the reported operation mode is `STOPPED`.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-migrate-to-data-tiers.html", + "extDocId": "migrate-index-allocation-filters", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/migrate-index-allocation-filters.html", "name": "ilm.migrate_to_data_tiers", "request": { "name": "Request", @@ -5712,9 +5719,14 @@ "stability": "stable" } }, - "description": "Manually moves an index into the specified step and executes that step.", + "description": "Move to a lifecycle step.\nManually move an index into a specific step in the lifecycle policy and run that step.\n\nWARNING: This operation can result in the loss of data. Manually moving an index into a specific step runs that step even if it has already been performed. This is a potentially destructive action and this should be considered an expert level API.\n\nYou must specify both the current step and the step to be executed in the body of the request.\nThe request will fail if the current step does not match the step currently running for the index\nThis is to prevent the index from being moved from an unexpected step into the next step.\n\nWhen specifying the target (`next_step`) to which the index will be moved, either the name or both the action and name fields are optional.\nIf only the phase is specified, the index will move to the first step of the first action in the target phase.\nIf the phase and action are specified, the index will move to the first step of the specified action in the specified phase.\nOnly actions specified in the ILM policy are considered valid.\nAn index cannot move to a step that is not part of its policy.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-move-to-step.html", "name": "ilm.move_to_step", + "privileges": { + "index": [ + "manage_ilm" + ] + }, "request": { "name": "Request", "namespace": "ilm.move_to_step" @@ -5746,8 +5758,10 @@ "stability": "stable" } }, - "description": "Creates a lifecycle policy. If the specified policy exists, the policy is replaced and the policy version is incremented.", + "description": "Create or update a lifecycle policy.\nIf the specified policy exists, it is replaced and the policy version is incremented.\n\nNOTE: Only the latest version of the policy is stored, you cannot revert to previous versions.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-put-lifecycle.html", + "extDocId": "ilm-index-lifecycle", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ilm-index-lifecycle.html", "name": "ilm.put_lifecycle", "privileges": { "cluster": [ @@ -5788,9 +5802,14 @@ "stability": "stable" } }, - "description": "Removes the assigned lifecycle policy and stops managing the specified index", + "description": "Remove policies from an index.\nRemove the assigned lifecycle policies from an index or a data stream's backing indices.\nIt also stops managing the indices.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-remove-policy.html", "name": "ilm.remove_policy", + "privileges": { + "index": [ + "manage_ilm" + ] + }, "request": { "name": "Request", "namespace": "ilm.remove_policy" @@ -5819,9 +5838,14 @@ "stability": "stable" } }, - "description": "Retries executing the policy for an index that is in the ERROR step.", + "description": "Retry a policy.\nRetry running the lifecycle policy for an index that is in the ERROR step.\nThe API sets the policy back to the step where the error occurred and runs the step.\nUse the explain lifecycle state API to determine whether an index is in the ERROR step.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-retry-policy.html", "name": "ilm.retry", + "privileges": { + "index": [ + "manage_ilm" + ] + }, "request": { "name": "Request", "namespace": "ilm.retry" @@ -5850,9 +5874,14 @@ "stability": "stable" } }, - "description": "Start the index lifecycle management (ILM) plugin.", + "description": "Start the ILM plugin.\nStart the index lifecycle management plugin if it is currently stopped.\nILM is started automatically when the cluster is formed.\nRestarting ILM is necessary only when it has been stopped using the stop ILM API.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-start.html", "name": "ilm.start", + "privileges": { + "cluster": [ + "manage_ilm" + ] + }, "request": { "name": "Request", "namespace": "ilm.start" @@ -5881,9 +5910,14 @@ "stability": "stable" } }, - "description": "Halts all lifecycle management operations and stops the index lifecycle management (ILM) plugin", + "description": "Stop the ILM plugin.\nHalt all lifecycle management operations and stop the index lifecycle management plugin.\nThis is useful when you are performing maintenance on the cluster and need to prevent ILM from performing any actions on your indices.\n\nThe API returns as soon as the stop request has been acknowledged, but the plugin might continue to run until in-progress operations complete and the plugin can be safely stopped.\nUse the get ILM status API to check whether ILM is running.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-stop.html", "name": "ilm.stop", + "privileges": { + "cluster": [ + "manage_ilm" + ] + }, "request": { "name": "Request", "namespace": "ilm.stop" @@ -6723,7 +6757,7 @@ "stability": "stable" } }, - "description": "Get the status for a data stream lifecycle.\nRetrieves information about an index or data stream’s current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.", + "description": "Get the status for a data stream lifecycle.\nGet information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams-explain-lifecycle.html", "name": "indices.explain_data_lifecycle", "request": { @@ -121356,7 +121390,7 @@ "body": { "kind": "no_body" }, - "description": "Deletes the specified lifecycle policy definition. You cannot delete policies that are currently in use. If the policy is being used to manage any indices, the request fails and returns an error.", + "description": "Delete a lifecycle policy.\nYou cannot delete policies that are currently in use. If the policy is being used to manage any indices, the request fails and returns an error.", "inherits": { "type": { "name": "RequestBase", @@ -121862,7 +121896,7 @@ "body": { "kind": "no_body" }, - "description": "Retrieves information about the index’s current lifecycle state, such as the currently executing phase, action, and step. Shows when the index entered each one, the definition of the running phase, and information about any failures.", + "description": "Explain the lifecycle state.\nGet the current lifecycle status for one or more indices.\nFor data streams, the API retrieves the current lifecycle status for the stream's backing indices.\n\nThe response indicates when the index entered each lifecycle state, provides the definition of the running phase, and information about any failures.", "inherits": { "type": { "name": "RequestBase", @@ -121939,7 +121973,7 @@ } } ], - "specLocation": "ilm/explain_lifecycle/ExplainLifecycleRequest.ts#L24-L58" + "specLocation": "ilm/explain_lifecycle/ExplainLifecycleRequest.ts#L24-L62" }, { "kind": "response", @@ -122027,7 +122061,7 @@ "body": { "kind": "no_body" }, - "description": "Retrieves a lifecycle policy.", + "description": "Get lifecycle policies.", "inherits": { "type": { "name": "RequestBase", @@ -122120,7 +122154,7 @@ "body": { "kind": "no_body" }, - "description": "Retrieves the current index lifecycle management (ILM) status.", + "description": "Get the ILM status.\nGet the current index lifecycle management status.", "inherits": { "type": { "name": "RequestBase", @@ -122133,7 +122167,7 @@ }, "path": [], "query": [], - "specLocation": "ilm/get_status/GetIlmStatusRequest.ts#L22-L26" + "specLocation": "ilm/get_status/GetIlmStatusRequest.ts#L22-L29" }, { "kind": "response", @@ -122191,7 +122225,7 @@ } ] }, - "description": "Switches the indices, ILM policies, and legacy, composable and component templates from using custom node attributes and\nattribute-based allocation filters to using data tiers, and optionally deletes one legacy index template.+\nUsing node roles enables ILM to automatically move the indices between data tiers.", + "description": "Migrate to data tiers routing.\nSwitch the indices, ILM policies, and legacy, composable, and component templates from using custom node attributes and attribute-based allocation filters to using data tiers.\nOptionally, delete one legacy index template.\nUsing node roles enables ILM to automatically move the indices between data tiers.\n\nMigrating away from custom node attributes routing can be manually performed.\nThis API provides an automated way of performing three out of the four manual steps listed in the migration guide:\n\n1. Stop setting the custom hot attribute on new indices.\n1. Remove custom allocation settings from existing ILM policies.\n1. Replace custom allocation settings from existing indices with the corresponding tier preference.\n\nILM must be stopped before performing the migration.\nUse the stop ILM and get ILM status APIs to wait until the reported operation mode is `STOPPED`.", "inherits": { "type": { "name": "RequestBase", @@ -122218,7 +122252,7 @@ } } ], - "specLocation": "ilm/migrate_to_data_tiers/Request.ts#L22-L43" + "specLocation": "ilm/migrate_to_data_tiers/Request.ts#L22-L54" }, { "kind": "response", @@ -122354,7 +122388,7 @@ } ] }, - "description": "Manually moves an index into the specified step and executes that step.", + "description": "Move to a lifecycle step.\nManually move an index into a specific step in the lifecycle policy and run that step.\n\nWARNING: This operation can result in the loss of data. Manually moving an index into a specific step runs that step even if it has already been performed. This is a potentially destructive action and this should be considered an expert level API.\n\nYou must specify both the current step and the step to be executed in the body of the request.\nThe request will fail if the current step does not match the step currently running for the index\nThis is to prevent the index from being moved from an unexpected step into the next step.\n\nWhen specifying the target (`next_step`) to which the index will be moved, either the name or both the action and name fields are optional.\nIf only the phase is specified, the index will move to the first step of the first action in the target phase.\nIf the phase and action are specified, the index will move to the first step of the specified action in the specified phase.\nOnly actions specified in the ILM policy are considered valid.\nAn index cannot move to a step that is not part of its policy.", "inherits": { "type": { "name": "RequestBase", @@ -122380,7 +122414,7 @@ } ], "query": [], - "specLocation": "ilm/move_to_step/MoveToStepRequest.ts#L24-L36" + "specLocation": "ilm/move_to_step/MoveToStepRequest.ts#L24-L51" }, { "kind": "response", @@ -122464,7 +122498,7 @@ } ] }, - "description": "Creates a lifecycle policy. If the specified policy exists, the policy is replaced and the policy version is incremented.", + "description": "Create or update a lifecycle policy.\nIf the specified policy exists, it is replaced and the policy version is incremented.\n\nNOTE: Only the latest version of the policy is stored, you cannot revert to previous versions.", "inherits": { "type": { "name": "RequestBase", @@ -122518,7 +122552,7 @@ } } ], - "specLocation": "ilm/put_lifecycle/PutLifecycleRequest.ts#L25-L55" + "specLocation": "ilm/put_lifecycle/PutLifecycleRequest.ts#L25-L59" }, { "kind": "response", @@ -122546,7 +122580,7 @@ "body": { "kind": "no_body" }, - "description": "Removes the assigned lifecycle policy and stops managing the specified index", + "description": "Remove policies from an index.\nRemove the assigned lifecycle policies from an index or a data stream's backing indices.\nIt also stops managing the indices.", "inherits": { "type": { "name": "RequestBase", @@ -122572,7 +122606,7 @@ } ], "query": [], - "specLocation": "ilm/remove_policy/RemovePolicyRequest.ts#L23-L31" + "specLocation": "ilm/remove_policy/RemovePolicyRequest.ts#L23-L35" }, { "kind": "response", @@ -122620,7 +122654,7 @@ "body": { "kind": "no_body" }, - "description": "Retries executing the policy for an index that is in the ERROR step.", + "description": "Retry a policy.\nRetry running the lifecycle policy for an index that is in the ERROR step.\nThe API sets the policy back to the step where the error occurred and runs the step.\nUse the explain lifecycle state API to determine whether an index is in the ERROR step.", "inherits": { "type": { "name": "RequestBase", @@ -122646,7 +122680,7 @@ } ], "query": [], - "specLocation": "ilm/retry/RetryIlmRequest.ts#L23-L31" + "specLocation": "ilm/retry/RetryIlmRequest.ts#L23-L36" }, { "kind": "response", @@ -122674,7 +122708,7 @@ "body": { "kind": "no_body" }, - "description": "Start the index lifecycle management (ILM) plugin.", + "description": "Start the ILM plugin.\nStart the index lifecycle management plugin if it is currently stopped.\nILM is started automatically when the cluster is formed.\nRestarting ILM is necessary only when it has been stopped using the stop ILM API.", "inherits": { "type": { "name": "RequestBase", @@ -122710,7 +122744,7 @@ } } ], - "specLocation": "ilm/start/StartIlmRequest.ts#L23-L32" + "specLocation": "ilm/start/StartIlmRequest.ts#L23-L37" }, { "kind": "response", @@ -122738,7 +122772,7 @@ "body": { "kind": "no_body" }, - "description": "Halts all lifecycle management operations and stops the index lifecycle management (ILM) plugin", + "description": "Stop the ILM plugin.\nHalt all lifecycle management operations and stop the index lifecycle management plugin.\nThis is useful when you are performing maintenance on the cluster and need to prevent ILM from performing any actions on your indices.\n\nThe API returns as soon as the stop request has been acknowledged, but the plugin might continue to run until in-progress operations complete and the plugin can be safely stopped.\nUse the get ILM status API to check whether ILM is running.", "inherits": { "type": { "name": "RequestBase", @@ -122774,7 +122808,7 @@ } } ], - "specLocation": "ilm/stop/StopIlmRequest.ts#L23-L32" + "specLocation": "ilm/stop/StopIlmRequest.ts#L23-L39" }, { "kind": "response", @@ -130359,7 +130393,7 @@ "body": { "kind": "no_body" }, - "description": "Get the status for a data stream lifecycle.\nRetrieves information about an index or data stream’s current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.", + "description": "Get the status for a data stream lifecycle.\nGet information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.", "inherits": { "type": { "name": "RequestBase", diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 11cf6f19cd..e2f4e2bba2 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -197,6 +197,7 @@ ilm-delete-lifecycle,https://www.elastic.co/guide/en/elasticsearch/reference/{br ilm-explain-lifecycle,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ilm-explain-lifecycle.html ilm-get-lifecycle,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ilm-get-lifecycle.html ilm-get-status,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ilm-get-status.html +ilm-index-lifecycle,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ilm-index-lifecycle.html ilm-migrate-to-data-tiers,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ilm-migrate-to-data-tiers.html ilm-move-to-step,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ilm-move-to-step.html ilm-put-lifecycle,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ilm-put-lifecycle.html @@ -271,6 +272,7 @@ mapping-source-field,https://www.elastic.co/guide/en/elasticsearch/reference/{br mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping.html mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping.html mean-reciprocal,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html#_mean_reciprocal_rank +migrate-index-allocation-filters,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/migrate-index-allocation-filters.html migration-api-deprecation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/migration-api-deprecation.html migration-api-feature-upgrade,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/migration-api-feature-upgrade.html ml-apis,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ml-apis.html diff --git a/specification/ilm/delete_lifecycle/DeleteLifecycleRequest.ts b/specification/ilm/delete_lifecycle/DeleteLifecycleRequest.ts index 42832e44d0..90b4136d16 100644 --- a/specification/ilm/delete_lifecycle/DeleteLifecycleRequest.ts +++ b/specification/ilm/delete_lifecycle/DeleteLifecycleRequest.ts @@ -22,8 +22,8 @@ import { Name } from '@_types/common' import { Duration } from '@_types/Time' /** - * Deletes the specified lifecycle policy definition. You cannot delete policies that are currently in use. If the policy is being used to manage any indices, the request fails and returns an error. - * + * Delete a lifecycle policy. + * You cannot delete policies that are currently in use. If the policy is being used to manage any indices, the request fails and returns an error. * @rest_spec_name ilm.delete_lifecycle * @availability stack since=6.6.0 stability=stable * @cluster_privileges manage_ilm diff --git a/specification/ilm/explain_lifecycle/ExplainLifecycleRequest.ts b/specification/ilm/explain_lifecycle/ExplainLifecycleRequest.ts index d981a4f62c..7eacbdaf41 100644 --- a/specification/ilm/explain_lifecycle/ExplainLifecycleRequest.ts +++ b/specification/ilm/explain_lifecycle/ExplainLifecycleRequest.ts @@ -22,7 +22,11 @@ import { IndexName } from '@_types/common' import { Duration } from '@_types/Time' /** - * Retrieves information about the index’s current lifecycle state, such as the currently executing phase, action, and step. Shows when the index entered each one, the definition of the running phase, and information about any failures. + * Explain the lifecycle state. + * Get the current lifecycle status for one or more indices. + * For data streams, the API retrieves the current lifecycle status for the stream's backing indices. + * + * The response indicates when the index entered each lifecycle state, provides the definition of the running phase, and information about any failures. * @rest_spec_name ilm.explain_lifecycle * @availability stack since=6.6.0 stability=stable * @index_privileges view_index_metadata,manage_ilm diff --git a/specification/ilm/get_lifecycle/GetLifecycleRequest.ts b/specification/ilm/get_lifecycle/GetLifecycleRequest.ts index b5cd8e8d03..8af57f8f35 100644 --- a/specification/ilm/get_lifecycle/GetLifecycleRequest.ts +++ b/specification/ilm/get_lifecycle/GetLifecycleRequest.ts @@ -22,7 +22,7 @@ import { Name } from '@_types/common' import { Duration } from '@_types/Time' /** - * Retrieves a lifecycle policy. + * Get lifecycle policies. * @rest_spec_name ilm.get_lifecycle * @availability stack since=6.6.0 stability=stable * @cluster_privileges manage_ilm, read_ilm diff --git a/specification/ilm/get_status/GetIlmStatusRequest.ts b/specification/ilm/get_status/GetIlmStatusRequest.ts index 4cc990cd6b..6c6866bf7a 100644 --- a/specification/ilm/get_status/GetIlmStatusRequest.ts +++ b/specification/ilm/get_status/GetIlmStatusRequest.ts @@ -20,7 +20,10 @@ import { RequestBase } from '@_types/Base' /** + * Get the ILM status. + * Get the current index lifecycle management status. * @rest_spec_name ilm.get_status * @availability stack since=6.6.0 stability=stable + * @cluster_privileges read_ilm */ export interface Request extends RequestBase {} diff --git a/specification/ilm/migrate_to_data_tiers/Request.ts b/specification/ilm/migrate_to_data_tiers/Request.ts index e1a0016a53..163630bea8 100644 --- a/specification/ilm/migrate_to_data_tiers/Request.ts +++ b/specification/ilm/migrate_to_data_tiers/Request.ts @@ -20,12 +20,23 @@ import { RequestBase } from '@_types/Base' /** - * Switches the indices, ILM policies, and legacy, composable and component templates from using custom node attributes and - * attribute-based allocation filters to using data tiers, and optionally deletes one legacy index template.+ + * Migrate to data tiers routing. + * Switch the indices, ILM policies, and legacy, composable, and component templates from using custom node attributes and attribute-based allocation filters to using data tiers. + * Optionally, delete one legacy index template. * Using node roles enables ILM to automatically move the indices between data tiers. * + * Migrating away from custom node attributes routing can be manually performed. + * This API provides an automated way of performing three out of the four manual steps listed in the migration guide: + * + * 1. Stop setting the custom hot attribute on new indices. + * 1. Remove custom allocation settings from existing ILM policies. + * 1. Replace custom allocation settings from existing indices with the corresponding tier preference. + * + * ILM must be stopped before performing the migration. + * Use the stop ILM and get ILM status APIs to wait until the reported operation mode is `STOPPED`. * @rest_spec_name ilm.migrate_to_data_tiers * @availability stack since=7.14.0 stability=stable + * @ext_doc_id migrate-index-allocation-filters */ export interface Request extends RequestBase { query_parameters: { diff --git a/specification/ilm/move_to_step/MoveToStepRequest.ts b/specification/ilm/move_to_step/MoveToStepRequest.ts index d2d5f305ea..6c29091798 100644 --- a/specification/ilm/move_to_step/MoveToStepRequest.ts +++ b/specification/ilm/move_to_step/MoveToStepRequest.ts @@ -22,8 +22,23 @@ import { IndexName } from '@_types/common' import { StepKey } from './types' /** + * Move to a lifecycle step. + * Manually move an index into a specific step in the lifecycle policy and run that step. + * + * WARNING: This operation can result in the loss of data. Manually moving an index into a specific step runs that step even if it has already been performed. This is a potentially destructive action and this should be considered an expert level API. + * + * You must specify both the current step and the step to be executed in the body of the request. + * The request will fail if the current step does not match the step currently running for the index + * This is to prevent the index from being moved from an unexpected step into the next step. + * + * When specifying the target (`next_step`) to which the index will be moved, either the name or both the action and name fields are optional. + * If only the phase is specified, the index will move to the first step of the first action in the target phase. + * If the phase and action are specified, the index will move to the first step of the specified action in the specified phase. + * Only actions specified in the ILM policy are considered valid. + * An index cannot move to a step that is not part of its policy. * @rest_spec_name ilm.move_to_step * @availability stack since=6.6.0 stability=stable + * @index_privileges manage_ilm */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/ilm/put_lifecycle/PutLifecycleRequest.ts b/specification/ilm/put_lifecycle/PutLifecycleRequest.ts index 3247d4921c..b9c2e24caa 100644 --- a/specification/ilm/put_lifecycle/PutLifecycleRequest.ts +++ b/specification/ilm/put_lifecycle/PutLifecycleRequest.ts @@ -23,11 +23,15 @@ import { Name } from '@_types/common' import { Duration } from '@_types/Time' /** - * Creates a lifecycle policy. If the specified policy exists, the policy is replaced and the policy version is incremented. + * Create or update a lifecycle policy. + * If the specified policy exists, it is replaced and the policy version is incremented. + * + * NOTE: Only the latest version of the policy is stored, you cannot revert to previous versions. * @rest_spec_name ilm.put_lifecycle * @availability stack since=6.6.0 stability=stable * @cluster_privileges manage_ilm * @index_privileges manage + * @ext_doc_id ilm-index-lifecycle */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/ilm/remove_policy/RemovePolicyRequest.ts b/specification/ilm/remove_policy/RemovePolicyRequest.ts index 3731e71d7a..f22a56823b 100644 --- a/specification/ilm/remove_policy/RemovePolicyRequest.ts +++ b/specification/ilm/remove_policy/RemovePolicyRequest.ts @@ -21,8 +21,12 @@ import { RequestBase } from '@_types/Base' import { IndexName } from '@_types/common' /** + * Remove policies from an index. + * Remove the assigned lifecycle policies from an index or a data stream's backing indices. + * It also stops managing the indices. * @rest_spec_name ilm.remove_policy * @availability stack since=6.6.0 stability=stable + * @index_privileges manage_ilm */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/ilm/retry/RetryIlmRequest.ts b/specification/ilm/retry/RetryIlmRequest.ts index e79c91827a..0dddce7d28 100644 --- a/specification/ilm/retry/RetryIlmRequest.ts +++ b/specification/ilm/retry/RetryIlmRequest.ts @@ -21,8 +21,13 @@ import { RequestBase } from '@_types/Base' import { IndexName } from '@_types/common' /** + * Retry a policy. + * Retry running the lifecycle policy for an index that is in the ERROR step. + * The API sets the policy back to the step where the error occurred and runs the step. + * Use the explain lifecycle state API to determine whether an index is in the ERROR step. * @rest_spec_name ilm.retry * @availability stack since=6.6.0 stability=stable + * @index_privileges manage_ilm */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/ilm/start/StartIlmRequest.ts b/specification/ilm/start/StartIlmRequest.ts index d99341e69b..aaa44be924 100644 --- a/specification/ilm/start/StartIlmRequest.ts +++ b/specification/ilm/start/StartIlmRequest.ts @@ -21,8 +21,13 @@ import { RequestBase } from '@_types/Base' import { Duration } from '@_types/Time' /** + * Start the ILM plugin. + * Start the index lifecycle management plugin if it is currently stopped. + * ILM is started automatically when the cluster is formed. + * Restarting ILM is necessary only when it has been stopped using the stop ILM API. * @rest_spec_name ilm.start * @availability stack since=6.6.0 stability=stable + * @cluster_privileges manage_ilm */ export interface Request extends RequestBase { query_parameters: { diff --git a/specification/ilm/stop/StopIlmRequest.ts b/specification/ilm/stop/StopIlmRequest.ts index 10b24b699c..3f20ae5795 100644 --- a/specification/ilm/stop/StopIlmRequest.ts +++ b/specification/ilm/stop/StopIlmRequest.ts @@ -21,8 +21,15 @@ import { RequestBase } from '@_types/Base' import { Duration } from '@_types/Time' /** + * Stop the ILM plugin. + * Halt all lifecycle management operations and stop the index lifecycle management plugin. + * This is useful when you are performing maintenance on the cluster and need to prevent ILM from performing any actions on your indices. + * + * The API returns as soon as the stop request has been acknowledged, but the plugin might continue to run until in-progress operations complete and the plugin can be safely stopped. + * Use the get ILM status API to check whether ILM is running. * @rest_spec_name ilm.stop * @availability stack since=6.6.0 stability=stable + * @cluster_privileges manage_ilm */ export interface Request extends RequestBase { query_parameters: { diff --git a/specification/indices/explain_data_lifecycle/IndicesExplainDataLifecycleRequest.ts b/specification/indices/explain_data_lifecycle/IndicesExplainDataLifecycleRequest.ts index afb8dd1f8b..299f7ab3b6 100644 --- a/specification/indices/explain_data_lifecycle/IndicesExplainDataLifecycleRequest.ts +++ b/specification/indices/explain_data_lifecycle/IndicesExplainDataLifecycleRequest.ts @@ -23,7 +23,7 @@ import { Duration } from '@_types/Time' /** * Get the status for a data stream lifecycle. - * Retrieves information about an index or data stream’s current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution. + * Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution. * @rest_spec_name indices.explain_data_lifecycle * @availability stack since=8.11.0 stability=stable * @availability serverless stability=stable visibility=public