From 300ddfa3c19bcf625c9ef45a86e0cf8dbae1c81c Mon Sep 17 00:00:00 2001 From: Gordon Brown Date: Mon, 14 Oct 2019 16:56:31 -0600 Subject: [PATCH] SLM Start/Stop HLRC and docs (#47966) This commit adds HLRC support and documentation for the SLM Start and Stop APIs, as well as updating existing documentation where appropriate. This commit also ensures that the SLM APIs are properly included in the HLRC documentation. --- .../client/IndexLifecycleClient.java | 101 +++++++++ .../IndexLifecycleRequestConverters.java | 42 ++++ ...pshotLifecycleManagementStatusRequest.java | 25 +++ .../client/slm/StartSLMRequest.java | 25 +++ .../client/slm/StopSLMRequest.java | 25 +++ .../documentation/ILMDocumentationIT.java | 211 +++++++++++++++--- ...pshot_lifecycle_management_status.asciidoc | 36 +++ ...art_snapshot_lifecycle_management.asciidoc | 36 +++ ...top_snapshot_lifecycle_management.asciidoc | 38 ++++ .../high-level/supported-apis.asciidoc | 29 +++ docs/reference/ilm/apis/slm-api.asciidoc | 167 +++++++++++++- 11 files changed, 704 insertions(+), 31 deletions(-) create mode 100644 client/rest-high-level/src/main/java/org/elasticsearch/client/slm/SnapshotLifecycleManagementStatusRequest.java create mode 100644 client/rest-high-level/src/main/java/org/elasticsearch/client/slm/StartSLMRequest.java create mode 100644 client/rest-high-level/src/main/java/org/elasticsearch/client/slm/StopSLMRequest.java create mode 100644 docs/java-rest/high-level/ilm/snapshot_lifecycle_management_status.asciidoc create mode 100644 docs/java-rest/high-level/ilm/start_snapshot_lifecycle_management.asciidoc create mode 100644 docs/java-rest/high-level/ilm/stop_snapshot_lifecycle_management.asciidoc diff --git a/client/rest-high-level/src/main/java/org/elasticsearch/client/IndexLifecycleClient.java b/client/rest-high-level/src/main/java/org/elasticsearch/client/IndexLifecycleClient.java index 54f381acb09..2fe3411ca46 100644 --- a/client/rest-high-level/src/main/java/org/elasticsearch/client/IndexLifecycleClient.java +++ b/client/rest-high-level/src/main/java/org/elasticsearch/client/IndexLifecycleClient.java @@ -43,6 +43,9 @@ import org.elasticsearch.client.slm.GetSnapshotLifecyclePolicyResponse; import org.elasticsearch.client.slm.GetSnapshotLifecycleStatsRequest; import org.elasticsearch.client.slm.GetSnapshotLifecycleStatsResponse; import org.elasticsearch.client.slm.PutSnapshotLifecyclePolicyRequest; +import org.elasticsearch.client.slm.SnapshotLifecycleManagementStatusRequest; +import org.elasticsearch.client.slm.StartSLMRequest; +import org.elasticsearch.client.slm.StopSLMRequest; import java.io.IOException; @@ -540,4 +543,102 @@ public class IndexLifecycleClient { return restHighLevelClient.performRequestAsyncAndParseEntity(request, IndexLifecycleRequestConverters::getSnapshotLifecycleStats, options, GetSnapshotLifecycleStatsResponse::fromXContent, listener, emptySet()); } + + /** + * Start the Snapshot Lifecycle Management feature. + * See 
+     *  https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/
+     *  java-rest-high-ilm-slm-start-slm.html
+     *
for more. + * @param request the request + * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized + * @return the response + * @throws IOException in case there is a problem sending the request or parsing back the response + */ + public AcknowledgedResponse startSLM(StartSLMRequest request, RequestOptions options) throws IOException { + return restHighLevelClient.performRequestAndParseEntity(request, IndexLifecycleRequestConverters::startSLM, options, + AcknowledgedResponse::fromXContent, emptySet()); + } + + /** + * Asynchronously start the Snapshot Lifecycle Management feature. + * See 
+     *  https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/
+     *  java-rest-high-ilm-slm-start-slm.html
+     *
for more. + * @param request the request + * @param listener the listener to be notified upon request completion + * @return cancellable that may be used to cancel the request + */ + public Cancellable startSLMAsync(StartSLMRequest request, RequestOptions options, ActionListener listener) { + return restHighLevelClient.performRequestAsyncAndParseEntity(request, IndexLifecycleRequestConverters::startSLM, options, + AcknowledgedResponse::fromXContent, listener, emptySet()); + } + + /** + * Stop the Snapshot Lifecycle Management feature. + * See 
+     *  https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/
+     *  java-rest-high-ilm-slm-stop-slm.html
+     *
for more. + * @param request the request + * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized + * @return the response + * @throws IOException in case there is a problem sending the request or parsing back the response + */ + public AcknowledgedResponse stopSLM(StopSLMRequest request, RequestOptions options) throws IOException { + return restHighLevelClient.performRequestAndParseEntity(request, IndexLifecycleRequestConverters::stopSLM, options, + AcknowledgedResponse::fromXContent, emptySet()); + } + + /** + * Asynchronously stop the Snapshot Lifecycle Management feature. + * See 
+     *  https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/
+     *  java-rest-high-ilm-slm-stop-slm.html
+     *
for more. + * @param request the request + * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized + * @param listener the listener to be notified upon request completion + * @return cancellable that may be used to cancel the request + */ + public Cancellable stopSLMAsync(StopSLMRequest request, RequestOptions options, ActionListener listener) { + return restHighLevelClient.performRequestAsyncAndParseEntity(request, IndexLifecycleRequestConverters::stopSLM, options, + AcknowledgedResponse::fromXContent, listener, emptySet()); + } + + /** + * Get the status of Snapshot Lifecycle Management. + * See 
+     *  https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/
+     *  java-rest-high-ilm-slm-status.html
+     *
for more. + * @param request the request + * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized + * @return the response + * @throws IOException in case there is a problem sending the request or parsing back the response + */ + public LifecycleManagementStatusResponse getSLMStatus(SnapshotLifecycleManagementStatusRequest request, + RequestOptions options) throws IOException { + return restHighLevelClient.performRequestAndParseEntity(request, IndexLifecycleRequestConverters::snapshotLifecycleManagementStatus, + options, LifecycleManagementStatusResponse::fromXContent, emptySet()); + } + + /** + * Asynchronously get the status of Snapshot Lifecycle Management. + * See 
+     *  https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/
+     *  java-rest-high-ilm-slm-status.html
+     *
for more. + * @param request the request + * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized + * @param listener the listener to be notified upon request completion + * @return cancellable that may be used to cancel the request + */ + public Cancellable getSLMStatusAsync(SnapshotLifecycleManagementStatusRequest request, RequestOptions options, + ActionListener listener) { + return restHighLevelClient.performRequestAsyncAndParseEntity(request, + IndexLifecycleRequestConverters::snapshotLifecycleManagementStatus, options, LifecycleManagementStatusResponse::fromXContent, + listener, emptySet()); + } } diff --git a/client/rest-high-level/src/main/java/org/elasticsearch/client/IndexLifecycleRequestConverters.java b/client/rest-high-level/src/main/java/org/elasticsearch/client/IndexLifecycleRequestConverters.java index 5c9212b598b..f4095077570 100644 --- a/client/rest-high-level/src/main/java/org/elasticsearch/client/IndexLifecycleRequestConverters.java +++ b/client/rest-high-level/src/main/java/org/elasticsearch/client/IndexLifecycleRequestConverters.java @@ -38,6 +38,9 @@ import org.elasticsearch.client.slm.ExecuteSnapshotLifecycleRetentionRequest; import org.elasticsearch.client.slm.GetSnapshotLifecyclePolicyRequest; import org.elasticsearch.client.slm.GetSnapshotLifecycleStatsRequest; import org.elasticsearch.client.slm.PutSnapshotLifecyclePolicyRequest; +import org.elasticsearch.client.slm.SnapshotLifecycleManagementStatusRequest; +import org.elasticsearch.client.slm.StartSLMRequest; +import org.elasticsearch.client.slm.StopSLMRequest; import org.elasticsearch.common.Strings; import java.io.IOException; @@ -239,4 +242,43 @@ final class IndexLifecycleRequestConverters { request.addParameters(params.asMap()); return request; } + + static Request snapshotLifecycleManagementStatus(SnapshotLifecycleManagementStatusRequest snapshotLifecycleManagementStatusRequest){ + Request request = new Request(HttpGet.METHOD_NAME, + new RequestConverters.EndpointBuilder() + .addPathPartAsIs("_slm") + .addPathPartAsIs("status") + .build()); + RequestConverters.Params params = new RequestConverters.Params(); + params.withMasterTimeout(snapshotLifecycleManagementStatusRequest.masterNodeTimeout()); + params.withTimeout(snapshotLifecycleManagementStatusRequest.timeout()); + request.addParameters(params.asMap()); + return request; + } + + static Request startSLM(StartSLMRequest startSLMRequest) { + Request request = new Request(HttpPost.METHOD_NAME, + new RequestConverters.EndpointBuilder() + .addPathPartAsIs("_slm") + .addPathPartAsIs("start") + .build()); + RequestConverters.Params params = new RequestConverters.Params(); + params.withMasterTimeout(startSLMRequest.masterNodeTimeout()); + params.withTimeout(startSLMRequest.timeout()); + request.addParameters(params.asMap()); + return request; + } + + static Request stopSLM(StopSLMRequest stopSLMRequest) { + Request request = new Request(HttpPost.METHOD_NAME, + new RequestConverters.EndpointBuilder() + .addPathPartAsIs("_slm") + .addPathPartAsIs("stop") + .build()); + RequestConverters.Params params = new RequestConverters.Params(); + params.withMasterTimeout(stopSLMRequest.masterNodeTimeout()); + params.withTimeout(stopSLMRequest.timeout()); + request.addParameters(params.asMap()); + return request; + } } diff --git a/client/rest-high-level/src/main/java/org/elasticsearch/client/slm/SnapshotLifecycleManagementStatusRequest.java b/client/rest-high-level/src/main/java/org/elasticsearch/client/slm/SnapshotLifecycleManagementStatusRequest.java new file mode 100644 index 00000000000..684c55cb487 --- /dev/null +++ b/client/rest-high-level/src/main/java/org/elasticsearch/client/slm/SnapshotLifecycleManagementStatusRequest.java @@ -0,0 +1,25 @@ +/* + * Licensed to Elasticsearch under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.elasticsearch.client.slm; + +import org.elasticsearch.client.TimedRequest; + +public class SnapshotLifecycleManagementStatusRequest extends TimedRequest { +} diff --git a/client/rest-high-level/src/main/java/org/elasticsearch/client/slm/StartSLMRequest.java b/client/rest-high-level/src/main/java/org/elasticsearch/client/slm/StartSLMRequest.java new file mode 100644 index 00000000000..6281acf2115 --- /dev/null +++ b/client/rest-high-level/src/main/java/org/elasticsearch/client/slm/StartSLMRequest.java @@ -0,0 +1,25 @@ +/* + * Licensed to Elasticsearch under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.elasticsearch.client.slm; + +import org.elasticsearch.client.TimedRequest; + +public class StartSLMRequest extends TimedRequest { +} diff --git a/client/rest-high-level/src/main/java/org/elasticsearch/client/slm/StopSLMRequest.java b/client/rest-high-level/src/main/java/org/elasticsearch/client/slm/StopSLMRequest.java new file mode 100644 index 00000000000..8d6a97cc8ba --- /dev/null +++ b/client/rest-high-level/src/main/java/org/elasticsearch/client/slm/StopSLMRequest.java @@ -0,0 +1,25 @@ +/* + * Licensed to Elasticsearch under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.elasticsearch.client.slm; + +import org.elasticsearch.client.TimedRequest; + +public class StopSLMRequest extends TimedRequest { +} diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java index cdf1f5b6be8..687da75fc82 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ILMDocumentationIT.java @@ -64,10 +64,13 @@ import org.elasticsearch.client.slm.GetSnapshotLifecycleStatsRequest; import org.elasticsearch.client.slm.GetSnapshotLifecycleStatsResponse; import org.elasticsearch.client.slm.PutSnapshotLifecyclePolicyRequest; import org.elasticsearch.client.slm.SnapshotInvocationRecord; +import org.elasticsearch.client.slm.SnapshotLifecycleManagementStatusRequest; import org.elasticsearch.client.slm.SnapshotLifecyclePolicy; import org.elasticsearch.client.slm.SnapshotLifecyclePolicyMetadata; import org.elasticsearch.client.slm.SnapshotLifecycleStats; import org.elasticsearch.client.slm.SnapshotRetentionConfiguration; +import org.elasticsearch.client.slm.StartSLMRequest; +import org.elasticsearch.client.slm.StopSLMRequest; import org.elasticsearch.cluster.metadata.IndexMetaData; import org.elasticsearch.common.Strings; import org.elasticsearch.common.collect.ImmutableOpenMap; @@ -460,7 +463,7 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase { assertTrue(latch.await(30L, TimeUnit.SECONDS)); } - public void testStartStopStatus() throws Exception { + public void testILMStartStopStatus() throws Exception { RestHighLevelClient client = highLevelClient(); stopILM(client); @@ -776,7 +779,7 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase { assertTrue(response.isAcknowledged()); //////// PUT - // tag::slm-put-snapshot-lifecycle-policy + // tag::slm-put-snapshot-lifecycle-policy-request Map config = new HashMap<>(); config.put("indices", Collections.singletonList("idx")); SnapshotRetentionConfiguration retention = @@ -786,7 +789,7 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase { "my_repository", config, retention); PutSnapshotLifecyclePolicyRequest request = new PutSnapshotLifecyclePolicyRequest(policy); - // end::slm-put-snapshot-lifecycle-policy + // end::slm-put-snapshot-lifecycle-policy-request // tag::slm-put-snapshot-lifecycle-policy-execute AcknowledgedResponse resp = client.indexLifecycle() @@ -815,16 +818,16 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase { // tag::slm-put-snapshot-lifecycle-policy-execute-async client.indexLifecycle().putSnapshotLifecyclePolicyAsync(request, - RequestOptions.DEFAULT, putListener); + RequestOptions.DEFAULT, putListener); // <1> // end::slm-put-snapshot-lifecycle-policy-execute-async //////// GET - // tag::slm-get-snapshot-lifecycle-policy + // tag::slm-get-snapshot-lifecycle-policy-request GetSnapshotLifecyclePolicyRequest getAllRequest = new GetSnapshotLifecyclePolicyRequest(); // <1> GetSnapshotLifecyclePolicyRequest getRequest = new GetSnapshotLifecyclePolicyRequest("policy_id"); // <2> - // end::slm-get-snapshot-lifecycle-policy + // end::slm-get-snapshot-lifecycle-policy-request // tag::slm-get-snapshot-lifecycle-policy-execute GetSnapshotLifecyclePolicyResponse getResponse = @@ -851,7 +854,7 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase { // tag::slm-get-snapshot-lifecycle-policy-execute-async client.indexLifecycle().getSnapshotLifecyclePolicyAsync(getRequest, - RequestOptions.DEFAULT, getListener); + RequestOptions.DEFAULT, getListener); // <1> // end::slm-get-snapshot-lifecycle-policy-execute-async assertThat(getResponse.getPolicies().size(), equalTo(1)); @@ -879,10 +882,10 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase { createIndex("idx", Settings.builder().put("index.number_of_shards", 1).build()); //////// EXECUTE - // tag::slm-execute-snapshot-lifecycle-policy + // tag::slm-execute-snapshot-lifecycle-policy-request ExecuteSnapshotLifecyclePolicyRequest executeRequest = new ExecuteSnapshotLifecyclePolicyRequest("policy_id"); // <1> - // end::slm-execute-snapshot-lifecycle-policy + // end::slm-execute-snapshot-lifecycle-policy-request // tag::slm-execute-snapshot-lifecycle-policy-execute ExecuteSnapshotLifecyclePolicyResponse executeResponse = @@ -937,7 +940,7 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase { // tag::slm-execute-snapshot-lifecycle-policy-execute-async client.indexLifecycle() .executeSnapshotLifecyclePolicyAsync(executeRequest, - RequestOptions.DEFAULT, executeListener); + RequestOptions.DEFAULT, executeListener); // <1> // end::slm-execute-snapshot-lifecycle-policy-execute-async latch.await(5, TimeUnit.SECONDS); @@ -958,42 +961,50 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase { greaterThanOrEqualTo(1L)); //////// DELETE - // tag::slm-delete-snapshot-lifecycle-policy + // tag::slm-delete-snapshot-lifecycle-policy-request DeleteSnapshotLifecyclePolicyRequest deleteRequest = new DeleteSnapshotLifecyclePolicyRequest("policy_id"); // <1> - // end::slm-delete-snapshot-lifecycle-policy + // end::slm-delete-snapshot-lifecycle-policy-request // tag::slm-delete-snapshot-lifecycle-policy-execute AcknowledgedResponse deleteResp = client.indexLifecycle() .deleteSnapshotLifecyclePolicy(deleteRequest, RequestOptions.DEFAULT); // end::slm-delete-snapshot-lifecycle-policy-execute + + // tag::slm-delete-snapshot-lifecycle-policy-response + boolean deleteAcknowledged = deleteResp.isAcknowledged(); // <1> + // end::slm-delete-snapshot-lifecycle-policy-response + assertTrue(deleteResp.isAcknowledged()); - ActionListener deleteListener = new ActionListener() { - @Override - public void onResponse(AcknowledgedResponse resp) { - // no-op - } + // tag::slm-delete-snapshot-lifecycle-policy-execute-listener + ActionListener deleteListener = + new ActionListener() { + @Override + public void onResponse(AcknowledgedResponse resp) { + boolean deleteAcknowledged = resp.isAcknowledged(); // <1> + } - @Override - public void onFailure(Exception e) { - // no-op - } - }; + @Override + public void onFailure(Exception e) { + // <2> + } + }; + // end::slm-delete-snapshot-lifecycle-policy-execute-listener // tag::slm-delete-snapshot-lifecycle-policy-execute-async client.indexLifecycle() .deleteSnapshotLifecyclePolicyAsync(deleteRequest, - RequestOptions.DEFAULT, deleteListener); + RequestOptions.DEFAULT, deleteListener); // <1> // end::slm-delete-snapshot-lifecycle-policy-execute-async assertTrue(deleteResp.isAcknowledged()); //////// EXECUTE RETENTION - // tag::slm-execute-snapshot-lifecycle-retention + // tag::slm-execute-snapshot-lifecycle-retention-request ExecuteSnapshotLifecycleRetentionRequest req = new ExecuteSnapshotLifecycleRetentionRequest(); - // end::slm-execute-snapshot-lifecycle-retention + // end::slm-execute-snapshot-lifecycle-retention-request // tag::slm-execute-snapshot-lifecycle-retention-execute AcknowledgedResponse retentionResp = @@ -1006,7 +1017,7 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase { final boolean acked = retentionResp.isAcknowledged(); // end::slm-execute-snapshot-lifecycle-retention-response - // tag::slm-execute-snapshot-lifecycle-policy-execute-listener + // tag::slm-execute-snapshot-lifecycle-retention-execute-listener ActionListener retentionListener = new ActionListener() { @Override @@ -1024,7 +1035,7 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase { // tag::slm-execute-snapshot-lifecycle-retention-execute-async client.indexLifecycle() .executeSnapshotLifecycleRetentionAsync(req, - RequestOptions.DEFAULT, retentionListener); + RequestOptions.DEFAULT, retentionListener); // <1> // end::slm-execute-snapshot-lifecycle-retention-execute-async } @@ -1051,6 +1062,152 @@ public class ILMDocumentationIT extends ESRestHighLevelClientTestCase { }); } + public void testSLMStartStopStatus() throws Exception { + RestHighLevelClient client = highLevelClient(); + + stopSLM(client); + + // tag::slm-status-request + SnapshotLifecycleManagementStatusRequest request = + new SnapshotLifecycleManagementStatusRequest(); + // end::slm-status-request + + // Check that SLM has stopped + { + // tag::slm-status-execute + LifecycleManagementStatusResponse response = + client.indexLifecycle() + .getSLMStatus(request, RequestOptions.DEFAULT); + // end::slm-status-execute + + // tag::slm-status-response + OperationMode operationMode = response.getOperationMode(); // <1> + // end::slm-status-response + + assertThat(operationMode, Matchers.either(equalTo(OperationMode.STOPPING)).or(equalTo(OperationMode.STOPPED))); + } + + startSLM(client); + + // tag::slm-status-execute-listener + ActionListener listener = + new ActionListener() { + @Override + public void onResponse( + LifecycleManagementStatusResponse response) { + OperationMode operationMode = response + .getOperationMode(); // <1> + } + + @Override + public void onFailure(Exception e) { + // <2> + } + }; + // end::slm-status-execute-listener + + final CountDownLatch latch = new CountDownLatch(1); + listener = new LatchedActionListener<>(listener, latch); + + // tag::slm-status-execute-async + client.indexLifecycle().getSLMStatusAsync(request, + RequestOptions.DEFAULT, listener); // <1> + // end::slm-status-execute-async + assertTrue(latch.await(30L, TimeUnit.SECONDS)); + + // Check that SLM is running again + LifecycleManagementStatusResponse response = + client.indexLifecycle() + .getSLMStatus(request, RequestOptions.DEFAULT); + + OperationMode operationMode = response.getOperationMode(); + assertEquals(OperationMode.RUNNING, operationMode); + } + + private void stopSLM(RestHighLevelClient client) throws IOException, InterruptedException { + // tag::slm-stop-slm-request + StopSLMRequest request = new StopSLMRequest(); + // end::slm-stop-slm-request + + // tag::slm-stop-slm-execute + AcknowledgedResponse response = client.indexLifecycle() + .stopSLM(request, RequestOptions.DEFAULT); + // end::slm-stop-slm-execute + + // tag::slm-stop-slm-response + boolean acknowledged = response.isAcknowledged(); // <1> + // end::slm-stop-slm-response + assertTrue(acknowledged); + + // tag::slm-stop-slm-execute-listener + ActionListener listener = + new ActionListener() { + @Override + public void onResponse(AcknowledgedResponse response) { + boolean acknowledged = response.isAcknowledged(); // <1> + } + + @Override + public void onFailure(Exception e) { + // <2> + } + }; + // end::slm-stop-slm-execute-listener + + // Replace the empty listener by a blocking listener in test + final CountDownLatch latch = new CountDownLatch(1); + listener = new LatchedActionListener<>(listener, latch); + + // tag::slm-stop-slm-execute-async + client.indexLifecycle().stopSLMAsync(request, + RequestOptions.DEFAULT, listener); // <1> + // end::slm-stop-slm-execute-async + assertTrue(latch.await(30L, TimeUnit.SECONDS)); + } + + private void startSLM(RestHighLevelClient client) throws IOException, InterruptedException { + // tag::slm-start-slm-request + StartSLMRequest request1 = new StartSLMRequest(); + // end::slm-start-slm-request + + // tag::slm-start-slm-execute + AcknowledgedResponse response = client.indexLifecycle() + .startSLM(request1, RequestOptions.DEFAULT); + // end::slm-start-slm-execute + + // tag::slm-start-slm-response + boolean acknowledged = response.isAcknowledged(); // <1> + // end::slm-start-slm-response + + assertTrue(acknowledged); + + // tag::slm-start-slm-execute-listener + ActionListener listener = + new ActionListener() { + @Override + public void onResponse(AcknowledgedResponse response) { + boolean acknowledged = response.isAcknowledged(); // <1> + } + + @Override + public void onFailure(Exception e) { + // <2> + } + }; + // end::slm-start-slm-execute-listener + + // Replace the empty listener by a blocking listener in test + final CountDownLatch latch = new CountDownLatch(1); + listener = new LatchedActionListener<>(listener, latch); + + // tag::slm-start-slm-execute-async + client.indexLifecycle().startSLMAsync(request1, + RequestOptions.DEFAULT, listener); // <1> + // end::slm-start-slm-execute-async + + assertTrue(latch.await(30L, TimeUnit.SECONDS)); + } + static Map toMap(Response response) throws IOException { return XContentHelper.convertToMap(JsonXContent.jsonXContent, EntityUtils.toString(response.getEntity()), false); } diff --git a/docs/java-rest/high-level/ilm/snapshot_lifecycle_management_status.asciidoc b/docs/java-rest/high-level/ilm/snapshot_lifecycle_management_status.asciidoc new file mode 100644 index 00000000000..ae6986711bc --- /dev/null +++ b/docs/java-rest/high-level/ilm/snapshot_lifecycle_management_status.asciidoc @@ -0,0 +1,36 @@ +-- +:api: slm-status +:request: SnapshotLifecycleManagementStatusRequest +:response: AcknowledgedResponse +-- +[role="xpack"] +[id="{upid}-{api}"] +=== Snapshot Lifecycle Management Status API + + +[id="{upid}-{api}-request"] +==== Request + +The Snapshot Lifecycle Management Status API allows you to retrieve the status +of Snapshot Lifecycle Management + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests-file}[{api}-request] +-------------------------------------------------- + + +[id="{upid}-{api}-response"] +==== Response + +The returned +{response}+ indicates the status of Snapshot Lifecycle Management. + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests-file}[{api}-response] +-------------------------------------------------- +<1> The returned status can be `RUNNING`, `STOPPING`, or `STOPPED`. + +include::../execution.asciidoc[] + + diff --git a/docs/java-rest/high-level/ilm/start_snapshot_lifecycle_management.asciidoc b/docs/java-rest/high-level/ilm/start_snapshot_lifecycle_management.asciidoc new file mode 100644 index 00000000000..b359f237ea5 --- /dev/null +++ b/docs/java-rest/high-level/ilm/start_snapshot_lifecycle_management.asciidoc @@ -0,0 +1,36 @@ +-- +:api: slm-start-slm +:request: StartSLMRequest +:response: AcknowledgedResponse +-- +[role="xpack"] +[id="{upid}-{api}"] +=== Start Snapshot Lifecycle Management API + + +[id="{upid}-{api}-request"] +==== Request + +The Start Snapshot Lifecycle Management API allows you to start Snapshot +Lifecycle Management if it has previously been stopped. + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests-file}[{api}-request] +-------------------------------------------------- + + +[id="{upid}-{api}-response"] +==== Response + +The returned +{response}+ indicates if the request to start Snapshot Lifecycle +Management was received. + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests-file}[{api}-response] +-------------------------------------------------- +<1> Whether or not the request to start Snapshot Lifecycle Management was +acknowledged. + +include::../execution.asciidoc[] diff --git a/docs/java-rest/high-level/ilm/stop_snapshot_lifecycle_management.asciidoc b/docs/java-rest/high-level/ilm/stop_snapshot_lifecycle_management.asciidoc new file mode 100644 index 00000000000..3f54341d430 --- /dev/null +++ b/docs/java-rest/high-level/ilm/stop_snapshot_lifecycle_management.asciidoc @@ -0,0 +1,38 @@ +-- +:api: slm-stop-slm +:request: StopSLMRequest +:response: AcknowledgedResponse +-- +[role="xpack"] +[id="{upid}-{api}"] +=== Stop Snapshot Lifecycle Management API + + +[id="{upid}-{api}-request"] +==== Request + +The Stop Snapshot Management API allows you to stop Snapshot Lifecycle +Management temporarily. + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests-file}[{api}-request] +-------------------------------------------------- + + +[id="{upid}-{api}-response"] +==== Response + +The returned +{response}+ indicates if the request to stop Snapshot +Lifecycle Management was received. + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests-file}[{api}-response] +-------------------------------------------------- +<1> Whether or not the request to stop Snapshot Lifecycle Management was +acknowledged. + +include::../execution.asciidoc[] + + diff --git a/docs/java-rest/high-level/supported-apis.asciidoc b/docs/java-rest/high-level/supported-apis.asciidoc index de5570e22d5..a6975a97326 100644 --- a/docs/java-rest/high-level/supported-apis.asciidoc +++ b/docs/java-rest/high-level/supported-apis.asciidoc @@ -579,6 +579,35 @@ include::ilm/lifecycle_management_status.asciidoc[] include::ilm/retry_lifecycle_policy.asciidoc[] include::ilm/remove_lifecycle_policy_from_index.asciidoc[] +[role="xpack"] +== Snapshot Lifecycle Management APIs + +:upid: {mainid}-ilm +:doc-tests-file: {doc-tests}/ILMDocumentationIT.java + +The Java High Level REST Client supports the following Snapshot Lifecycle +Management APIs: + +* <<{upid}-slm-put-snapshot-lifecycle-policy>> +* <<{upid}-slm-delete-snapshot-lifecycle-policy>> +* <<{upid}-ilm-get-lifecycle-policy>> +* <<{upid}-slm-start-slm>> +* <<{upid}-slm-stop-slm>> +* <<{upid}-slm-status>> +* <<{upid}-slm-execute-snapshot-lifecycle-policy>> +* <<{upid}-slm-execute-snapshot-lifecycle-retention>> + + +include::ilm/put_snapshot_lifecycle_policy.asciidoc[] +include::ilm/delete_snapshot_lifecycle_policy.asciidoc[] +include::ilm/get_snapshot_lifecycle_policy.asciidoc[] +include::ilm/start_snapshot_lifecycle_management.asciidoc[] +include::ilm/stop_snapshot_lifecycle_management.asciidoc[] +include::ilm/snapshot_lifecycle_management_status.asciidoc[] +include::ilm/execute_snapshot_lifecycle_policy.asciidoc[] +include::ilm/execute_snapshot_lifecycle_retention.asciidoc[] + + [role="xpack"] [[transform_apis]] == {transform-cap} APIs diff --git a/docs/reference/ilm/apis/slm-api.asciidoc b/docs/reference/ilm/apis/slm-api.asciidoc index c686d21c91d..44c11cae525 100644 --- a/docs/reference/ilm/apis/slm-api.asciidoc +++ b/docs/reference/ilm/apis/slm-api.asciidoc @@ -15,10 +15,9 @@ SLM policy management is split into three different CRUD APIs, a way to put or u policies, a way to retrieve policies, and a way to delete unwanted policies, as well as a separate API for immediately invoking a snapshot based on a policy. -Since SLM falls under the same category as ILM, it is stopped and started by -using the <> ILM APIs. It is, however, managed -by a different enable setting. To disable SLM's functionality, set the cluster -setting `xpack.slm.enabled` to `false` in elasticsearch.yml. +SLM can be stopped temporarily and restarted using the <> and +<> APIs. To disable SLM's functionality entirely, set the +cluster setting `xpack.slm.enabled` to `false` in elasticsearch.yml. [[slm-api-put]] === Put snapshot lifecycle policy API @@ -661,3 +660,163 @@ background: } -------------------------------------------------- +[[slm-stop]] +=== Stop Snapshot Lifecycle Management API + +[subs="attributes"] +++++ +Stop Snapshot Lifecycle Management +++++ + +Stop the Snapshot Lifecycle Management (SLM) plugin. + +[[slm-stop-request]] +==== {api-request-title} + +`POST /_ilm/stop` + +[[slm-stop-desc]] +==== {api-description-title} + +Halts all snapshot lifecycle management operations and stops the SLM plugin. +This is useful when you are performing maintenance on the cluster and need to +prevent SLM from performing any actions on your indices. Note that this API does +not stop any snapshots that are currently in progress, and that snapshots can +still be taken manually via the <> even +when SLM is stopped. + +The API returns as soon as the stop request has been acknowledged, but the +plugin might continue to run until in-progress operations complete and the plugin +can be safely stopped. Use the <> API to see +if SLM is running. + +==== Request Parameters + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + +==== Authorization + +You must have the `manage_slm` cluster privilege to use this API. +For more information, see <>. + +[[slm-stop-example]] +==== {api-examples-title} + +Stops the SLM plugin. + +[source,console] +-------------------------------------------------- +POST _slm/stop +-------------------------------------------------- +// TEST[continued] + +If the request does not encounter errors, you receive the following result: + +[source,console-result] +-------------------------------------------------- +{ + "acknowledged": true +} +-------------------------------------------------- + +[[slm-start]] +=== Start Snapshot Lifecycle Management API + +[subs="attributes"] +++++ +Start Snapshot Lifecycle Management +++++ + +Start the Snapshot Lifecycle Management (SLM) plugin. + +[[slm-start-request]] +==== {api-request-title} + +`POST /_slm/start` + +[[slm-start-desc]] +==== {api-description-title} + +Starts the SLM plugin if it is currently stopped. SLM is started +automatically when the cluster is formed. Restarting SLM is only +necessary if it has been stopped using the <>. + +==== Request Parameters + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + +==== Authorization + +You must have the `manage_slm` cluster privilege to use this API. +For more information, see <>. + +[[slm-start-example]] +==== {api-examples-title} + +Starts the SLM plugin. + +[source,console] +-------------------------------------------------- +POST _slm/start +-------------------------------------------------- +// TEST[continued] + +If the request succeeds, you receive the following result: + +[source,console-result] +-------------------------------------------------- +{ + "acknowledged": true +} +-------------------------------------------------- + +[[slm-get-status]] +=== Get Snapshot Lifecycle Management status API + +[subs="attributes"] +++++ +Get Snapshot Lifecycle Management status +++++ + +Retrieves the current Snapshot Lifecycle Management (SLM) status. + +[[slm-get-status-request]] +==== {api-request-title} + +`GET /_slm/status` + +[[slm-get-status-desc]] +==== {api-description-title} + +Returns the status of the SLM plugin. The `operation_mode` field in the +response shows one of three states: `STARTED`, `STOPPING`, +or `STOPPED`. You can change the status of the SLM plugin with the +<> and <> APIs. + +==== Request Parameters + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + +==== Authorization + +You must have the `manage_slm` or `read_slm` or both cluster privileges to use this API. +For more information, see <>. + +[[slm-get-status-example]] +==== {api-examples-title} + +Gets the SLM plugin status. + +[source,console] +-------------------------------------------------- +GET _slm/status +-------------------------------------------------- + +If the request succeeds, the body of the response shows the operation mode: + +[source,console-result] +-------------------------------------------------- +{ + "operation_mode": "RUNNING" +} +--------------------------------------------------