Add initial documentation for SLM (#41510)

* Add initial documentation for SLM

This adds the initial documentation for snapshot lifecycle management.

It also includes the REST spec API json files since they're sort of
documentation.

Relates to #38461

docs/build.gradle

@@ -42,6 +42,7 @@ integTestCluster {
 
   // enable regexes in painless so our tests don't complain about example snippets that use them
   setting 'script.painless.regex.enabled', 'true'
+  setting 'path.repo', new File(buildDir, "cluster/shared/repo")
   Closure configFile = {
     extraConfigFile it, "src/test/cluster/config/$it"
   }
@@ -1136,3 +1137,13 @@ buildRestTests.setups['seats'] = '''
             {"theatre": "Graye", "cost": 33, "row": 2, "number": 6, "sold": false}
             {"index":{"_id": "4"}}
             {"theatre": "Skyline", "cost": 20, "row": 5, "number": 2, "sold": false}'''
+// Used by snapshot lifecycle management docs
+buildRestTests.setups['setup-repository'] = '''
+  - do:
+      snapshot.create_repository:
+        repository: my_repository
+        body:
+          type: fs
+          settings:
+            location: buildDir/cluster/shared/repo
+'''

docs/reference/ilm/index.asciidoc

@@ -47,6 +47,14 @@ to a single shard.
 hardware.
 . Delete the index once the required 30 day retention period is reached.
 
+*Snapshot Lifecycle Management*
+
+ILM itself does allow managing indices, however, managing snapshots for a set of
+indices is outside of the scope of an index-level policy. Instead, there are
+separate APIs for managing snapshot lifecycles. Please see the
+<<snapshot-lifecycle-management-api,Snapshot Lifecycle Management>>
+documentation for information about configuring snapshots.
+
 [IMPORTANT]
 ===========================
 {ilm} does not support mixed-version cluster usage. Although it

docs/reference/ilm/start-stop-ilm.asciidoc

@@ -10,6 +10,10 @@ maybe there are scheduled maintenance windows when cluster topology
 changes are desired that may impact running ILM actions. For this reason,
 ILM has two ways to disable operations.
 
+When stopping ILM, snapshot lifecycle management operations are also stopped,
+this means that no scheduled snapshots are created (currently ongoing snapshots
+are unaffected).
+
 Normally, ILM will be running by default.
 To see the current operating status of ILM, use the <<ilm-get-status,Get Status API>>
 to see the current state of ILM.

docs/reference/rest-api/index.asciidoc

@@ -12,6 +12,7 @@ directly to configure and access {xpack} features.
 * <<graph-explore-api,Graph Explore API>>
 * <<freeze-index-api>>, <<unfreeze-index-api>>
 * <<index-lifecycle-management-api,Index lifecycle management APIs>>
+* <<snapshot-lifecycle-management-api,Snapshot lifecycle management APIs>>
 * <<licensing-apis,Licensing APIs>>
 * <<ml-apis,Machine Learning APIs>>
 * <<security-api,Security APIs>>
@@ -27,6 +28,7 @@ include::{es-repo-dir}/data-frames/apis/index.asciidoc[]
 include::{es-repo-dir}/graph/explore.asciidoc[]
 include::{es-repo-dir}/indices/apis/freeze.asciidoc[]
 include::{es-repo-dir}/ilm/apis/ilm-api.asciidoc[]
+include::{es-repo-dir}/ilm/apis/slm-api.asciidoc[]
 include::{es-repo-dir}/licensing/index.asciidoc[]
 include::{es-repo-dir}/migration/migration.asciidoc[]
 include::{es-repo-dir}/ml/apis/ml-api.asciidoc[]

x-pack/plugin/src/test/resources/rest-api-spec/api/slm.delete_lifecycle.json

@@ -0,0 +1,19 @@
+{
+  "slm.delete_lifecycle": {
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api.html",
+    "methods": [ "DELETE" ],
+    "url": {
+      "path": "/_slm/policy/{policy_id}",
+      "paths": ["/_slm/policy/{policy_id}"],
+      "parts": {
+        "policy": {
+          "type" : "string",
+          "description" : "The id of the snapshot lifecycle policy to remove"
+        }
+      },
+      "params": {
+      }
+    },
+    "body": null
+  }
+}

x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_lifecycle.json

@@ -0,0 +1,19 @@
+{
+  "slm.execute_lifecycle": {
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api.html",
+    "methods": [ "PUT" ],
+    "url": {
+      "path": "/_slm/policy/{policy_id}/_execute",
+      "paths": ["/_slm/policy/{policy_id}/_execute"],
+      "parts": {
+        "policy_id": {
+          "type" : "string",
+          "description" : "The id of the snapshot lifecycle policy to be executed"
+        }
+      },
+      "params": {
+      }
+    },
+    "body": null
+  }
+}

x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_lifecycle.json

@@ -0,0 +1,19 @@
+{
+  "slm.get_lifecycle": {
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api.html",
+    "methods": [ "GET" ],
+    "url": {
+      "path": "/_slm/policy/{policy_id}",
+      "paths": ["/_slm/policy/{policy_id}", "/_slm/policy"],
+      "parts": {
+        "policy_id": {
+          "type" : "string",
+          "description" : "Comma-separated list of snapshot lifecycle policies to retrieve"
+        }
+      },
+      "params": {
+      }
+    },
+    "body": null
+  }
+}

x-pack/plugin/src/test/resources/rest-api-spec/api/slm.put_lifecycle.json

@@ -0,0 +1,21 @@
+{
+  "slm.put_lifecycle": {
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api.html",
+    "methods": [ "PUT" ],
+    "url": {
+      "path": "/_slm/policy/{policy_id}",
+      "paths": ["/_slm/policy/{policy_id}"],
+      "parts": {
+        "policy_id": {
+          "type" : "string",
+          "description" : "The id of the snapshot lifecycle policy"
+        }
+      },
+      "params": {
+      }
+    },
+    "body": {
+      "description": "The snapshot lifecycle policy definition to register"
+    }
+  }
+}