[kudu] branch master updated: [doc] note on having at least 3 locations for better HA

[al...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

alexey pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/kudu.git


The following commit(s) were added to refs/heads/master by this push:
     new 89bac59  [doc] note on having at least 3 locations for better HA
89bac59 is described below

commit 89bac5989e3582afb791cedf494443a7c934dade
Author: Alexey Serbin <al...@apache.org>
AuthorDate: Fri Sep 25 12:31:07 2020 -0700

    [doc] note on having at least 3 locations for better HA
    
    This patch adds a note on defining at least three locations to increase
    the availability of a Kudu cluster when location awareness is enabled.
    Sure, it's obvious if understanding how the placement policy works,
    but for the first-time readers it might be a good heads-up.
    
    Change-Id: Ib0d8d2e7d917205c62aca567eb2b2db540f7857e
    Reviewed-on: http://gerrit.cloudera.org:8080/16514
    Tested-by: Kudu Jenkins
    Reviewed-by: Greg Solovyev <gs...@cloudera.com>
    Reviewed-by: Andrew Wong <aw...@cloudera.com>
---
 docs/administration.adoc | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/docs/administration.adoc b/docs/administration.adoc
index 9ad27a8..ec6d3cd 100644
--- a/docs/administration.adoc
+++ b/docs/administration.adoc
@@ -219,12 +219,14 @@ single node failure. However, clusters can be vulnerable to correlated failures
 of multiple nodes. For example, all of the physical hosts on the same rack in
 a datacenter may become unavailable simultaneously if the top-of-rack switch
 fails. Kudu's rack awareness feature provides protection from some kinds of
-correlated failures, like the failure of a single rack in a datacenter.
-
-The first element of Kudu's rack awareness feature is location assignment. When
-a tablet server or client registers with a master, the master assigns it a
-location. A location is a `/`-separated string that begins with a `/` and where
-each `/`-separated component consists of characters from the set
+correlated failures, like the failure of a whole rack in a datacenter. Rack
+awareness increases the availability of a Kudu cluster if there are at least
+three different _locations_ defined in the cluster.
+
+The first element of Kudu's rack awareness feature is _location assignment_.
+When a tablet server or client registers with a master, the master assigns it a
+_location_. A location is a `/`-separated string that begins with a `/` and
+where each `/`-separated component consists of characters from the set
 `[a-zA-Z0-9_-.]`. For example, `/dc-0/rack-09` is a valid location, while
 `rack-04` and `/rack=1` are not valid locations. Thus location strings resemble
 absolute UNIX file paths where characters in directory and file names are
@@ -236,7 +238,7 @@ argument, the IP address or hostname of a tablet server or client, and return
 the location for the tablet server or client. Make sure that all Kudu masters
 are using the same location mapping command.
 
-The second element of Kudu's rack awareness feature is the placement policy,
+The second element of Kudu's rack awareness feature is the _placement policy_,
 which is
 
   Do not place a majority of replicas of a tablet on tablet servers in the same location.
@@ -252,6 +254,11 @@ location `/L0`. As another example, if a tablet has replicas on tablet servers
 `A`, `C`, and `E`, and then `C` fails, the replacement replica must be placed on
 `D` in order to comply with the placement policy.
 
+It's necessary to have at least three locations defined in a Kudu cluster to
+improve its high availability with the location awareness feature. If there are
+only two or just one location defined in a Kudu cluster, any tablet will
+inevitably have a majority of its replicas placed in a single location.
+
 In the case where it is impossible to place replicas in a way that complies with
 the placement policy, Kudu will violate the policy and place a replica anyway.
 For example, using the setup described in the previous paragraph, if a tablet
@@ -266,8 +273,8 @@ moved to comply with the placement policy. See
 <<rebalancer_tool_with_rack_awareness,running the tablet rebalancing tool on a rack-aware cluster>>
 for more information.
 
-The third and final element of Kudu's rack awareness feature is the use of
-client locations to find "nearby" servers. As mentioned, the masters also
+The third and final element of Kudu's rack awareness feature is the _use of
+client locations to find "nearby" servers_. As mentioned, the masters also
 assign a location to clients when they connect to the cluster. The client
 (whether Java, {cpp}, or Python) uses its own location and the locations of
 tablet servers in the cluster to prefer "nearby" replicas when scanning in