From 748fb196dc2033b05d34afc4dfb39a00cc998da2 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 9 Jan 2025 12:05:13 -0800 Subject: [PATCH] Add SLM API examples (#3470) (#3501) Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --------- Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> (cherry picked from commit 41ea7416dac6384455a230f67fe63ab4424324d9) Co-authored-by: Lisa Cawley --- output/openapi/elasticsearch-openapi.json | 32 +++---- output/schema/schema.json | 94 +++++++++++-------- specification/slm/_types/SnapshotLifecycle.ts | 10 ++ .../DeleteSnapshotLifecycleRequest.ts | 7 +- .../ExecuteSnapshotLifecycleRequest.ts | 7 +- ...cuteSnapshotLifecycleResponseExample1.yaml | 8 ++ .../ExecuteRetentionRequest.ts | 7 +- .../GetSnapshotLifecycleRequest.ts | 7 +- .../GetSnapshotLifecycleResponseExample1.yaml | 17 ++++ .../GetSnapshotLifecycleStatsRequest.ts | 1 + ...ecycleManagementStatsResponseExample1.yaml | 17 ++++ ...napshotLifecycleManagementStatusRequest.ts | 9 +- ...cycleManagementStatusResponseExample1.yaml | 5 + .../PutSnapshotLifecycleRequest.ts | 9 +- ...SnapshotLifecycleRequestExample1 copy.yaml | 13 +++ .../PutSnapshotLifecycleRequestExample2.yaml | 16 ++++ ...StartSnapshotLifecycleManagementRequest.ts | 9 +- ...otLifecycleManagementResponseExample1.yaml | 5 + .../StopSnapshotLifecycleManagementRequest.ts | 9 +- 19 files changed, 209 insertions(+), 73 deletions(-) create mode 100644 specification/slm/execute_lifecycle/examples/response/ExecuteSnapshotLifecycleResponseExample1.yaml create mode 100644 specification/slm/get_lifecycle/examples/response/GetSnapshotLifecycleResponseExample1.yaml create mode 100644 specification/slm/get_stats/examples/response/GetSnapshotLifecycleManagementStatsResponseExample1.yaml create mode 100644 specification/slm/get_status/examples/response/GetSnapshotLifecycleManagementStatusResponseExample1.yaml create mode 100644 specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample1 copy.yaml create mode 100644 specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample2.yaml create mode 100644 specification/slm/start/examples/response/StartSnapshotLifecycleManagementResponseExample1.yaml diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 2ff372f577..091c81fa68 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -32615,7 +32615,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -32625,7 +32625,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -32696,7 +32696,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -32706,7 +32706,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -32752,7 +32752,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -32762,7 +32762,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -32805,7 +32805,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -32815,7 +32815,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -32965,7 +32965,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -32975,7 +32975,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -33018,7 +33018,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -33028,7 +33028,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -33063,7 +33063,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -33073,7 +33073,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -104590,7 +104590,7 @@ "slm.get_lifecycle#master_timeout": { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -104600,7 +104600,7 @@ "slm.get_lifecycle#timeout": { "in": "query", "name": "timeout", - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" diff --git a/output/schema/schema.json b/output/schema/schema.json index 76c908618e..392024c566 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -18463,7 +18463,8 @@ } }, "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", + "docId": "slm-api-delete-policy", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-delete-policy.html", "name": "slm.delete_lifecycle", "privileges": { "cluster": [ @@ -18503,7 +18504,8 @@ } }, "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", + "docId": "slm-api-execute-lifecycle", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-execute-lifecycle.html", "name": "slm.execute_lifecycle", "privileges": { "cluster": [ @@ -18543,7 +18545,8 @@ } }, "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", + "docId": "slm-api-execute-retention", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-execute-retention.html", "name": "slm.execute_retention", "privileges": { "cluster": [ @@ -18583,7 +18586,8 @@ } }, "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", + "docId": "slm-api-get-policy", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-get-policy.html", "name": "slm.get_lifecycle", "privileges": { "cluster": [ @@ -18629,7 +18633,8 @@ } }, "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", + "docId": "slm-api-get-stats", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-get-stats.html", "name": "slm.get_stats", "privileges": { "cluster": [ @@ -18669,7 +18674,8 @@ } }, "description": "Get the snapshot lifecycle management status.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-get-status.html", + "docId": "slm-api-get-status", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-get-status.html", "name": "slm.get_status", "privileges": { "cluster": [ @@ -18709,7 +18715,8 @@ } }, "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", + "docId": "slm-api-put-policy", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-put-policy.html", "name": "slm.put_lifecycle", "privileges": { "cluster": [ @@ -18755,7 +18762,8 @@ } }, "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", + "docId": "slm-api-start", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-start.html", "name": "slm.start", "privileges": { "cluster": [ @@ -18795,7 +18803,8 @@ } }, "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", + "docId": "slm-api-stop", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-stop.html", "name": "slm.stop", "request": { "name": "Request", @@ -204127,7 +204136,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L99-L129" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L109-L139" }, { "kind": "interface", @@ -204190,7 +204199,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L131-L136" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L141-L146" }, { "kind": "interface", @@ -204222,7 +204231,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L138-L141" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L148-L151" }, { "kind": "interface", @@ -204287,7 +204296,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L76-L82" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L86-L92" }, { "kind": "interface", @@ -204333,7 +204342,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L84-L97" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L94-L107" }, { "kind": "interface", @@ -204376,6 +204385,7 @@ } }, { + "description": "The last time the policy was modified.", "name": "modified_date", "required": false, "type": { @@ -204407,6 +204417,7 @@ } }, { + "description": "The next time the policy will run.", "name": "next_execution", "required": false, "type": { @@ -204449,6 +204460,7 @@ } }, { + "description": "The version of the snapshot policy.\nOnly the latest version is stored and incremented when the policy is updated.", "name": "version", "required": true, "type": { @@ -204471,7 +204483,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L38-L49" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L38-L59" }, { "kind": "interface", @@ -204612,7 +204624,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L51-L74" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L61-L84" }, { "kind": "request", @@ -204649,7 +204661,7 @@ ], "query": [ { - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -204662,7 +204674,7 @@ } }, { - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -204675,7 +204687,7 @@ } } ], - "specLocation": "slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts#L24-L49" + "specLocation": "slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts#L24-L52" }, { "kind": "response", @@ -204730,7 +204742,7 @@ ], "query": [ { - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -204743,7 +204755,7 @@ } }, { - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -204756,7 +204768,7 @@ } } ], - "specLocation": "slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts#L24-L49" + "specLocation": "slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts#L24-L52" }, { "kind": "response", @@ -204804,7 +204816,7 @@ "path": [], "query": [ { - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -204817,7 +204829,7 @@ } }, { - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -204830,7 +204842,7 @@ } } ], - "specLocation": "slm/execute_retention/ExecuteRetentionRequest.ts#L23-L45" + "specLocation": "slm/execute_retention/ExecuteRetentionRequest.ts#L23-L48" }, { "kind": "response", @@ -204885,7 +204897,7 @@ ], "query": [ { - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -204898,7 +204910,7 @@ } }, { - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -204911,7 +204923,7 @@ } } ], - "specLocation": "slm/get_lifecycle/GetSnapshotLifecycleRequest.ts#L24-L51" + "specLocation": "slm/get_lifecycle/GetSnapshotLifecycleRequest.ts#L24-L54" }, { "kind": "response", @@ -204990,7 +205002,7 @@ } } ], - "specLocation": "slm/get_stats/GetSnapshotLifecycleStatsRequest.ts#L23-L44" + "specLocation": "slm/get_stats/GetSnapshotLifecycleStatsRequest.ts#L23-L45" }, { "kind": "response", @@ -205149,7 +205161,7 @@ "path": [], "query": [ { - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -205162,7 +205174,7 @@ } }, { - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -205175,7 +205187,7 @@ } } ], - "specLocation": "slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts#L23-L43" + "specLocation": "slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts#L23-L48" }, { "kind": "response", @@ -205298,7 +205310,7 @@ ], "query": [ { - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -205311,7 +205323,7 @@ } }, { - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -205324,7 +205336,7 @@ } } ], - "specLocation": "slm/put_lifecycle/PutSnapshotLifecycleRequest.ts#L26-L78" + "specLocation": "slm/put_lifecycle/PutSnapshotLifecycleRequest.ts#L26-L83" }, { "kind": "response", @@ -205366,7 +205378,7 @@ "path": [], "query": [ { - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -205379,7 +205391,7 @@ } }, { - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -205392,7 +205404,7 @@ } } ], - "specLocation": "slm/start/StartSnapshotLifecycleManagementRequest.ts#L23-L45" + "specLocation": "slm/start/StartSnapshotLifecycleManagementRequest.ts#L23-L50" }, { "kind": "response", @@ -205434,7 +205446,7 @@ "path": [], "query": [ { - "description": "Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -205447,7 +205459,7 @@ } }, { - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -205460,7 +205472,7 @@ } } ], - "specLocation": "slm/stop/StopSnapshotLifecycleManagementRequest.ts#L23-L49" + "specLocation": "slm/stop/StopSnapshotLifecycleManagementRequest.ts#L23-L54" }, { "kind": "response", diff --git a/specification/slm/_types/SnapshotLifecycle.ts b/specification/slm/_types/SnapshotLifecycle.ts index 9d46e2ca14..70e3e7b46e 100644 --- a/specification/slm/_types/SnapshotLifecycle.ts +++ b/specification/slm/_types/SnapshotLifecycle.ts @@ -39,11 +39,21 @@ export class SnapshotLifecycle { in_progress?: InProgress last_failure?: Invocation last_success?: Invocation + /** + * The last time the policy was modified. + */ modified_date?: DateTime modified_date_millis: EpochTime + /** + * The next time the policy will run. + */ next_execution?: DateTime next_execution_millis: EpochTime policy: Policy + /** + * The version of the snapshot policy. + * Only the latest version is stored and incremented when the policy is updated. + */ version: VersionNumber stats: Statistics } diff --git a/specification/slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts b/specification/slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts index 8c73037abd..8f85357d8d 100644 --- a/specification/slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts +++ b/specification/slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts @@ -29,6 +29,7 @@ import { Duration } from '@_types/Time' * @availability stack since=7.4.0 stability=stable * @availability serverless stability=stable visibility=private * @cluster_privileges manage_slm + * @doc_id slm-api-delete-policy */ export interface Request extends RequestBase { path_parts: { @@ -36,12 +37,14 @@ export interface Request extends RequestBase { } query_parameters: { /** - * Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */ master_timeout?: Duration /** - * Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */ timeout?: Duration diff --git a/specification/slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts b/specification/slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts index 719319c97b..13099170cf 100644 --- a/specification/slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts +++ b/specification/slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts @@ -29,6 +29,7 @@ import { Duration } from '@_types/Time' * @availability stack since=7.4.0 stability=stable * @availability serverless stability=stable visibility=private * @cluster_privileges manage_slm + * @doc_id slm-api-execute-lifecycle */ export interface Request extends RequestBase { path_parts: { @@ -36,12 +37,14 @@ export interface Request extends RequestBase { } query_parameters: { /** - * Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */ master_timeout?: Duration /** - * Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */ timeout?: Duration diff --git a/specification/slm/execute_lifecycle/examples/response/ExecuteSnapshotLifecycleResponseExample1.yaml b/specification/slm/execute_lifecycle/examples/response/ExecuteSnapshotLifecycleResponseExample1.yaml new file mode 100644 index 0000000000..d8d5b9bd5e --- /dev/null +++ b/specification/slm/execute_lifecycle/examples/response/ExecuteSnapshotLifecycleResponseExample1.yaml @@ -0,0 +1,8 @@ +# summary: +description: > + Run `POST /_slm/policy/daily-snapshots/_execute` to take an immediate snapshot according to the `daily-snapshots` policy. +# type: response +# response_code: '' +value: + "{\n \"snapshot_name\": \"daily-snap-2019.04.24-gwrqoo2xtea3q57vvg0uea\"\n\ + }" diff --git a/specification/slm/execute_retention/ExecuteRetentionRequest.ts b/specification/slm/execute_retention/ExecuteRetentionRequest.ts index f6e5973918..e060bc35c0 100644 --- a/specification/slm/execute_retention/ExecuteRetentionRequest.ts +++ b/specification/slm/execute_retention/ExecuteRetentionRequest.ts @@ -28,16 +28,19 @@ import { Duration } from '@_types/Time' * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=private * @cluster_privileges manage_slm + * @doc_id slm-api-execute-retention */ export interface Request extends RequestBase { query_parameters: { /** - * Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */ master_timeout?: Duration /** - * Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */ timeout?: Duration diff --git a/specification/slm/get_lifecycle/GetSnapshotLifecycleRequest.ts b/specification/slm/get_lifecycle/GetSnapshotLifecycleRequest.ts index f04c26b874..ec0b63e7e5 100644 --- a/specification/slm/get_lifecycle/GetSnapshotLifecycleRequest.ts +++ b/specification/slm/get_lifecycle/GetSnapshotLifecycleRequest.ts @@ -28,6 +28,7 @@ import { Duration } from '@_types/Time' * @availability stack since=7.4.0 stability=stable * @availability serverless stability=stable visibility=private * @cluster_privileges manage_slm + * @doc_id slm-api-get-policy */ export interface Request extends RequestBase { path_parts: { @@ -38,12 +39,14 @@ export interface Request extends RequestBase { } query_parameters: { /** - * Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */ master_timeout?: Duration /** - * Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */ timeout?: Duration diff --git a/specification/slm/get_lifecycle/examples/response/GetSnapshotLifecycleResponseExample1.yaml b/specification/slm/get_lifecycle/examples/response/GetSnapshotLifecycleResponseExample1.yaml new file mode 100644 index 0000000000..f06ec0ac23 --- /dev/null +++ b/specification/slm/get_lifecycle/examples/response/GetSnapshotLifecycleResponseExample1.yaml @@ -0,0 +1,17 @@ +summary: +description: A successful response from `GET _slm/policy/daily-snapshots?human`. +# type: response +# response_code: '' +value: + "{\n \"daily-snapshots\": {\n \"version\": 1,\n \"modified_date\": \"\ + 2099-05-06T01:30:00.000Z\",\n \"modified_date_millis\": 4081757400000,\n \"\ + policy\" : {\n \"schedule\": \"0 30 1 * * ?\",\n \"name\": \"\"\ + ,\n \"repository\": \"my_repository\",\n \"config\": {\n \"indices\"\ + : [\"data-*\", \"important\"],\n \"ignore_unavailable\": false,\n \ + \ \"include_global_state\": false\n },\n \"retention\": {\n \"\ + expire_after\": \"30d\",\n \"min_count\": 5,\n \"max_count\": 50\n\ + \ }\n },\n \"stats\": {\n \"policy\": \"daily-snapshots\",\n \ + \ \"snapshots_taken\": 0,\n \"snapshots_failed\": 0,\n \"snapshots_deleted\"\ + : 0,\n \"snapshot_deletion_failures\": 0\n },\n \"next_execution\": \"\ + 2099-05-07T01:30:00.000Z\",\n \"next_execution_millis\": 4081843800000\n }\n\ + }" diff --git a/specification/slm/get_stats/GetSnapshotLifecycleStatsRequest.ts b/specification/slm/get_stats/GetSnapshotLifecycleStatsRequest.ts index 12a0f69110..6035aa04f1 100644 --- a/specification/slm/get_stats/GetSnapshotLifecycleStatsRequest.ts +++ b/specification/slm/get_stats/GetSnapshotLifecycleStatsRequest.ts @@ -27,6 +27,7 @@ import { Duration } from '@_types/Time' * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=private * @cluster_privileges manage_slm + * @doc_id slm-api-get-stats */ export interface Request extends RequestBase { query_parameters: { diff --git a/specification/slm/get_stats/examples/response/GetSnapshotLifecycleManagementStatsResponseExample1.yaml b/specification/slm/get_stats/examples/response/GetSnapshotLifecycleManagementStatsResponseExample1.yaml new file mode 100644 index 0000000000..66e9de8ba0 --- /dev/null +++ b/specification/slm/get_stats/examples/response/GetSnapshotLifecycleManagementStatsResponseExample1.yaml @@ -0,0 +1,17 @@ +# summary: +description: A successful response from `GET /_slm/stats`. +# type: response +# response_code: '' +value: |- + { + "retention_runs": 13, + "retention_failed": 0, + "retention_timed_out": 0, + "retention_deletion_time": "1.4s", + "retention_deletion_time_millis": 1404, + "policy_stats": [ ], + "total_snapshots_taken": 1, + "total_snapshots_failed": 1, + "total_snapshots_deleted": 0, + "total_snapshot_deletion_failures": 0 + } diff --git a/specification/slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts b/specification/slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts index d633936cda..d226ec566a 100644 --- a/specification/slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts +++ b/specification/slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts @@ -26,16 +26,21 @@ import { Duration } from '@_types/Time' * @availability stack since=7.6.0 stability=stable * @availability serverless stability=stable visibility=private * @cluster_privileges read_slm + * @doc_id slm-api-get-status */ export interface Request extends RequestBase { query_parameters: { /** - * Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. + * To indicate that the request should never timeout, set it to `-1`. * @server_default 30s */ master_timeout?: Duration /** - * Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. + * To indicate that the request should never timeout, set it to `-1`. * @server_default 30s */ timeout?: Duration diff --git a/specification/slm/get_status/examples/response/GetSnapshotLifecycleManagementStatusResponseExample1.yaml b/specification/slm/get_status/examples/response/GetSnapshotLifecycleManagementStatusResponseExample1.yaml new file mode 100644 index 0000000000..b40e5e68ee --- /dev/null +++ b/specification/slm/get_status/examples/response/GetSnapshotLifecycleManagementStatusResponseExample1.yaml @@ -0,0 +1,5 @@ +# summary: +description: A successful response from `GET _slm/status`. +# type: response +# response_code: '' +value: "{\n \"operation_mode\": \"RUNNING\"\n}" diff --git a/specification/slm/put_lifecycle/PutSnapshotLifecycleRequest.ts b/specification/slm/put_lifecycle/PutSnapshotLifecycleRequest.ts index 66e107f2ca..209562edd0 100644 --- a/specification/slm/put_lifecycle/PutSnapshotLifecycleRequest.ts +++ b/specification/slm/put_lifecycle/PutSnapshotLifecycleRequest.ts @@ -33,6 +33,7 @@ import { Duration } from '@_types/Time' * @availability serverless stability=stable visibility=private * @cluster_privileges manage_slm * @index_privileges manage + * @doc_id slm-api-put-policy */ export interface Request extends RequestBase { path_parts: { @@ -43,12 +44,16 @@ export interface Request extends RequestBase { } query_parameters: { /** - * Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. + * To indicate that the request should never timeout, set it to `-1`. * @server_default 30s */ master_timeout?: Duration /** - * Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. + * To indicate that the request should never timeout, set it to `-1`. * @server_default 30s */ timeout?: Duration diff --git a/specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample1 copy.yaml b/specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample1 copy.yaml new file mode 100644 index 0000000000..d532444b36 --- /dev/null +++ b/specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample1 copy.yaml @@ -0,0 +1,13 @@ +summary: Create a policy +# method_request: PUT /_slm/policy/daily-snapshots +description: > + Run `PUT /_slm/policy/daily-snapshots` to create a lifecycle policy. + The `schedule` is when the snapshot should be taken, in this case, 1:30am daily. + The `retention` details specify to: keep snapshots for 30 days; always keep at least 5 successful snapshots, even if they're more than 30 days old; keep no more than 50 successful snapshots, even if they're less than 30 days old. +# type: request +value: + "{\n \"schedule\": \"0 30 1 * * ?\",\n \"name\": \"\"\ + ,\n \"repository\": \"my_repository\",\n \"config\": {\n \"indices\": [\"data-*\"\ + , \"important\"],\n \"ignore_unavailable\": false,\n \"include_global_state\"\ + : false\n },\n \"retention\": {\n \"expire_after\": \"30d\",\n \"min_count\"\ + : 5,\n \"max_count\": 50\n }\n}" diff --git a/specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample2.yaml b/specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample2.yaml new file mode 100644 index 0000000000..802bed5cec --- /dev/null +++ b/specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample2.yaml @@ -0,0 +1,16 @@ +summary: Create a policy with intevals +# method_request: PUT /_slm/policy/hourly-snapshots +description: > + Run `PUT /_slm/policy/hourly-snapshots` to create a lifecycle policy that uses interval scheduling. + It creates a snapshot once every hour. + The first snapshot will be created one hour after the policy is modified, with subsequent snapshots every hour afterward. +# type: request +value: |- + { + "schedule": "1h", + "name": "", + "repository": "my_repository", + "config": { + "indices": ["data-*", "important"] + } + } diff --git a/specification/slm/start/StartSnapshotLifecycleManagementRequest.ts b/specification/slm/start/StartSnapshotLifecycleManagementRequest.ts index c4d3431715..345c28c25d 100644 --- a/specification/slm/start/StartSnapshotLifecycleManagementRequest.ts +++ b/specification/slm/start/StartSnapshotLifecycleManagementRequest.ts @@ -28,16 +28,21 @@ import { Duration } from '@_types/Time' * @availability stack since=7.6.0 stability=stable * @availability serverless stability=stable visibility=private * @cluster_privileges manage_slm + * @doc_id slm-api-start */ export interface Request extends RequestBase { query_parameters: { /** - * Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. + * To indicate that the request should never timeout, set it to `-1`. * @server_default 30s */ master_timeout?: Duration /** - * Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. + * To indicate that the request should never timeout, set it to `-1`. * @server_default 30s */ timeout?: Duration diff --git a/specification/slm/start/examples/response/StartSnapshotLifecycleManagementResponseExample1.yaml b/specification/slm/start/examples/response/StartSnapshotLifecycleManagementResponseExample1.yaml new file mode 100644 index 0000000000..b21929e48d --- /dev/null +++ b/specification/slm/start/examples/response/StartSnapshotLifecycleManagementResponseExample1.yaml @@ -0,0 +1,5 @@ +# summary: +description: A successful response from `POST _slm/start`. +# type: response +# response_code: '' +value: "{\n \"acknowledged\": true\n}" diff --git a/specification/slm/stop/StopSnapshotLifecycleManagementRequest.ts b/specification/slm/stop/StopSnapshotLifecycleManagementRequest.ts index 8436aead0d..f70b736281 100644 --- a/specification/slm/stop/StopSnapshotLifecycleManagementRequest.ts +++ b/specification/slm/stop/StopSnapshotLifecycleManagementRequest.ts @@ -32,16 +32,21 @@ import { Duration } from '@_types/Time' * @rest_spec_name slm.stop * @availability stack since=7.6.0 stability=stable * @availability serverless stability=stable visibility=private + * @doc_id slm-api-stop */ export interface Request extends RequestBase { query_parameters: { /** - * Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. + * To indicate that the request should never timeout, set it to `-1`. * @server_default 30s */ master_timeout?: Duration /** - * Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. + * To indicate that the request should never timeout, set it to `-1`. * @server_default 30s */ timeout?: Duration