docs: Add documentation for elasticsearch_shards and elasticsearch_replicas

Gerardo Navarrorequested to merge
gitlab-community/gitlab-org/gitlab:571263-gerardo-navarro-docs-api-admin-application-settings-elasticsearch-shards-and-replicas into master

What does this MR do and why?

Documents the existing but undocumented elasticsearch_shards and elasticsearch_replicas parameters in the Application Settings API.

These parameters already support two update modes:

  1. Scalar values - Set the same number of shards/replicas for all Elasticsearch indices
  2. Object values - Set different values per index using index alias names as keys

This documentation addition:

  • Adds elasticsearch_shards and elasticsearch_replicas to the API parameter table
  • Adds a new "Elasticsearch index settings" section with usage examples for both modes
  • Documents the requirement that both parameters must be provided together when using per-index values

This is a documentation-only MR that complements !216396 which adds the elasticsearch_index_settings GET endpoint.

🛠️ with ❤️ at Siemens

References

  • Related issue: #571263
  • Related MR (GET endpoint): !216396
  • Implementation code: ee/app/services/ee/application_settings/update_service.rb#L77-99

Screenshots or screen recordings

Not applicable - documentation only changes.

How to set up and validate locally

  • Review the documentation changes in doc/api/settings.md
  • Verify the curl examples are correct by testing against a local GDK instance: 
    # Update all indices at once
curl --request PUT \
  --header "PRIVATE-TOKEN: <token>" \
  --header "Content-Type: application/json" \
  --url "http://gdk.local:3000/api/v4/application/settings" \
  --data '{"elasticsearch_shards": 5, "elasticsearch_replicas": 1}'

# Update specific indices individually
curl --request PUT \
  --header "PRIVATE-TOKEN: <token>" \
  --header "Content-Type: application/json" \
  --url "http://gdk.local:3000/api/v4/application/settings" \
  --data '{"elasticsearch_shards": {"gitlab-development": 5}, "elasticsearch_replicas": {"gitlab-development": 1}}'
  • Run the docs linter: vale doc/api/settings.md

MR acceptance checklist

Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

MR Checklist (@gerardo-navarro)

Merge request reports