Skip to content

Commit 8280a20

Browse files
benwtrentbenwtrent
authored
ML: Add upgrade mode docs, hlrc, and fix bug (#37942)
* ML: Add upgrade mode docs, hlrc, and fix bug * [DOCS] Fixes build error and edits text * adjusting docs * Update docs/reference/ml/apis/set-upgrade-mode.asciidoc Co-Authored-By: benwtrent <[email protected]> * Update set-upgrade-mode.asciidoc * Update set-upgrade-mode.asciidoc
1 parent f337994 commit 8280a20

File tree

13 files changed

+407
-8
lines changed

13 files changed

+407
-8
lines changed

‎client/rest-high-level/src/main/java/org/elasticsearch/client/MLRequestConverters.java‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@
6464
import org.elasticsearch.client.ml.PutFilterRequest;
6565
import org.elasticsearch.client.ml.PutJobRequest;
6666
import org.elasticsearch.client.ml.RevertModelSnapshotRequest;
67+
import org.elasticsearch.client.ml.SetUpgradeModeRequest;
6768
import org.elasticsearch.client.ml.StartDatafeedRequest;
6869
import org.elasticsearch.client.ml.StopDatafeedRequest;
6970
import org.elasticsearch.client.ml.UpdateDatafeedRequest;
@@ -624,6 +625,17 @@ static Request deleteFilter(DeleteFilterRequest deleteFilterRequest) {
624625
return request;
625626
}
626627

628+
static Request setUpgradeMode(SetUpgradeModeRequest setUpgradeModeRequest) {
629+
String endpoint = new EndpointBuilder().addPathPartAsIs("_ml", "set_upgrade_mode").build();
630+
Request request = new Request(HttpPost.METHOD_NAME, endpoint);
631+
RequestConverters.Params params = new RequestConverters.Params(request);
632+
params.putParam(SetUpgradeModeRequest.ENABLED.getPreferredName(), Boolean.toString(setUpgradeModeRequest.isEnabled()));
633+
if (setUpgradeModeRequest.getTimeout() != null) {
634+
params.putParam(SetUpgradeModeRequest.TIMEOUT.getPreferredName(), setUpgradeModeRequest.getTimeout().toString());
635+
}
636+
return request;
637+
}
638+
627639
static Request mlInfo(MlInfoRequest infoRequest) {
628640
String endpoint = new EndpointBuilder()
629641
.addPathPartAsIs("_ml", "info")

‎client/rest-high-level/src/main/java/org/elasticsearch/client/MachineLearningClient.java‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@
8686
import org.elasticsearch.client.ml.PutJobResponse;
8787
import org.elasticsearch.client.ml.RevertModelSnapshotRequest;
8888
import org.elasticsearch.client.ml.RevertModelSnapshotResponse;
89+
import org.elasticsearch.client.ml.SetUpgradeModeRequest;
8990
import org.elasticsearch.client.ml.StartDatafeedRequest;
9091
import org.elasticsearch.client.ml.StartDatafeedResponse;
9192
import org.elasticsearch.client.ml.StopDatafeedRequest;
@@ -1838,4 +1839,42 @@ public void findFileStructureAsync(FindFileStructureRequest request, RequestOpti
18381839
listener,
18391840
Collections.emptySet());
18401841
}
1842+
1843+
/**
1844+
* Sets the ML cluster setting upgrade_mode
1845+
* <p>
1846+
* For additional info
1847+
* see <a href="http://www.elastic.co/guide/en/elasticsearch/reference/current/ml-set-upgrade-mode.html">Set Upgrade Mode</a>
1848+
*
1849+
* @param request The request to set upgrade mode
1850+
* @param options Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
1851+
* @return response
1852+
* @throws IOException when there is a serialization issue sending the request or receiving the response
1853+
*/
1854+
public AcknowledgedResponse setUpgradeMode(SetUpgradeModeRequest request, RequestOptions options) throws IOException {
1855+
return restHighLevelClient.performRequestAndParseEntity(request,
1856+
MLRequestConverters::setUpgradeMode,
1857+
options,
1858+
AcknowledgedResponse::fromXContent,
1859+
Collections.emptySet());
1860+
}
1861+
1862+
/**
1863+
* Sets the ML cluster setting upgrade_mode asynchronously
1864+
* <p>
1865+
* For additional info
1866+
* see <a href="http://www.elastic.co/guide/en/elasticsearch/reference/current/ml-set-upgrade-mode.html">Set Upgrade Mode</a>
1867+
*
1868+
* @param request The request of Machine Learning info
1869+
* @param options Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
1870+
* @param listener Listener to be notified upon request completion
1871+
*/
1872+
public void setUpgradeModeAsync(SetUpgradeModeRequest request, RequestOptions options, ActionListener<AcknowledgedResponse> listener) {
1873+
restHighLevelClient.performRequestAsyncAndParseEntity(request,
1874+
MLRequestConverters::setUpgradeMode,
1875+
options,
1876+
AcknowledgedResponse::fromXContent,
1877+
listener,
1878+
Collections.emptySet());
1879+
}
18411880
}

‎client/rest-high-level/src/main/java/org/elasticsearch/client/ml/SetUpgradeModeRequest.java‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
/*
2+
* Licensed to Elasticsearch under one or more contributor
3+
* license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright
5+
* ownership. Elasticsearch licenses this file to you under
6+
* the Apache License, Version 2.0 (the "License"); you may
7+
* not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
package org.elasticsearch.client.ml;
20+
21+
import org.elasticsearch.action.ActionRequest;
22+
import org.elasticsearch.action.ActionRequestValidationException;
23+
import org.elasticsearch.common.ParseField;
24+
import org.elasticsearch.common.unit.TimeValue;
25+
26+
import java.util.Objects;
27+
28+
/**
29+
* Sets ML into upgrade_mode
30+
*/
31+
public class SetUpgradeModeRequest extends ActionRequest {
32+
33+
34+
public static final ParseField ENABLED = new ParseField("enabled");
35+
public static final ParseField TIMEOUT = new ParseField("timeout");
36+
37+
private boolean enabled;
38+
private TimeValue timeout;
39+
40+
/**
41+
* Create a new request
42+
*
43+
* @param enabled whether to enable `upgrade_mode` or not
44+
*/
45+
public SetUpgradeModeRequest(boolean enabled) {
46+
this.enabled = enabled;
47+
}
48+
49+
public boolean isEnabled() {
50+
return enabled;
51+
}
52+
53+
public void setEnabled(boolean enabled) {
54+
this.enabled = enabled;
55+
}
56+
57+
public TimeValue getTimeout() {
58+
return timeout;
59+
}
60+
61+
/**
62+
* How long to wait for the request to be completed
63+
*
64+
* @param timeout default value of 30 seconds
65+
*/
66+
public void setTimeout(TimeValue timeout) {
67+
this.timeout = timeout;
68+
}
69+
70+
@Override
71+
public ActionRequestValidationException validate() {
72+
return null;
73+
}
74+
75+
@Override
76+
public int hashCode() {
77+
return Objects.hash(enabled, timeout);
78+
}
79+
80+
@Override
81+
public boolean equals(Object other) {
82+
if (this == other) {
83+
return true;
84+
}
85+
86+
if (other == null || getClass() != other.getClass()) {
87+
return false;
88+
}
89+
90+
SetUpgradeModeRequest that = (SetUpgradeModeRequest) other;
91+
return Objects.equals(enabled, that.enabled) && Objects.equals(timeout, that.timeout);
92+
}
93+
}

‎client/rest-high-level/src/test/java/org/elasticsearch/client/MLRequestConvertersTests.java‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@
6161
import org.elasticsearch.client.ml.PutFilterRequest;
6262
import org.elasticsearch.client.ml.PutJobRequest;
6363
import org.elasticsearch.client.ml.RevertModelSnapshotRequest;
64+
import org.elasticsearch.client.ml.SetUpgradeModeRequest;
6465
import org.elasticsearch.client.ml.StartDatafeedRequest;
6566
import org.elasticsearch.client.ml.StartDatafeedRequestTests;
6667
import org.elasticsearch.client.ml.StopDatafeedRequest;
@@ -818,6 +819,22 @@ public void testFindFileStructure() throws Exception {
818819
assertEquals(sample, requestEntityToString(request));
819820
}
820821

822+
public void testSetUpgradeMode() {
823+
SetUpgradeModeRequest setUpgradeModeRequest = new SetUpgradeModeRequest(true);
824+
825+
Request request = MLRequestConverters.setUpgradeMode(setUpgradeModeRequest);
826+
assertThat(request.getEndpoint(), equalTo("/_ml/set_upgrade_mode"));
827+
assertThat(request.getMethod(), equalTo(HttpPost.METHOD_NAME));
828+
assertThat(request.getParameters().get(SetUpgradeModeRequest.ENABLED.getPreferredName()), equalTo(Boolean.toString(true)));
829+
assertThat(request.getParameters().containsKey(SetUpgradeModeRequest.TIMEOUT.getPreferredName()), is(false));
830+
831+
setUpgradeModeRequest.setTimeout(TimeValue.timeValueHours(1));
832+
setUpgradeModeRequest.setEnabled(false);
833+
request = MLRequestConverters.setUpgradeMode(setUpgradeModeRequest);
834+
assertThat(request.getParameters().get(SetUpgradeModeRequest.ENABLED.getPreferredName()), equalTo(Boolean.toString(false)));
835+
assertThat(request.getParameters().get(SetUpgradeModeRequest.TIMEOUT.getPreferredName()), is("1h"));
836+
}
837+
821838
private static Job createValidJob(String jobId) {
822839
AnalysisConfig.Builder analysisConfig = AnalysisConfig.builder(Collections.singletonList(
823840
Detector.builder().setFunction("count").build()));

‎client/rest-high-level/src/test/java/org/elasticsearch/client/MachineLearningIT.java‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@
8484
import org.elasticsearch.client.ml.PutJobResponse;
8585
import org.elasticsearch.client.ml.RevertModelSnapshotRequest;
8686
import org.elasticsearch.client.ml.RevertModelSnapshotResponse;
87+
import org.elasticsearch.client.ml.SetUpgradeModeRequest;
8788
import org.elasticsearch.client.ml.StartDatafeedRequest;
8889
import org.elasticsearch.client.ml.StartDatafeedResponse;
8990
import org.elasticsearch.client.ml.StopDatafeedRequest;
@@ -1614,4 +1615,30 @@ public void testFindFileStructure() throws IOException {
16141615
assertEquals("timestamp", structure.getTimestampField());
16151616
assertFalse(structure.needClientTimezone());
16161617
}
1618+
1619+
public void testEnableUpgradeMode() throws Exception {
1620+
MachineLearningClient machineLearningClient = highLevelClient().machineLearning();
1621+
1622+
MlInfoResponse mlInfoResponse = machineLearningClient.getMlInfo(new MlInfoRequest(), RequestOptions.DEFAULT);
1623+
assertThat(mlInfoResponse.getInfo().get("upgrade_mode"), equalTo(false));
1624+
1625+
AcknowledgedResponse setUpgrademodeResponse = execute(new SetUpgradeModeRequest(true),
1626+
machineLearningClient::setUpgradeMode,
1627+
machineLearningClient::setUpgradeModeAsync);
1628+
1629+
assertThat(setUpgrademodeResponse.isAcknowledged(), is(true));
1630+
1631+
1632+
mlInfoResponse = machineLearningClient.getMlInfo(new MlInfoRequest(), RequestOptions.DEFAULT);
1633+
assertThat(mlInfoResponse.getInfo().get("upgrade_mode"), equalTo(true));
1634+
1635+
setUpgrademodeResponse = execute(new SetUpgradeModeRequest(false),
1636+
machineLearningClient::setUpgradeMode,
1637+
machineLearningClient::setUpgradeModeAsync);
1638+
1639+
assertThat(setUpgrademodeResponse.isAcknowledged(), is(true));
1640+
1641+
mlInfoResponse = machineLearningClient.getMlInfo(new MlInfoRequest(), RequestOptions.DEFAULT);
1642+
assertThat(mlInfoResponse.getInfo().get("upgrade_mode"), equalTo(false));
1643+
}
16171644
}

‎client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,7 @@
9999
import org.elasticsearch.client.ml.PutJobResponse;
100100
import org.elasticsearch.client.ml.RevertModelSnapshotRequest;
101101
import org.elasticsearch.client.ml.RevertModelSnapshotResponse;
102+
import org.elasticsearch.client.ml.SetUpgradeModeRequest;
102103
import org.elasticsearch.client.ml.StartDatafeedRequest;
103104
import org.elasticsearch.client.ml.StartDatafeedResponse;
104105
import org.elasticsearch.client.ml.StopDatafeedRequest;
@@ -3078,6 +3079,57 @@ public void onFailure(Exception e) {
30783079
}
30793080
}
30803081

3082+
public void testSetUpgradeMode() throws Exception {
3083+
RestHighLevelClient client = highLevelClient();
3084+
{
3085+
// tag::set-upgrade-mode-request
3086+
SetUpgradeModeRequest request = new SetUpgradeModeRequest(true); // <1>
3087+
request.setTimeout(TimeValue.timeValueMinutes(10)); // <2>
3088+
// end::set-upgrade-mode-request
3089+
3090+
// Set to false so that the cluster setting does not have to be unset at the end of the test.
3091+
request.setEnabled(false);
3092+
3093+
// tag::set-upgrade-mode-execute
3094+
AcknowledgedResponse acknowledgedResponse = client.machineLearning().setUpgradeMode(request, RequestOptions.DEFAULT);
3095+
// end::set-upgrade-mode-execute
3096+
3097+
// tag::set-upgrade-mode-response
3098+
boolean acknowledged = acknowledgedResponse.isAcknowledged(); // <1>
3099+
// end::set-upgrade-mode-response
3100+
assertThat(acknowledged, is(true));
3101+
}
3102+
{
3103+
SetUpgradeModeRequest request = new SetUpgradeModeRequest(false);
3104+
3105+
// tag::set-upgrade-mode-execute-listener
3106+
ActionListener<AcknowledgedResponse> listener = new ActionListener<AcknowledgedResponse>() {
3107+
@Override
3108+
public void onResponse(AcknowledgedResponse acknowledgedResponse) {
3109+
// <1>
3110+
}
3111+
3112+
@Override
3113+
public void onFailure(Exception e) {
3114+
// <2>
3115+
}
3116+
};
3117+
// end::set-upgrade-mode-execute-listener
3118+
3119+
// Replace the empty listener by a blocking listener in test
3120+
final CountDownLatch latch = new CountDownLatch(1);
3121+
listener = new LatchedActionListener<>(listener, latch);
3122+
3123+
// tag::set-upgrade-mode-execute-async
3124+
client.machineLearning()
3125+
.setUpgradeModeAsync(request, RequestOptions.DEFAULT, listener); // <1>
3126+
// end::set-upgrade-mode-execute-async
3127+
3128+
assertTrue(latch.await(30L, TimeUnit.SECONDS));
3129+
3130+
}
3131+
}
3132+
30813133
private String createFilter(RestHighLevelClient client) throws IOException {
30823134
MlFilter.Builder filterBuilder = MlFilter.builder("my_safe_domains")
30833135
.setDescription("A list of safe domains")

‎docs/java-rest/high-level/ml/set-upgrade-mode.asciidoc‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
--
2+
:api: set-upgrade-mode
3+
:request: SetUpgradeModeRequest
4+
:response: AcknowledgedResponse
5+
--
6+
[id="{upid}-{api}"]
7+
=== Set Upgrade Mode API
8+
9+
The Set Upgrade Mode API temporarily halts all {ml} job and {dfeed} tasks when `enabled=true`. Their
10+
reported states remain unchanged. Consequently, when exiting upgrade mode the halted {ml} jobs and
11+
{dfeeds} will return to their previous state.
12+
13+
It accepts a +{request}+ object and responds with a +{response}+ object.
14+
15+
When `enabled=true`, no new jobs can be opened, and no job or {dfeed} tasks will
16+
be running. Be sure to set `enabled=false` once upgrade actions are completed.
17+
18+
[id="{upid}-{api}-request"]
19+
==== Set Upgrade Mode Request
20+
21+
A +{request}+ object gets created setting the desired `enabled` state.
22+
23+
["source","java",subs="attributes,callouts,macros"]
24+
--------------------------------------------------
25+
include-tagged::{doc-tests-file}[{api}-request]
26+
--------------------------------------------------
27+
<1> Constructing a new request referencing enabling upgrade mode
28+
<2> Optionally setting the `timeout` value for how long the
29+
execution should wait.
30+
31+
[id="{upid}-{api}-response"]
32+
==== Set Upgrade Mode Response
33+
34+
["source","java",subs="attributes,callouts,macros"]
35+
--------------------------------------------------
36+
include-tagged::{doc-tests-file}[{api}-response]
37+
--------------------------------------------------
38+
<1> `isAcknowledged()` from the +{response}+ indicates if the setting was set successfully.
39+
40+
include::../execution.asciidoc[]

‎docs/java-rest/high-level/supported-apis.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,6 +295,7 @@ The Java High Level REST Client supports the following Machine Learning APIs:
295295
* <<{upid}-update-model-snapshot>>
296296
* <<{upid}-get-ml-info>>
297297
* <<{upid}-delete-expired-data>>
298+
* <<{upid}-set-upgrade-mode>>
298299

299300
include::ml/put-job.asciidoc[]
300301
include::ml/get-job.asciidoc[]
@@ -338,6 +339,7 @@ include::ml/revert-model-snapshot.asciidoc[]
338339
include::ml/update-model-snapshot.asciidoc[]
339340
include::ml/get-info.asciidoc[]
340341
include::ml/delete-expired-data.asciidoc[]
342+
include::ml/set-upgrade-mode.asciidoc[]
341343

342344
== Migration APIs
343345

0 commit comments

Comments
 (0)