From 19e6ee4a9f0fdaf685baeeab1bbb4f67c8c74a1d Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 8 Jan 2025 08:05:16 -0800 Subject: [PATCH 1/4] Add SLM API examples --- output/schema/schema.json | 5 +++-- .../put_lifecycle/PutSnapshotLifecycleRequest.ts | 1 + ...PutSnapshotLifecycleRequestExample1 copy.yaml | 13 +++++++++++++ .../PutSnapshotLifecycleRequestExample2.yaml | 16 ++++++++++++++++ 4 files changed, 33 insertions(+), 2 deletions(-) create mode 100644 specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample1 copy.yaml create mode 100644 specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample2.yaml diff --git a/output/schema/schema.json b/output/schema/schema.json index e9db5474ac..7486ad8a45 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -18591,7 +18591,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": [ @@ -205112,7 +205113,7 @@ } } ], - "specLocation": "slm/put_lifecycle/PutSnapshotLifecycleRequest.ts#L26-L78" + "specLocation": "slm/put_lifecycle/PutSnapshotLifecycleRequest.ts#L26-L79" }, { "kind": "response", diff --git a/specification/slm/put_lifecycle/PutSnapshotLifecycleRequest.ts b/specification/slm/put_lifecycle/PutSnapshotLifecycleRequest.ts index 66e107f2ca..8a12048308 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: { 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..3e9c9412ca --- /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 being created every hour afterward. +# type: request +value: |- + { + "schedule": "1h", + "name": "", + "repository": "my_repository", + "config": { + "indices": ["data-*", "important"] + } + } From 3a3da6d922d27167ae583e8b73944d33045eb708 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 8 Jan 2025 10:17:59 -0800 Subject: [PATCH 2/4] Add more examples --- specification/slm/_types/SnapshotLifecycle.ts | 10 ++++++++++ .../DeleteSnapshotLifecycleRequest.ts | 7 +++++-- .../ExecuteSnapshotLifecycleRequest.ts | 7 +++++-- ...xecuteSnapshotLifecycleResponseExample1.yaml | 8 ++++++++ .../ExecuteRetentionRequest.ts | 7 +++++-- .../GetSnapshotLifecycleRequest.ts | 7 +++++-- .../GetSnapshotLifecycleResponseExample1.yaml | 17 +++++++++++++++++ .../GetSnapshotLifecycleStatsRequest.ts | 1 + ...ifecycleManagementStatsResponseExample1.yaml | 17 +++++++++++++++++ ...tSnapshotLifecycleManagementStatusRequest.ts | 9 +++++++-- ...fecycleManagementStatusResponseExample1.yaml | 5 +++++ .../PutSnapshotLifecycleRequest.ts | 8 ++++++-- .../StartSnapshotLifecycleManagementRequest.ts | 9 +++++++-- ...shotLifecycleManagementResponseExample1.yaml | 5 +++++ .../StopSnapshotLifecycleManagementRequest.ts | 9 +++++++-- 15 files changed, 110 insertions(+), 16 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/start/examples/response/StartSnapshotLifecycleManagementResponseExample1.yaml 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 8a12048308..209562edd0 100644 --- a/specification/slm/put_lifecycle/PutSnapshotLifecycleRequest.ts +++ b/specification/slm/put_lifecycle/PutSnapshotLifecycleRequest.ts @@ -44,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/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 From 1a4b64444745729dfea6f39352c3370948e6199f Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 8 Jan 2025 10:18:33 -0800 Subject: [PATCH 3/4] Generate output --- output/openapi/elasticsearch-openapi.json | 32 ++++---- output/schema/schema.json | 91 +++++++++++++---------- 2 files changed, 67 insertions(+), 56 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index dcfce53610..66ef40e380 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -32633,7 +32633,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" @@ -32643,7 +32643,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" @@ -32714,7 +32714,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" @@ -32724,7 +32724,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" @@ -32770,7 +32770,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" @@ -32780,7 +32780,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" @@ -32823,7 +32823,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" @@ -32833,7 +32833,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" @@ -32983,7 +32983,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" @@ -32993,7 +32993,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" @@ -33036,7 +33036,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" @@ -33046,7 +33046,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" @@ -33081,7 +33081,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" @@ -33091,7 +33091,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" @@ -104405,7 +104405,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" @@ -104415,7 +104415,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 7486ad8a45..9545f7e43b 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -18345,7 +18345,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": [ @@ -18385,7 +18386,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": [ @@ -18425,7 +18427,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": [ @@ -18465,7 +18468,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": [ @@ -18511,7 +18515,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": [ @@ -18551,7 +18556,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": [ @@ -18638,7 +18644,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": [ @@ -18678,7 +18685,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", @@ -203916,7 +203924,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L99-L129" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L109-L139" }, { "kind": "interface", @@ -203979,7 +203987,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L131-L136" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L141-L146" }, { "kind": "interface", @@ -204011,7 +204019,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L138-L141" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L148-L151" }, { "kind": "interface", @@ -204076,7 +204084,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L76-L82" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L86-L92" }, { "kind": "interface", @@ -204122,7 +204130,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L84-L97" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L94-L107" }, { "kind": "interface", @@ -204165,6 +204173,7 @@ } }, { + "description": "The last time the policy was modified.", "name": "modified_date", "required": false, "type": { @@ -204196,6 +204205,7 @@ } }, { + "description": "The next time the policy will run.", "name": "next_execution", "required": false, "type": { @@ -204238,6 +204248,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": { @@ -204260,7 +204271,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L38-L49" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L38-L59" }, { "kind": "interface", @@ -204401,7 +204412,7 @@ } } ], - "specLocation": "slm/_types/SnapshotLifecycle.ts#L51-L74" + "specLocation": "slm/_types/SnapshotLifecycle.ts#L61-L84" }, { "kind": "request", @@ -204438,7 +204449,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", @@ -204451,7 +204462,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", @@ -204464,7 +204475,7 @@ } } ], - "specLocation": "slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts#L24-L49" + "specLocation": "slm/delete_lifecycle/DeleteSnapshotLifecycleRequest.ts#L24-L52" }, { "kind": "response", @@ -204519,7 +204530,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", @@ -204532,7 +204543,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", @@ -204545,7 +204556,7 @@ } } ], - "specLocation": "slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts#L24-L49" + "specLocation": "slm/execute_lifecycle/ExecuteSnapshotLifecycleRequest.ts#L24-L52" }, { "kind": "response", @@ -204593,7 +204604,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", @@ -204606,7 +204617,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", @@ -204619,7 +204630,7 @@ } } ], - "specLocation": "slm/execute_retention/ExecuteRetentionRequest.ts#L23-L45" + "specLocation": "slm/execute_retention/ExecuteRetentionRequest.ts#L23-L48" }, { "kind": "response", @@ -204674,7 +204685,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", @@ -204687,7 +204698,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", @@ -204700,7 +204711,7 @@ } } ], - "specLocation": "slm/get_lifecycle/GetSnapshotLifecycleRequest.ts#L24-L51" + "specLocation": "slm/get_lifecycle/GetSnapshotLifecycleRequest.ts#L24-L54" }, { "kind": "response", @@ -204779,7 +204790,7 @@ } } ], - "specLocation": "slm/get_stats/GetSnapshotLifecycleStatsRequest.ts#L23-L44" + "specLocation": "slm/get_stats/GetSnapshotLifecycleStatsRequest.ts#L23-L45" }, { "kind": "response", @@ -204938,7 +204949,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", @@ -204951,7 +204962,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", @@ -204964,7 +204975,7 @@ } } ], - "specLocation": "slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts#L23-L43" + "specLocation": "slm/get_status/GetSnapshotLifecycleManagementStatusRequest.ts#L23-L48" }, { "kind": "response", @@ -205087,7 +205098,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", @@ -205100,7 +205111,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", @@ -205113,7 +205124,7 @@ } } ], - "specLocation": "slm/put_lifecycle/PutSnapshotLifecycleRequest.ts#L26-L79" + "specLocation": "slm/put_lifecycle/PutSnapshotLifecycleRequest.ts#L26-L83" }, { "kind": "response", @@ -205155,7 +205166,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", @@ -205168,7 +205179,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", @@ -205181,7 +205192,7 @@ } } ], - "specLocation": "slm/start/StartSnapshotLifecycleManagementRequest.ts#L23-L45" + "specLocation": "slm/start/StartSnapshotLifecycleManagementRequest.ts#L23-L50" }, { "kind": "response", @@ -205223,7 +205234,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", @@ -205236,7 +205247,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", @@ -205249,7 +205260,7 @@ } } ], - "specLocation": "slm/stop/StopSnapshotLifecycleManagementRequest.ts#L23-L49" + "specLocation": "slm/stop/StopSnapshotLifecycleManagementRequest.ts#L23-L54" }, { "kind": "response", From 09580d31f9a73dc94e349638dc2b57e232c8facc Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 9 Jan 2025 11:55:56 -0800 Subject: [PATCH 4/4] Update specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample2.yaml Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- .../examples/request/PutSnapshotLifecycleRequestExample2.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample2.yaml b/specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample2.yaml index 3e9c9412ca..802bed5cec 100644 --- a/specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample2.yaml +++ b/specification/slm/put_lifecycle/examples/request/PutSnapshotLifecycleRequestExample2.yaml @@ -3,7 +3,7 @@ summary: Create a policy with intevals 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 being created every hour afterward. + The first snapshot will be created one hour after the policy is modified, with subsequent snapshots every hour afterward. # type: request value: |- {