Skip to content

Commit 11840e9

Browse files
kuniseneedugon
andauthored
Clarify index settings & APIs that are not available in serverless (#1728)
## Description There are some APIs and index settings that are not available in serverless mode. Using such API or index settings will get such response. Two main things: ### [1] It's not clear in docs that explain "why" these settings are designed as not available. Reason per we checked internally is that, _"These are defensive settings meant to protect the index from misuse that may lead to cluster instability so I don't believe we can expose these in Serverless. Since Elastic has responsibility for supporting cluster stability we have to make decisions about what you can and can not do to destabilize a cluster."_ We'd like to make it clear in public too. Also, some other pointers taken into consideration: - Avoid mentioning "misuse" since that sounds like user's fault - Emphasize it's Elastic's responsibility to keep the cluster stability. - Cover also cluster level and node level setting description that fully managed by Elastic ### [2] There's a detailed error message when using not available API. But there's no such error message for not available index settings. It's logically unbalanced. Either we should remove the message from unavailable API, or we add the error message for unavailable index settings. IMHO, at this time point, I'd like to add the error message for unavailable index settings, because there must have been a reason that we decided to put "unavailable API error message" into the doc. In the long run, I'd think we should remove both. ### Side notes Note the difference between index settings, and node/cluster settings. Per the [existing doc](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/differences-from-other-elasticsearch-offerings), we don't allow any node settings and cluster settings, they are fully managed by Elastic. We only allow limited index settings. I tried to make this point clear in my doc PR too. ## PR Preview API - https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/1728/deploy-manage/deploy/elastic-cloud/differences-from-other-elasticsearch-offerings#elasticsearch-differences-serverless-apis-availability Index settings - https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/1728/deploy-manage/deploy/elastic-cloud/differences-from-other-elasticsearch-offerings#elasticsearch-differences-serverless-settings-availability --- cc @ppf2 @jakommo @maggieghamry as we discussed together cc @dbrimley @leemthompo --------- Co-authored-by: Edu González de la Herrán <[email protected]>
1 parent 49ea890 commit 11840e9

File tree

1 file changed

+23
-2
lines changed

1 file changed

+23
-2
lines changed

deploy-manage/deploy/elastic-cloud/differences-from-other-elasticsearch-offerings.md

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,10 @@ These recommendations do not apply to indices using better binary quantization (
162162

163163
## Available {{es}} APIs [elasticsearch-differences-serverless-apis-availability]
164164

165-
Because {{serverless-full}} manages infrastructure automatically, certain Elasticsearch APIs are not available:
165+
In {{serverless-full}}, access is limited to a subset of {{es}} APIs, as Elastic manages the underlying infrastructure. These restrictions help maintain cluster stability, availability, and data integrity, ensuring reliable operation of Serverless projects.
166+
167+
The following {{es}} APIs are not available in {{serverless-full}}:
168+
166169

167170
Infrastructure operations
168171
: * All `_nodes/*` operations
@@ -201,7 +204,7 @@ Refer to the [{{es-serverless}} API reference](https://www.elastic.co/docs/api/d
201204

202205
## Available {{es}} settings [elasticsearch-differences-serverless-settings-availability]
203206

204-
In {{serverless-full}} Elasticsearch projects, you can only configure [index-level settings](elasticsearch://reference/elasticsearch/index-settings/index.md). Cluster-level settings and node-level settings are fully managed by Elastic.
207+
In {{serverless-full}} projects, configuration available to users is limited to certain [index-level settings](elasticsearch://reference/elasticsearch/index-settings/index.md), while Elastic manages cluster-level and node-level settings to maintain stability, availability, performance, and data integrity. These restrictions help ensure the reliability of Serverless projects.
205208

206209
Available settings
207210
: **Index-level settings**: Settings that control how documents are processed, stored, and searched are available to end users. These include:
@@ -219,6 +222,24 @@ Managed settings
219222
* Shard allocation
220223
* Resource management
221224

225+
When attempting to use an unavailable index setting, you'll receive this error:
226+
227+
```json
228+
{
229+
"error": {
230+
"root_cause": [
231+
{
232+
"type": "illegal_argument_exception",
233+
"reason": "Settings [xyz] are not available when running in serverless mode"
234+
}
235+
],
236+
"type": "illegal_argument_exception",
237+
"reason": "Settings [xyz] are not available when running in serverless mode"
238+
},
239+
"status": 400
240+
}
241+
```
242+
222243
## Learn more
223244

224245
- [{{serverless-full}} roadmap](https://www.elastic.co/cloud/serverless/roadmap): See upcoming features and development plans for the Serverless platform

0 commit comments

Comments
 (0)