From c3be8fbed5f1d0516e5306ce4619f77ccee566ce Mon Sep 17 00:00:00 2001 From: Gerardo Navarro Date: Mon, 15 Dec 2025 10:10:34 +0000 Subject: [PATCH 1/2] Add documentation for elasticsearch_shards and elasticsearch_replicas Document the existing but undocumented ability to configure Elasticsearch index shards and replicas via the application settings API, including per-index configuration support. Changelog: other --- doc/api/settings.md | 60 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/doc/api/settings.md b/doc/api/settings.md index 0a755fe104d5ec..b0abf51bdbd9cd 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -573,6 +573,8 @@ to configure other related settings. These requirements are | `elasticsearch_password` | string | no | The password of your Elasticsearch instance. Premium and Ultimate only. | | `elasticsearch_prefix` | string | no | Custom prefix for Elasticsearch index names. Defaults to `gitlab`. Must be 1-100 characters, contain only lowercase alphanumeric characters, hyphens, and underscores, and cannot start or end with a hyphen or underscore. Premium and Ultimate only. | | `elasticsearch_retry_on_failure` | integer | no | Maximum number of possible retries for Elasticsearch search requests. Premium and Ultimate only. | +| `elasticsearch_shards` | integer or object | no | Number of shards for Elasticsearch indices. Can be an integer to set all indices to the same value, or an object to set per-index values (for example, `{"gitlab-production": 5, "gitlab-production-notes": 3}`). When using per-index values, you must also provide `elasticsearch_replicas` for the same indices. Premium and Ultimate only. | +| `elasticsearch_replicas` | integer or object | no | Number of replicas for Elasticsearch indices. Can be an integer to set all indices to the same value, or an object to set per-index values (for example, `{"gitlab-production": 1, "gitlab-production-notes": 2}`). When using per-index values, you must also provide `elasticsearch_shards` for the same indices. Premium and Ultimate only. | | `email_additional_text` | string | no | Additional text added to the bottom of every email for legal/auditing/compliance reasons. Premium and Ultimate only. | | `email_author_in_body` | boolean | no | Some email servers do not support overriding the email sender name. Enable this option to include the name of the author of the issue, merge request or comment in the email body instead. | | `email_confirmation_setting` | string | no | Specifies whether users must confirm their email before sign in. Possible values are `off`, `soft`, and `hard`. | @@ -862,6 +864,64 @@ You can configure dormant projects deletion or turn it off. The package file size limits are not part of the Application settings API. Instead, these settings can be accessed using the [Plan limits API](plan_limits.md). +### Elasticsearch index settings + +{{< details >}} + +- Tier: Premium, Ultimate +- Offering: GitLab Self-Managed, GitLab Dedicated + +{{< /details >}} + +You can configure the number of shards and replicas for Elasticsearch indices using the +`elasticsearch_shards` and `elasticsearch_replicas` parameters. + +#### Update all indices at once + +To set the same number of shards and replicas for all Elasticsearch indices: + +```shell +curl --request PUT \ + --header "PRIVATE-TOKEN: " \ + --header "Content-Type: application/json" \ + --url "https://gitlab.example.com/api/v4/application/settings" \ + --data '{ + "elasticsearch_shards": 5, + "elasticsearch_replicas": 1 + }' +``` + +#### Update specific indices individually + +To set different values for each index, pass objects with the index alias names as keys: + +```shell +curl --request PUT \ + --header "PRIVATE-TOKEN: " \ + --header "Content-Type: application/json" \ + --url "https://gitlab.example.com/api/v4/application/settings" \ + --data '{ + "elasticsearch_shards": { + "gitlab-production": 5, + "gitlab-production-notes": 3, + "gitlab-production-issues": 4 + }, + "elasticsearch_replicas": { + "gitlab-production": 1, + "gitlab-production-notes": 2, + "gitlab-production-issues": 1 + } + }' +``` + +When updating indices individually: + +- You must provide **both** `elasticsearch_shards` and `elasticsearch_replicas` for each index. +- If either value is missing for an index, that index is skipped. +- Index alias names are determined by GitLab based on the `elasticsearch_prefix` setting + (default: `gitlab`) combined with the environment and index type + (for example, `gitlab-production`, `gitlab-production-notes`, `gitlab-production-issues`). + ## Related topics - [Options for `default_branch_protection_defaults`](groups.md#options-for-default_branch_protection_defaults) -- GitLab From 51d095c1b52e6cee7a8a7f02d70106b81e4b1b8b Mon Sep 17 00:00:00 2001 From: Gerardo Navarro Date: Tue, 16 Dec 2025 21:09:05 +0100 Subject: [PATCH 2/2] refactor: Apply suggestion from @idurham --- doc/api/settings.md | 62 ++------------------------------------------- 1 file changed, 2 insertions(+), 60 deletions(-) diff --git a/doc/api/settings.md b/doc/api/settings.md index b0abf51bdbd9cd..b315e30bfa43f7 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -573,8 +573,8 @@ to configure other related settings. These requirements are | `elasticsearch_password` | string | no | The password of your Elasticsearch instance. Premium and Ultimate only. | | `elasticsearch_prefix` | string | no | Custom prefix for Elasticsearch index names. Defaults to `gitlab`. Must be 1-100 characters, contain only lowercase alphanumeric characters, hyphens, and underscores, and cannot start or end with a hyphen or underscore. Premium and Ultimate only. | | `elasticsearch_retry_on_failure` | integer | no | Maximum number of possible retries for Elasticsearch search requests. Premium and Ultimate only. | -| `elasticsearch_shards` | integer or object | no | Number of shards for Elasticsearch indices. Can be an integer to set all indices to the same value, or an object to set per-index values (for example, `{"gitlab-production": 5, "gitlab-production-notes": 3}`). When using per-index values, you must also provide `elasticsearch_replicas` for the same indices. Premium and Ultimate only. | -| `elasticsearch_replicas` | integer or object | no | Number of replicas for Elasticsearch indices. Can be an integer to set all indices to the same value, or an object to set per-index values (for example, `{"gitlab-production": 1, "gitlab-production-notes": 2}`). When using per-index values, you must also provide `elasticsearch_shards` for the same indices. Premium and Ultimate only. | +| `elasticsearch_shards` | integer or object | Yes, if `elasticsearch_replicas` is defined as an object | Number of shards for Elasticsearch indices. Use an integer to set all indices to the same value. Use an object to set per-index values. For example: `{"gitlab-production": 5, "gitlab-production-notes": 3}`.
When using an object, you must provide both `elasticsearch_shards` and `elasticsearch_replicas` for each index. If either value is missing for an index, that index is skipped. Premium and Ultimate only. | +| `elasticsearch_replicas` | integer or object | Yes, if `elasticsearch_shards` is defined as an object | Number of replicas for Elasticsearch indices. Use an integer to set all indices to the same value. Use an object to set per-index values. For example: `{"gitlab-production": 1, "gitlab-production-notes": 2}`.
When using an object, you must provide both `elasticsearch_shards` and `elasticsearch_replicas` for each index. If either value is missing for an index, that index is skipped. Premium and Ultimate only. | | `email_additional_text` | string | no | Additional text added to the bottom of every email for legal/auditing/compliance reasons. Premium and Ultimate only. | | `email_author_in_body` | boolean | no | Some email servers do not support overriding the email sender name. Enable this option to include the name of the author of the issue, merge request or comment in the email body instead. | | `email_confirmation_setting` | string | no | Specifies whether users must confirm their email before sign in. Possible values are `off`, `soft`, and `hard`. | @@ -864,64 +864,6 @@ You can configure dormant projects deletion or turn it off. The package file size limits are not part of the Application settings API. Instead, these settings can be accessed using the [Plan limits API](plan_limits.md). -### Elasticsearch index settings - -{{< details >}} - -- Tier: Premium, Ultimate -- Offering: GitLab Self-Managed, GitLab Dedicated - -{{< /details >}} - -You can configure the number of shards and replicas for Elasticsearch indices using the -`elasticsearch_shards` and `elasticsearch_replicas` parameters. - -#### Update all indices at once - -To set the same number of shards and replicas for all Elasticsearch indices: - -```shell -curl --request PUT \ - --header "PRIVATE-TOKEN: " \ - --header "Content-Type: application/json" \ - --url "https://gitlab.example.com/api/v4/application/settings" \ - --data '{ - "elasticsearch_shards": 5, - "elasticsearch_replicas": 1 - }' -``` - -#### Update specific indices individually - -To set different values for each index, pass objects with the index alias names as keys: - -```shell -curl --request PUT \ - --header "PRIVATE-TOKEN: " \ - --header "Content-Type: application/json" \ - --url "https://gitlab.example.com/api/v4/application/settings" \ - --data '{ - "elasticsearch_shards": { - "gitlab-production": 5, - "gitlab-production-notes": 3, - "gitlab-production-issues": 4 - }, - "elasticsearch_replicas": { - "gitlab-production": 1, - "gitlab-production-notes": 2, - "gitlab-production-issues": 1 - } - }' -``` - -When updating indices individually: - -- You must provide **both** `elasticsearch_shards` and `elasticsearch_replicas` for each index. -- If either value is missing for an index, that index is skipped. -- Index alias names are determined by GitLab based on the `elasticsearch_prefix` setting - (default: `gitlab`) combined with the environment and index type - (for example, `gitlab-production`, `gitlab-production-notes`, `gitlab-production-issues`). - ## Related topics - [Options for `default_branch_protection_defaults`](groups.md#options-for-default_branch_protection_defaults) -- GitLab