elastic / elastic/docs-content

[Internal]: Document all of the ways to update ES settings

Open
#1,579 2 comments 0 reactions 0 assignees View on GitHub
Team:Admin Team:Developer
Dominant language
No language data
Stars
47
Forks
261
Avg merge
3d 17h
Merged PRs (30d)
130

Description

### Description

Do a better job of explaining how settings can be set / overridden / reset, impact of JSON parsing order

Raised in https://github.com/elastic/elasticsearch-specification/issues/4435, behavior outlined in https://docs.google.com/document/d/1DqkEMTCyJsFArJP_ePj4zFsuTx2-0UNsH4NGmjg00yQ/edit?tab=t.0#heading=h.vwpq1kn6hahn

Impacts both cluster + index settings

### Resources

https://docs.google.com/document/d/1DqkEMTCyJsFArJP_ePj4zFsuTx2-0UNsH4NGmjg00yQ/edit?tab=t.0#heading=h.vwpq1kn6hahn

Content up to, but not including "How to model index settings in the API specification?"

### Which documentation set does this change impact?

Unknown

### Feature differences

-

### What release is this request related to?

N/A

### Serverless release

-

### Collaboration model

The documentation team

### Point of contact.

**Main contact:** @l-trotta

---

## Elastic Docs AI Scoping 🤖

Docs issue scope

### Summary
The issue requests better documentation of all the ways Elasticsearch settings can be set, overridden, and reset — specifically covering the coexistence of flat dotted notation (e.g., `indices.recovery.max_bytes_per_sec`) and nested JSON hierarchy, JSON parsing order (last value in text order wins), wildcard resets for cluster settings, and the "index" prefix equivalence for index settings. The linked elasticsearch-specification issue (#4435, now closed/completed) confirms these behaviors are real and provides concrete examples. There are no linked code-change PRs — this is a documentation gap for existing, undocumented behavior. The primary technical content source is the Google Doc referenced in the issue (internal) and the elasticsearch-specification issue body.

### Request accuracy
Accurate — the elasticsearch-specification issue provides detailed examples confirming all four behaviors are present and undocumented.

### Next action for author
Add a new "API request formats" (or equivalent) section to `deploy-manage/stack-settings.md` covering the four JSON representation behaviors, using examples from the elasticsearch-specification issue and the internal Google Doc.

### Impact: High

### Scope boundary
Node-level and static settings (elasticsearch.yml) do not need changes — this is scoped to the dynamic settings API request format behaviors only.

### Recommended documentation targets

| Page | URL | Action | Impact | Confidence | Why this page? |
|------|-----|--------|--------|------------|----------------|
| Elastic Stack settings | https://www.elastic.co/docs/deploy-manage/stack-settings | Add section to existing page | High | High | This page already covers dynamic settings (transient/persistent, null reset) and is the natural home for a new subsection on API request formats (flat vs. nested, parsing order, wildcards, index prefix). |
| Dynamic settings snippet | `deploy-manage/deploy/self-managed/_snippets/dynamic-settings.md` (transcluded into stack-settings.md) | Update existing page | Medium | High | The snippet briefly describes transient/persistent and null reset but omits JSON format behaviors; expanding it or adding a link from it would catch all pages that include it. |
| Cluster update settings API reference | https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings | Review only | Medium | Medium | This API reference page (likely in the elasticsearch-specification or elasticsearch server repo, not this repo) should document the wildcard reset and flat/nested coexistence for cluster settings. |
| Update index settings API reference | https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings | Review only | Medium | Medium | This API reference page should document the "index" prefix equivalence and flat/nested mixing for index settings. |

### Recommendations

1. In `deploy-manage/stack-settings.md`, add a subsection under "Dynamic and static Elasticsearch settings" titled something like **"Setting request formats"** that covers:
- Flat dotted names (e.g., `indices.recovery.max_bytes_per_sec`) and nested JSON objects are both valid and can be mixed in a single request.
- When both forms appear in the same request body, the last value encountered in JSON text order takes precedence.
- For cluster settings, wildcards can be used to reset a group of settings at once (both flat `"indices.*": null` and nested `"indices": {"*": null}` work).
- For index settings, requests with no prefix, with the `index.` dotted prefix, and with the nested `index:{}` wrapper are all equivalent.
2. Update (or add a cross-reference from) the `dynamic-settings.md` snippet to point to the new section.
3. File follow-up issues (or coordinate with `@pquentin`) to update the Cluster update settings and Update index settings API reference pages in the elasticsearch-specification repo.

### Notes

- The `stack-settings.md` page currently functions as a mixed-purpose configuration overview; adding a focused "request formats" subsection fits its existing role and avoids creating a new standalone page for what is conceptually a short reference section.
- The examples in the elasticsearch-specification issue body (#4435) can be used directly as illustrative code snippets.
- The internal Google Doc should be reviewed for any additional edge cases not captured in the specification issue before writing.

---
[Docs automation](https://github.com/elastic/docs-actions) | [From workflow: Issue Scope Analyzer](https://github.com/elastic/docs-content/actions/runs/24730380927)

React with 👍 if helpful, 👎 if not.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.