Clarify index settings & APIs that are not available in serverless

[kunisen]

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, 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

[github-actions]

🔍 Preview links for changed docs:

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

🔔 The preview site may take up to 3 minutes to finish building. These links will become live once it completes.

[eedugon]

I think this issue relates with #79 (cc: @shainaraskas ).

Thanks a lot for your help here @kunisen , I'll review this next week together with the scope of the mentioned issue.

[kunisen]

Thanks @eedugon

Yes, it's a part of #79, specifically stemmed from #79 (comment) and internal discussion link where @dbrimley asked me to raise a doc PR so that PM can review the statement we want to use.

(My bad I should write that in my original post - apparently I missed it)

[eedugon]

My bad I should write that in my original post - apparently I missed it

no worries! It's just that yesterday we decided to prioritize this issue and your PR feels like it dropped from the sky 😄

I'll take a look and see if it's aligned with the overall plan to fix this issue and get back to you. Again, thanks!

[eedugon]

The clarifications make sense, thanks for adding them. I've added a few suggestions as they shouldn't be added as important banners in this context.

[kunisen]

@dbrimley Could we get your approval from PM perspective or are we waiting on any further input from my side?
(We got docs team's kind help to review the sentence)

[eedugon]

LGTM, thanks Kuni!! Feel free to merge whenever you have the agreement of other stakeholders.