Parameter improvements to Cluster Health API wait for shards

[abeyad]

Previously, the cluster health API used a strictly numeric value for wait_for_active_shards. However, with the introduction of ActiveShardCount and the removal of write consistency level for replication operations, wait_for_active_shards is used for write operations to represent values for ActiveShardCount. This PR moves the cluster health API's usage of wait_for_active_shards to be consistent with its usage in the write operation APIs.

This PR also changes wait_for_relocating_shards from a numeric value to a simple boolean value wait_for_no_relocating_shards to set whether the cluster health operation should wait for
all relocating shards to complete relocation.

Breaking changes summary:

1. wait_for_active_shards: this is not a breaking change because the same numeric values that were allowed before are allowed now. We have just added the ability to specify all as well, in conformity with the the write operation APIs that also use wait_for_active_shards
2. wait_for_no_relocating_shards: this is a breaking change because it differs from the old name wait_for_relocating_shards and it takes a boolean value to represent whether we should wait for the cluster to have no relocations, whereas the old wait_for_relocating_shards took a number to represent how many relocating shards to wait on (if this value was set, it was pretty much always set to 0)

Closes #20216

[abeyad]

@elasticmachine retest this please

[nik9000]

{@code false}?

[nik9000]

Left a few minor things, mostly documentation wording suggestions. LGTM.

[abeyad]

@nik9000 thanks for the review! i pushed b50e472 that addresses your comments

[nik9000]

LGTM

[clintongormley]

I'm OK with this change, but I would add a check for wait_for_relocating_shards and throw an exception if present, otherwise this parameter will just be silently ignored.

it'd be better to make REST param parsing strict (#14719) rather than dealing with these on a case-by-case basis

[abeyad]

@clintongormley I pushed a commit to check for the old param and throw an exception: e4e946b

I agree that it would be good to have a general solution to making REST param parsing strict

[niemyjski]

So in our use case when we create an index we want to block client calls until all shards are created but we don't care about replicas. So I guess with this change I would need to specify all. Personally, I'd like if it was more like cluster heath api and I could just wait for yellow as shard size might not be known... But all works for me.

[abeyad]

@niemyjski you wouldn't need to specify anything, because in 5.0, by default index creation will not return until all of the primary shards are active (see #18985).

Suppose you had 2 replicas in addition to your primary. If you wanted to wait for at least 1 replica to become active in addition to the primaries before proceeding with the write, then you would use wait_for_active_shards=2 (1 for primary plus 1 for replica). If you wanted to wait for all replicas, you would specify wait_for_active_shards=3 or more easier wait_for_active_shards=all

[niemyjski]

Awesome! I didn't get that from reading the docs, that's good to know!

[bleskes]

Awesome! I didn't get that from reading the docs, that's good to know!

@niemyjski if you have any suggestion on how to improve the docs, please let us know (just click that edit button on the website :))