Cluster Forced Allocation Awareness

Elastic Stack Elasticsearch
1

I believe I found a mistake in the documentation on the ES website.
on the page:
http://www.elasticsearch.org/guide/reference/modules/cluster.html
Under "Forced Awareness"
We have the paragraph

cluster.routing.allocation.awareness.force.zone.values: zone1,zone2
cluster.routing.allocation.awareness.attributes: zone

Now, lets say we start 2 nodes with |node.zone| set to |zone1| and
create an index with 5 shards and 1 replica.
The index will be created, but only 5 shards will be allocated (with no
replicas).
Only when we start more shards with |node.zone| set to |zone2| will the
replicas be allocated.

If I understand correctly,
The 2nd line says that "zone" is the awareness attribute that will
control how shards and their replicas are allocated.
The 1st line says that the values for the zone awareness attribute is
limited to zone1 and zone2.
What is never said on this page (or other I can find) is that a primary
shard and it's replica(s) will not be allocated to two nodes with the
same allocation awareness attribute.
Re-writing the paragraph that I think has a typo in its last sentence I
might say:

Now, lets say we start 2 nodes with node.zone set to zone1 and create an index specifying 5 shards and 1 replica. The index will be created, but only 5 shards with no replicas will be created. Some of the shards will be on one of the zone1 nodes and some on the other zone1 node, but replicas will NOT allocated to the same awareness attribute, so NO REPLICAS will be created. Now, we start 2 more nodes with node.zone set to "zone2", only then will the replicas be allocated to the separate zone "zone2".

Note that the last sentence used to say "start 2 more SHARDS", but now
it says "start 2 more NODES." Other changes are attempts by me to
provide some explanation.

What is not stated is what happens to creation of replicas, when there
is to c.r.a.awareness.force...

Please correct me if I am wrong.

I find the end of this same page to be confusing. Am I right to say that:

  1. cluster.routing.allocation.awareness.force. controls
    onto which nodes the primary and replicas are separately allocated
    while
  2. |index.routing.allocation.include. and
    ||index.routing.allocation.include. ||controls onto
    which nodes an index (primary shards and replica shards together) are
    allocated?
    |

|As far as I can tell, the examples in the index.routing section
starting at "| For example, here is a sample of several node
configurations:" |provide NO useful information, because
It doesn't describe on which nodes the node.group1 : "group1_value1" and
node.group2 : "group2_value4" values are defined.
It does not include any REST call (maybe a index create call?) that
would change behavior based on such values.
It also does not go on to describe what happens (and when), once you
have (re)defined new group1, group2 and group3 values to "xxx", "yyy",
and "zzz".
Somehow the example gained a group3 without explanation.
|

|Reading the other section I would think we'd need some combination of
nodes with node.group1 : "xxx" and node.group2 : "yyy" and node.group3 :
"zzz" defined and then the index (primary shards and replicas) would be
allocated using the node attributes, but there is no such scenario
described on the page.
|

|I'm thinking someone left and example incomplete on this page, but I am
not able to make sense of it, so can not offer a re-write.
|

thanks,
-Paul

--