From 69a8c924d2ba4a8cb5fc8e5b2084c38ce42bca18 Mon Sep 17 00:00:00 2001 From: David Turner Date: Tue, 2 Apr 2024 09:18:59 +0100 Subject: [PATCH] Expand docs on reset desired balance API (#106921) Explains its purpose and surrounding context a little more, including a note that this should never be necessary (i.e. if you find you need it, that's a bug). --- docs/reference/cluster/delete-desired-balance.asciidoc | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/reference/cluster/delete-desired-balance.asciidoc b/docs/reference/cluster/delete-desired-balance.asciidoc index 7b89fed881e41..f81dcab011da4 100644 --- a/docs/reference/cluster/delete-desired-balance.asciidoc +++ b/docs/reference/cluster/delete-desired-balance.asciidoc @@ -6,9 +6,13 @@ NOTE: {cloud-only} -Resets the desired balance and starts a new computation from the current allocation. -This API may be used if desired balance computation diverged from the current state -and is trying to move too many shards. +Discards the current desired balance and computes a new desired balance starting from the current allocation of shards. +This can sometimes help {es} find a desired balance which needs fewer shard movements to achieve, especially if the +cluster has experienced changes so substantial that the current desired balance is no longer optimal without {es} having +detected that the current desired balance will take more shard movements to achieve than needed. However, this API +imposes a heavy load on the elected master node and may not always have the expected effect. Calling this API should +never be necessary. Consider instead <> to avoid excessive shard movements. [[delete-desired-balance-request]] ==== {api-request-title}