Skip to content

Commit d22a6f2

Browse files
henningandersenjrodewig
henningandersen
and
jrodewig
committed
Autoscaling APIs not experimental (#67202)
We no longer regard the autoscaling APIs experimental though they are only intended for use by ESS/ECE/ECK. This commit updates the docs to reflect this and adds a minimal set of documentation for the feature. Co-authored-by: James Rodewig <[email protected]>
1 parent 0e263a7 commit d22a6f2

12 files changed

+443
-13
lines changed

‎docs/reference/autoscaling/apis/autoscaling-apis.asciidoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
[role="xpack"]
2-
[testenv="platinum"]
2+
[testenv="enterprise"]
33
[[autoscaling-apis]]
44
== Autoscaling APIs
55

6-
experimental[]
6+
include::../autoscaling-designed-for-note.asciidoc[]
77

88
You can use the following APIs to perform autoscaling operations.
99

‎docs/reference/autoscaling/apis/delete-autoscaling-policy.asciidoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
[role="xpack"]
2-
[testenv="platinum"]
2+
[testenv="enterprise"]
33
[[autoscaling-delete-autoscaling-policy]]
44
=== Delete autoscaling policy API
55
++++
66
<titleabbrev>Delete autoscaling policy</titleabbrev>
77
++++
88

9-
experimental[]
9+
include::../autoscaling-designed-for-note.asciidoc[]
1010

1111
Delete autoscaling policy.
1212

‎docs/reference/autoscaling/apis/get-autoscaling-capacity.asciidoc

Lines changed: 192 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
[role="xpack"]
2-
[testenv="platinum"]
2+
[testenv="enterprise"]
33
[[autoscaling-get-autoscaling-capacity]]
44
=== Get autoscaling capacity API
55
++++
66
<titleabbrev>Get autoscaling capacity</titleabbrev>
77
++++
88

9-
experimental[]
9+
include::../autoscaling-designed-for-note.asciidoc[]
1010

1111
Get autoscaling capacity.
1212

@@ -33,6 +33,196 @@ This API gets the current autoscaling capacity based on the configured
3333
autoscaling policy. This API will return information to size the cluster
3434
appropriately to the current workload.
3535

36+
The `required_capacity` is calculated as the max of the `required_capacity`
37+
result of all individual deciders that are enabled for the policy.
38+
39+
The operator should verify that the `current_nodes` match
40+
the operator's knowledge of the cluster to avoid making autoscaling decisions
41+
based on stale or incomplete information.
42+
43+
The response contains decider-specific information you can use to diagnose how
44+
and why autoscaling determined a certain capacity was required. This information
45+
is provided for diagnosis only. Do not use this information to make autoscaling
46+
decisions.
47+
48+
[role="child_attributes"]
49+
[[autoscaling-get-autoscaling-capacity-api-response-body]]
50+
==== {api-response-body-title}
51+
52+
`policies`::
53+
(object)
54+
Contains the map of policy name to capacity result
55+
+
56+
.Properties of `policies`
57+
[%collapsible%open]
58+
====
59+
`<policy_name>`::
60+
(object)
61+
Contains capacity information for the policy
62+
+
63+
.Properties of `<policy_name>`
64+
[%collapsible%open]
65+
=====
66+
`required_capacity`::
67+
(object)
68+
Contains the required capacity for the policy.
69+
+
70+
.Properties of `required_capacity`
71+
[%collapsible%open]
72+
======
73+
`node`::
74+
(object)
75+
Contains the minimum node sizes required per node, ensuring that individual
76+
shards or ML jobs can fit into a single node.
77+
+
78+
.Properties of `node`
79+
[%collapsible%open]
80+
=======
81+
`storage`::
82+
(integer)
83+
Bytes of storage required per node.
84+
85+
`memory`::
86+
(integer)
87+
Bytes of memory required per node.
88+
89+
=======
90+
`total`::
91+
(object)
92+
Contains the total size required for the policy.
93+
+
94+
.Properties of `total`
95+
[%collapsible%open]
96+
=======
97+
`storage`::
98+
(integer)
99+
Total bytes of storage required for the policy.
100+
101+
`memory`::
102+
(integer)
103+
Total bytes of memory required for the policy.
104+
=======
105+
======
106+
`current_capacity`::
107+
(object)
108+
Contains the current capacity for nodes governed by the policy, i.e. the nodes
109+
that {es} bases its calculation on.
110+
+
111+
.Properties of `current_capacity`
112+
[%collapsible%open]
113+
======
114+
`node`::
115+
(object)
116+
Contains the maximum sizes of nodes governed by the policy.
117+
+
118+
.Properties of `node`
119+
[%collapsible%open]
120+
=======
121+
`storage`::
122+
(integer)
123+
Maximum bytes of storage of a node.
124+
125+
`memory`::
126+
(integer)
127+
Maximum bytes of memory of a node.
128+
129+
=======
130+
`total`::
131+
(object)
132+
Contains the current total storage and memory sizes for nodes governed by the policy.
133+
+
134+
.Properties of `total`
135+
[%collapsible%open]
136+
=======
137+
`storage`::
138+
(integer)
139+
Current bytes of storage available for the policy.
140+
141+
`memory`::
142+
(integer)
143+
Current bytes of memory available for the policy.
144+
=======
145+
======
146+
`current_nodes`::
147+
(array of objects)
148+
List of nodes used for capacity calculation.
149+
+
150+
.Properties of elements in `current_nodes`
151+
[%collapsible%open]
152+
======
153+
`name`::
154+
(string)
155+
Name of the node.
156+
======
157+
`deciders`::
158+
(object)
159+
The capacity results from individual deciders, allowing insight into how the
160+
outer level `required_capacity` was calculated.
161+
+
162+
.Properties of `deciders`
163+
[%collapsible%open]
164+
=======
165+
`<decider_name>`::
166+
(object)
167+
The capacity result for a specific decider enabled for the policy.
168+
+
169+
.Properties of `<decider_name>`
170+
[%collapsible%open]
171+
========
172+
`required_capacity`::
173+
(object)
174+
Required capacity determined by the decider.
175+
+
176+
.Properties of `required_capacity`
177+
[%collapsible%open]
178+
=========
179+
`node`::
180+
(object)
181+
Contains the minimum node sizes required per node, ensuring that individual
182+
shards or {ml} jobs can fit into a single node.
183+
+
184+
.Properties of `node`
185+
[%collapsible%open]
186+
==========
187+
`storage`::
188+
(integer)
189+
Bytes of storage required per node.
190+
191+
`memory`::
192+
(integer)
193+
Bytes of memory required per node.
194+
195+
==========
196+
`total`::
197+
(object)
198+
Contains the total size required for the policy.
199+
+
200+
.Properties of `total`
201+
[%collapsible%open]
202+
==========
203+
`storage`::
204+
(integer)
205+
Total bytes of storage required for the policy.
206+
207+
`memory`::
208+
(integer)
209+
Total bytes of memory required for the policy.
210+
==========
211+
=========
212+
`reason_summary`::
213+
(string)
214+
Description of the basis for the decider's result.
215+
216+
`reason_details`::
217+
(object)
218+
A per-decider structure containing details about the basis for the deciders' result.
219+
The contents should not be relied on for application purposes and are not subject
220+
to backwards compatibility guarantees.
221+
========
222+
=======
223+
=====
224+
====
225+
36226
[[autoscaling-get-autoscaling-capacity-examples]]
37227
==== {api-examples-title}
38228

‎docs/reference/autoscaling/apis/get-autoscaling-policy.asciidoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
[role="xpack"]
2-
[testenv="platinum"]
2+
[testenv="enterprise"]
33
[[autoscaling-get-autoscaling-policy]]
44
=== Get autoscaling policy API
55
++++
66
<titleabbrev>Get autoscaling policy</titleabbrev>
77
++++
88

9-
experimental[]
9+
include::../autoscaling-designed-for-note.asciidoc[]
1010

1111
Get autoscaling policy.
1212

‎docs/reference/autoscaling/apis/put-autoscaling-policy.asciidoc

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
[role="xpack"]
2-
[testenv="platinum"]
2+
[testenv="enterprise"]
33
[[autoscaling-put-autoscaling-policy]]
44
=== Put autoscaling policy API
55
++++
66
<titleabbrev>Put autoscaling policy</titleabbrev>
77
++++
88

9-
experimental[]
9+
include::../autoscaling-designed-for-note.asciidoc[]
1010

1111
Put autoscaling policy.
1212

@@ -47,6 +47,7 @@ DELETE /_autoscaling/policy/name
4747
==== {api-description-title}
4848

4949
This API puts an autoscaling policy with the provided name.
50+
See <<autoscaling-deciders,Autoscaling Deciders>> for available deciders.
5051

5152
[[autoscaling-put-autoscaling-policy-examples]]
5253
==== {api-examples-title}

‎docs/reference/autoscaling/autoscaling-deciders.asciidoc

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
[role="xpack"]
2+
[testenv="enterprise"]
3+
[[autoscaling-deciders]]
4+
== Autoscaling deciders
5+
6+
<<autoscaling-reactive-storage-decider,Reactive storage decider>>::
7+
Estimates required storage capacity of current data set. Available for policies
8+
governing data nodes.
9+
10+
<<autoscaling-proactive-storage-decider,Proactive storage decider>>::
11+
Estimates required storage capacity based on current ingestion into hot nodes.
12+
Available for policies governing hot data nodes.
13+
14+
<<autoscaling-machine-learning-decider,Machine learning decider>>::
15+
Estimates required memory capacity based on machine learning jobs.
16+
Available for policies governing machine learning nodes.
17+
18+
<<autoscaling-fixed-decider,Fixed decider>>::
19+
Responds with a fixed required capacity. This decider is intended for testing only.
20+
21+
include::deciders/reactive-storage-decider.asciidoc[]
22+
include::deciders/proactive-storage-decider.asciidoc[]
23+
include::deciders/machine-learning-decider.asciidoc[]
24+
include::deciders/fixed-decider.asciidoc[]

‎docs/reference/autoscaling/autoscaling-designed-for-note.asciidoc

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
[NOTE]
2+
Autoscaling is designed for indirect use by {ess-trial}[{ess}],
3+
{ece-ref}[{ece}], and {eck-ref}[Elastic Cloud on Kubernetes]. Direct use is not
4+
supported.

‎docs/reference/autoscaling/deciders/fixed-decider.asciidoc

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
[role="xpack"]
2+
[testenv="enterprise"]
3+
[[autoscaling-fixed-decider]]
4+
=== Fixed decider
5+
6+
experimental[]
7+
[WARNING]
8+
The fixed decider is intended for testing only. Do not use this decider in production.
9+
10+
The `fixed` decider responds with a fixed required capacity. It is not enabled
11+
by default but can be enabled for any policy by explicitly configuring it.
12+
13+
==== Configuration settings
14+
15+
`storage`::
16+
(Optional, <<byte-units,byte value>>)
17+
Required amount of node-level storage. Defaults to `-1` (disabled).
18+
19+
`memory`::
20+
(Optional, <<byte-units,byte value>>)
21+
Required amount of node-level memory. Defaults to `-1` (disabled).
22+
23+
`nodes`::
24+
(Optional, integer)
25+
Number of nodes to use when calculating capacity. Defaults to `1`.
26+
27+
[[autoscaling-fixed-decider-examples]]
28+
==== {api-examples-title}
29+
30+
This example puts an autoscaling policy named `my_autoscaling_policy`, enabling
31+
and configuring the fixed decider.
32+
33+
[source,console]
34+
--------------------------------------------------
35+
PUT /_autoscaling/policy/my_autoscaling_policy
36+
{
37+
"roles" : [ "data_hot" ],
38+
"deciders": {
39+
"fixed": {
40+
"storage": "1tb",
41+
"memory": "32gb",
42+
"nodes": 8
43+
}
44+
}
45+
}
46+
--------------------------------------------------
47+
// TEST
48+
49+
The API returns the following result:
50+
51+
[source,console-result]
52+
--------------------------------------------------
53+
{
54+
"acknowledged": true
55+
}
56+
--------------------------------------------------
57+
58+
//////////////////////////
59+
60+
[source,console]
61+
--------------------------------------------------
62+
DELETE /_autoscaling/policy/my_autoscaling_policy
63+
--------------------------------------------------
64+
// TEST[continued]
65+
66+
//////////////////////////
67+

0 commit comments

Comments
 (0)