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.
