svn commit: r1907474 - /knox/trunk/books/2.0.0/config.md

[am...@apache.org]

Author: amagyar
Date: Mon Feb  6 17:35:55 2023
New Revision: 1907474

URL: http://svn.apache.org/viewvc?rev=1907474&view=rev
Log:
KNOX-2843 - Document SQL DB based topology monitor

Modified:
    knox/trunk/books/2.0.0/config.md

Modified: knox/trunk/books/2.0.0/config.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/2.0.0/config.md?rev=1907474&r1=1907473&r2=1907474&view=diff
==============================================================================
--- knox/trunk/books/2.0.0/config.md (original)
+++ knox/trunk/books/2.0.0/config.md Mon Feb  6 17:35:55 2023
@@ -831,11 +831,18 @@ Knox's Hadoop XML configuration parser w
 
 ##### Remote Configuration Monitor #####
 
-In addition to monitoring local directories for provider configurations and simplified descriptors, the gateway similarly supports monitoring ZooKeeper.
+In addition to monitoring local directories for provider configurations and simplified descriptors, the gateway similarly supports monitoring either ZooKeeper or an SQL database.
+
+##### Zookeeper based monitor #####
 
 This monitor depends on a [remote configuration registry client](#Remote+Configuration+Registry+Clients), and that client must be specified by setting the following property in gateway-site.xml
 
     <property>
+        <name>gateway.service.remoteconfigurationmonitor.impl</name>
+        <value>org.apache.knox.gateway.topology.monitor.db.ZkRemoteConfigurationMonitorService</value>
+    </property>
+
+    <property>
         <name>gateway.remote.config.monitor.client</name>
         <value>sandbox-zookeeper-client</value>
         <description>Remote configuration monitor client name.</description>
@@ -940,6 +947,50 @@ _While multiple such clients can be conf
 
 The [remote configuration monitor](#Remote+Configuration+Monitor) facility uses these client configurations to perform its function.
 
+
+##### SQL databse based monitor #####
+
+The SQL based remote configuration monitor works like the Zookeeper monitor, but it monitors a relational database.
+
+Enabling this monitor requires setting gateway.service.remoteconfigurationmonitor.impl in gateway-site.xml to org.apache.knox.gateway.topology.monitor.db.DbRemoteConfigurationMonitorService.
+
+    <property>
+      <name>gateway.service.remoteconfigurationmonitor.impl</name>
+      <value>org.apache.knox.gateway.topology.monitor.db.DbRemoteConfigurationMonitorService</value>
+    </property>
+
+Valid database settings need to be configured in gateway-site.xml. See "Configuring the JDBC token state service" for more information about the database configuration.
+
+    <property>
+      <name>gateway.database.type</name>
+      <value>mysql</value>
+    </property>
+    <property>
+      <name>gateway.database.connection.url</name>
+      <value>jdbc:mysql://localhost:3306/knox</value>
+    </property>
+
+With this configuration, the gateway will periodically check the content of the KNOX_PROVIDERS and KNOX_DESCRIPTORS tables and it will
+modify (create, update or delete) the local files under the shared-providers and descriptors directories respectively.
+
+ The interval (in seconds) at which the remote configuration monitor will poll the database is controlled by the following property.
+
+    gateway.remote.config.monitor.db.poll.interval.seconds
+
+The default value is 30 seconds.    
+
+
+ * If a remote configuration exists in the datbase but doesn't exist on the file system, then the monitor is going to create the file with corresponding content.
+
+ * If an existing remote configuration was deleted from the database (logical deletion) but it still exists on the local file system, then the monitor is going to delete the corresponding file. The logically deleted records are eventually cleared up by the monitor.
+
+ * If a remote configuration exists in the database with a different content than the local file, then the monitor is going to update the
+content of the local file with the content from the database. However to avoid unnecessary IO operations the monitor only updates the
+content once and if there were no further changes in the database since this last update time, then it will skip changing the local content
+until a new change happens in the database (indicated by the last_modified_time column). This means you can do temporary changes on the local file system without losing your modifications (until a change happens in the database).
+
+The content of the database *must* be changed by the Knox Admin UI or the by the Admin API.
+
 #### Remote Alias Service ####
 
 Knox can be configured to use a remote alias service. The remote alias service is pluggable to support multiple different backends. The feature can be disabled by setting the property `gateway.remote.alias.service.enabled` to `false` in `gateway-site.xml`. Knox needs to be restarted for this change to take effect.