HBASE-28063 Document how to configure TLS settings to ZooKeeper client (#5383)

Signed-off-by: [email protected]

Author: anmolnar

src/main/asciidoc/_chapters/zookeeper.adoc

@@ -441,7 +441,74 @@ This would avoid the need for a separate Hadoop jar that fixes link:https://issu
 
 ==== Elimination of `kerberos.removeHostFromPrincipal` and`kerberos.removeRealmFromPrincipal`
 
+== TLS connection to ZooKeeper
 
+Apache ZooKeeper also supports SSL/TLS client connections to encrypt the data in transmission. This is particularly
+useful when the ZooKeeper ensemble is running on a host different from HBase and data has to be sent
+over the wire.
+
+=== Java system properties
+
+The ZooKeeper client supports the following Java system properties to set up TLS connection:
+
+[source,bourne]
+----
+zookeeper.client.secure=true
+zookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty
+zookeeper.ssl.keyStore.location="/path/to/your/keystore"
+zookeeper.ssl.keyStore.password="keystore_password"
+zookeeper.ssl.trustStore.location="/path/to/your/truststore"
+zookeeper.ssl.trustStore.password="truststore_password"
+----
+
+Setting up KeyStore is optional and only required if ZooKeeper server requests for client certificate.
+
+Find more detailed information in the link:https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeper+SSL+User+Guide[ZooKeeper SSL User Guide].
+
+[WARNING]
+These're standard Java properties which should be set in the HBase command line and are effective in
+the entire Java process. All ZooKeeper clients running in the same process will pick them up including
+co-processors.
+
+[NOTE]
+Since ZooKeeper version 3.8 the following two properties are useful to store the
+keystore and truststore passwords in protected text files rather than exposing them in the command line.
+
+[source,bourne]
+----
+zookeeper.ssl.keyStore.passwordPath=/path/to/secure/file
+zookeeper.ssl.trustStore.passwordPath=/path/to/secure/file
+----
+
+=== HBase configuration
+
+By adding link:https://issues.apache.org/jira/browse/HBASE-28038[HBASE-28038], ZooKeeper client TLS
+settings are also available in _hbase-site.xml_ via `hbase.zookeeper.property` prefix. In contrast
+to Java system properties this could be more convenient under some circumstances.
+
+[source,xml]
+----
+
+<configuration>
+  <property>
+    <name>hbase.zookeeper.property.client.secure</name>
+    <value>true</value>
+  </property>
+  <property>
+    <name>hbase.zookeeper.property.clientCnxnSocket</name>
+    <value>org.apache.zookeeper.ClientCnxnSocketNetty</value>
+  </property>
+  <property>
+    <name>hbase.zookeeper.property.ssl.trustStore.location</name>
+    <value>/path/to/your/truststore</value>
+  </property>
+...
+</configuration>
+----
+
+[NOTE]
+These settings are eventually transformed into Java system properties, it's just a convenience feature.
+So, the same rules that mentioned in the previous point, applies to them as well.
 
 ifdef::backend-docbook[]
 [index]