ZOOKEEPER-2240 Make the three-node minimum more explicit in documentation and on website (Shawn Heisey and Arshad Mohammad via phunt)

git-svn-id: https://svn.apache.org/repos/asf/zookeeper/trunk@1735836 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -398,6 +398,9 @@ IMPROVEMENTS:
   ZOOKEEPER-2300: Expose SecureClientPort and SecureClientAddress JMX properties
   (Arshad Mohammad via rgs)
 
+  ZOOKEEPER-2240 Make the three-node minimum more explicit in 
+  documentation and on website (Shawn Heisey and Arshad Mohammad via phunt)
+
 Release 3.5.0 - 8/4/2014
 
 NEW FEATURES:

docs/zookeeperAdmin.html

@@ -519,6 +519,35 @@ document.write("Last Published: " + document.lastModified);
       only handle the failure of a single machine; if two machines fail, the
       remaining two machines do not constitute a majority. However, with five
       machines ZooKeeper can handle the failure of two machines. </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+         
+<p>
+            As mentioned in the
+            <a href="zookeeperStarted.html">ZooKeeper Getting Started Guide</a>
+            , a minimum of three servers are required for a fault tolerant
+            clustered setup, and it is strongly recommended that you have an
+            odd number of servers.
+         </p>
+         
+<p>Usually three servers is more than enough for a production
+            install, but for maximum reliability during maintenance, you may
+            wish to install five servers. With three servers, if you perform
+            maintenance on one of them, you are vulnerable to a failure on one
+            of the other two servers during that maintenance. If you have five
+            of them running, you can take one down for maintenance, and know
+            that you're still OK if one of the other four suddenly fails.
+         </p>
+         
+<p>Your redundancy considerations should include all aspects of
+            your environment. If you have three ZooKeeper servers, but their
+            network cables are all plugged into the same network switch, then
+            the failure of that switch will take down your entire ensemble.
+         </p>
+      
+</div>
+</div>
 <p>Here are the steps to setting a server that will be part of an
       ensemble. These steps should be performed on every host in the
       ensemble:</p>

docs/zookeeperStarted.html

@@ -522,8 +522,30 @@ numChildren = 0
       ZooKeeper in replicated mode. A replicated group of servers in the same
       application is called a <em>quorum</em>, and in replicated
       mode, all servers in the quorum have copies of the same configuration
-      file. The file is similar to the one used in standalone mode, but with a
-      few differences. Here is an example:</p>
+      file.</p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+      
+<p>
+         For replicated mode, a minimum of three servers are required,
+         and it is strongly recommended that you have an odd number of
+         servers. If you only have two servers, then you are in a
+         situation where if one of them fails, there are not enough
+         machines to form a majority quorum. Two servers is inherently
+         <strong>less</strong>
+         stable than a single server, because there are two single
+         points of failure.
+      </p>
+   
+</div>
+</div>
+<p>
+      The required
+      <strong>conf/zoo.cfg</strong>
+      file for replicated mode is similar to the one used in standalone
+      mode, but with a few differences. Here is an example:
+   </p>
 <pre class="code">
 tickTime=2000
 dataDir=/var/lib/zookeeper
@@ -572,6 +594,14 @@ server.3=zoo3:2888:3888
         (in the above replicated example, running on a
         single <em>localhost</em>, you would still have
         three config files).</p>
+        
+<p>Please be aware that setting up multiple servers on a single
+            machine will not create any redundancy. If something were to
+            happen which caused the machine to die, all of the zookeeper
+            servers would be offline. Full redundancy requires that each
+            server have its own machine. It must be a completely separate
+            physical server. Multiple virtual machines on the same physical
+            host are still vulnerable to the complete failure of that host.</p>
       
 </div>
 </div>

src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml

@@ -186,7 +186,28 @@
       only handle the failure of a single machine; if two machines fail, the
       remaining two machines do not constitute a majority. However, with five
       machines ZooKeeper can handle the failure of two machines. </para>
-
+      <note>
+         <para>
+            As mentioned in the
+            <ulink url="zookeeperStarted.html">ZooKeeper Getting Started Guide</ulink>
+            , a minimum of three servers are required for a fault tolerant
+            clustered setup, and it is strongly recommended that you have an
+            odd number of servers.
+         </para>
+         <para>Usually three servers is more than enough for a production
+            install, but for maximum reliability during maintenance, you may
+            wish to install five servers. With three servers, if you perform
+            maintenance on one of them, you are vulnerable to a failure on one
+            of the other two servers during that maintenance. If you have five
+            of them running, you can take one down for maintenance, and know
+            that you're still OK if one of the other four suddenly fails.
+         </para>
+         <para>Your redundancy considerations should include all aspects of
+            your environment. If you have three ZooKeeper servers, but their
+            network cables are all plugged into the same network switch, then
+            the failure of that switch will take down your entire ensemble.
+         </para>
+      </note>
       <para>Here are the steps to setting a server that will be part of an
       ensemble. These steps should be performed on every host in the
       ensemble:</para>

src/docs/src/documentation/content/xdocs/zookeeperStarted.xml

@@ -342,8 +342,25 @@ numChildren = 0
       ZooKeeper in replicated mode. A replicated group of servers in the same
       application is called a <emphasis>quorum</emphasis>, and in replicated
       mode, all servers in the quorum have copies of the same configuration
-      file. The file is similar to the one used in standalone mode, but with a
-      few differences. Here is an example:</para>
+      file.</para>
+   <note>
+      <para>
+         For replicated mode, a minimum of three servers are required,
+         and it is strongly recommended that you have an odd number of
+         servers. If you only have two servers, then you are in a
+         situation where if one of them fails, there are not enough
+         machines to form a majority quorum. Two servers is inherently
+         <emphasis role="bold">less</emphasis>
+         stable than a single server, because there are two single
+         points of failure.
+      </para>
+   </note>
+   <para>
+      The required
+      <emphasis role="bold">conf/zoo.cfg</emphasis>
+      file for replicated mode is similar to the one used in standalone
+      mode, but with a few differences. Here is an example:
+   </para>
 
 <programlisting>
 tickTime=2000
@@ -396,6 +413,13 @@ server.3=zoo3:2888:3888
         (in the above replicated example, running on a
         single <emphasis>localhost</emphasis>, you would still have
         three config files).</para>
+        <para>Please be aware that setting up multiple servers on a single
+            machine will not create any redundancy. If something were to
+            happen which caused the machine to die, all of the zookeeper
+            servers would be offline. Full redundancy requires that each
+            server have its own machine. It must be a completely separate
+            physical server. Multiple virtual machines on the same physical
+            host are still vulnerable to the complete failure of that host.</para>
       </note>
     </section>