knox-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kris...@apache.org
Subject svn commit: r1855787 - in /knox: site/books/knox-1-3-0/user-guide.html trunk/books/1.3.0/book.md trunk/books/1.3.0/config.md
Date Mon, 18 Mar 2019 18:42:50 GMT
Author: krisden
Date: Mon Mar 18 18:42:50 2019
New Revision: 1855787

URL: http://svn.apache.org/viewvc?rev=1855787&view=rev
Log:
KNOX-1805 - Documentation for KNOX-1687 Hashicorp Vault RemoteAliasService provider

Modified:
    knox/site/books/knox-1-3-0/user-guide.html
    knox/trunk/books/1.3.0/book.md
    knox/trunk/books/1.3.0/config.md

Modified: knox/site/books/knox-1-3-0/user-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-1-3-0/user-guide.html?rev=1855787&r1=1855786&r2=1855787&view=diff
==============================================================================
--- knox/site/books/knox-1-3-0/user-guide.html (original)
+++ knox/site/books/knox-1-3-0/user-guide.html Mon Mar 18 18:42:50 2019
@@ -52,11 +52,11 @@
         <ul>
           <li><a href="#Remote+Configuration+Monitor">Remote Configuration Monitor</a></li>
           <li><a href="#Remote+Configuration+Registry+Clients">Remote Configuration
Registry Clients</a></li>
-          <li><a href="#Remote+Alias+Discovery">Remote Alias Discovery</a></li>
           <li><a href="#Topology+Descriptors">Topology Descriptors</a></li>
           <li><a href="#Hostmap+Provider">Hostmap Provider</a></li>
         </ul>
       </li>
+      <li><a href="#Remote+Alias+Service">Remote Alias Service</a></li>
       <li><a href="#Knox+CLI">Knox CLI</a></li>
       <li><a href="#Admin+API">Admin API</a></li>
       <li><a href="#X-Forwarded-*+Headers+Support">X-Forwarded-* Headers Support</a></li>
@@ -938,7 +938,7 @@ https://{gateway-host}:{gateway-port}/{g
     </tr>
     <tr>
       <td><code>gateway.remote.alias.service.enabled</code> </td>
-      <td>Turn on/off remote alias management, this will take effect only when remote
configuration monitoring is enabled </td>
+      <td>Turn on/off remote alias service </td>
       <td><code>true</code></td>
     </tr>
     <tr>
@@ -1506,14 +1506,46 @@ trustworthiness.
 </code></pre>
 <p><em>While multiple such clients can be configured, for ZooKeeper clients,
there is currently a limitation with respect to authentication. Multiple clients cannot each
have distinct authentication configurations. This limitation is imposed by the underlying
ZooKeeper client. Therefore, the clients must all be insecure (no authentication configured),
or they must all authenticate to the same ZooKeeper using the same credentials.</em></p>
 <p>The <a href="#Remote+Configuration+Monitor">remote configuration monitor</a>
facility uses these client configurations to perform its function.</p>
-<h4><a id="Remote+Alias+Discovery">Remote Alias Discovery</a> <a href="#Remote+Alias+Discovery"><img
src="markbook-section-link.png"/></a></h4>
-<p>Knox will also monitor for remote aliases that are added, deleted or updated. By
default this is turned on (if Remote Configuration Monitor is on) and will sync all the aliases.
In case one wants to turn off this feature they can do so by using the property &ldquo;gateway.remote.alias.service.enabled&rdquo;
in gateway-site.xml. Knox needs to be restarted for this change to take effect. </p>
+<h4><a id="Remote+Alias+Service">Remote Alias Service</a> <a href="#Remote+Alias+Service"><img
src="markbook-section-link.png"/></a></h4>
+<p>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 <code>gateway.remote.alias.service.enabled</code> to <code>false</code>
in <code>gateway-site.xml</code>. Knox needs to be restarted for this change to
take effect.</p>
 <pre><code>&lt;property&gt;
     &lt;name&gt;gateway.remote.alias.service.enabled&lt;/name&gt;
     &lt;value&gt;false&lt;/value&gt;
-    &lt;description&gt;Turn on/off Remote Alias Discovery(true by default)&lt;/description&gt;
+    &lt;description&gt;Turn on/off Remote Alias service (true by default)&lt;/description&gt;
 &lt;/property&gt;
 </code></pre>
+<p>The type of remote alias service can be configured by default using <code>gateway.remote.alias.service.config.type</code>.
If necessary the remote alias service config prefix can be changed with <code>gateway.remote.alias.service.config.prefix</code>.
Changing the prefix affects all remote alias service configurations.</p>
+<h5><a id="Remote+Alias+Service+-+HashiCorp+Vault">Remote Alias Service - HashiCorp
Vault</a> <a href="#Remote+Alias+Service+-+HashiCorp+Vault"><img src="markbook-section-link.png"/></a></h5>
+<p>The HashiCorp Vault remote alias service is deigned to store aliases into HashiCorp
Vault. It is configured by setting <code>gateway.remote.alias.service.config.type</code>
to <code>hashicorp.vault</code> in gateway-site.xml. The table below highlights
configuration parameters for the HashiCorp Vault remote alias service. Knox needs to be restarted
for this change to take effect.</p>
+<table>
+  <thead>
+    <tr>
+      <th>Property </th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>gateway.remote.alias.service.config.hashicorp.vault.address</code></td>
+      <td>Address of the HashiCorp Vault server</td>
+    </tr>
+    <tr>
+      <td><code>gateway.remote.alias.service.config.hashicorp.vault.secrets.engine</code></td>
+      <td>HashiCorp Vault secrets engine</td>
+    </tr>
+    <tr>
+      <td><code>gateway.remote.alias.service.config.hashicorp.vault.path.prefix</code></td>
+      <td>HashiCorp Vault secrets engine path prefix</td>
+    </tr>
+  </tbody>
+</table>
+<p>There are multiple authentication mechanisms supported by HashiCorp Vault. Knox
supports pluggable authentication mechanisms. The authentication type is configured by setting
<code>gateway.remote.alias.service.config.hashicorp.vault.authentication.type</code>
in gateway-site.xml.</p>
+<p><strong>Token Authentication</strong></p>
+<p>Token authentication takes a single setting <code>gateway.remote.alias.service.config.hashicorp.vault.authentication.token</code>
and takes either the value of the authentication token or a local alias configured with <code>${ALIAS=token_name}</code>.</p>
+<p><strong>Kubernetes Authentication</strong></p>
+<p>Kubernetes authentication takes a single setting <code>gateway.remote.alias.service.config.hashicorp.vault.authentication.kubernetes.role</code>
which defines the role to use when connecting to Vault. The Kubernetes authentication mechanism
uses the secrets prepopulated into a K8S pod to authenticate to Vault. Knox can then use the
secrets from Vault after being authenticated.</p>
+<h5><a id="Remote+Alias+Service+-+Zookeeper">Remote Alias Service - Zookeeper</a>
<a href="#Remote+Alias+Service+-+Zookeeper"><img src="markbook-section-link.png"/></a></h5>
+<p>The Zookeeper remote alias service is designed to store aliases into Apache Zookeeper.
It supports monitoring for remote aliases that are added, deleted or updated. The Zookeeper
remote alias service is configured by turning the Remote Configuration Monitor on and setting
<code>gateway.remote.alias.service.config.type</code> to <code>zookeeper</code>
in gateway-site.xml. Knox needs to be restarted for this change to take effect. </p>
 <h4><a id="Logging">Logging</a> <a href="#Logging"><img src="markbook-section-link.png"/></a></h4>
 <p>If necessary you can enable additional logging by editing the <code>log4j.properties</code>
file in the <code>conf</code> directory. Changing the <code>rootLogger</code>
value from <code>ERROR</code> to <code>DEBUG</code> will generate
a large amount of debug logging. A number of useful, more fine loggers are also provided in
the file.</p>
 <h4><a id="Java+VM+Options">Java VM Options</a> <a href="#Java+VM+Options"><img
src="markbook-section-link.png"/></a></h4>

Modified: knox/trunk/books/1.3.0/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.3.0/book.md?rev=1855787&r1=1855786&r2=1855787&view=diff
==============================================================================
--- knox/trunk/books/1.3.0/book.md (original)
+++ knox/trunk/books/1.3.0/book.md Mon Mar 18 18:42:50 2019
@@ -45,9 +45,9 @@
     * #[Cluster Configuration Monitoring]
         * #[Remote Configuration Monitor]
         * #[Remote Configuration Registry Clients]
-        * #[Remote Alias Discovery]
         * #[Topology Descriptors]
         * #[Hostmap Provider]
+    * #[Remote Alias Service]
     * #[Knox CLI]
     * #[Admin API]
     * #[X-Forwarded-* Headers Support]

Modified: knox/trunk/books/1.3.0/config.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/1.3.0/config.md?rev=1855787&r1=1855786&r2=1855787&view=diff
==============================================================================
--- knox/trunk/books/1.3.0/config.md (original)
+++ knox/trunk/books/1.3.0/config.md Mon Mar 18 18:42:50 2019
@@ -157,7 +157,7 @@ Property    | Description | Default
 `gateway.remote.config.registry.<name>`|A named [remote configuration registry client](#Remote+Configuration+Registry+Clients)
definition, where _name_ is an arbitrary identifier for the connection|null
 `gateway.cluster.config.monitor.ambari.enabled`| Indicates whether the cluster monitoring
and associated dynamic topology updating is enabled | `false`
 `gateway.cluster.config.monitor.ambari.interval` | The interval (in seconds) at which the
cluster monitor will poll Ambari for cluster configuration changes | `60`
-`gateway.remote.alias.service.enabled` | Turn on/off remote alias management, this will take
effect only when remote configuration monitoring is enabled  | `true`
+`gateway.remote.alias.service.enabled` | Turn on/off remote alias service | `true`
 `gateway.read.only.override.topologies` | A comma-delimited list of topology names which
should be forcibly treated as read-only. | none
 `gateway.discovery.default.address` | The default discovery address, which is applied if
no address is specified in a descriptor. | null
 `gateway.discovery.default.cluster` | The default discovery cluster name, which is applied
if no cluster name is specified in a descriptor. | null
@@ -796,16 +796,42 @@ _While multiple such clients can be conf
 
 The [remote configuration monitor](#Remote+Configuration+Monitor) facility uses these client
configurations to perform its function.
 
-#### Remote Alias Discovery ####
+#### Remote Alias Service ####
 
-Knox will also monitor for remote aliases that are added, deleted or updated. By default
this is turned on (if Remote Configuration Monitor is on) and will sync all the aliases. In
case one wants to turn off this feature they can do so by using the property "gateway.remote.alias.service.enabled"
in gateway-site.xml. Knox needs to be restarted for this change to take effect. 
+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.
 
-    <property>
-        <name>gateway.remote.alias.service.enabled</name>
-        <value>false</value>
-        <description>Turn on/off Remote Alias Discovery(true by default)</description>
-    </property>
+```
+<property>
+    <name>gateway.remote.alias.service.enabled</name>
+    <value>false</value>
+    <description>Turn on/off Remote Alias service (true by default)</description>
+</property>
+```
+
+The type of remote alias service can be configured by default using `gateway.remote.alias.service.config.type`.
If necessary the remote alias service config prefix can be changed with `gateway.remote.alias.service.config.prefix`.
Changing the prefix affects all remote alias service configurations.
+##### Remote Alias Service - HashiCorp Vault #####
+
+The HashiCorp Vault remote alias service is deigned to store aliases into HashiCorp Vault.
It is configured by setting `gateway.remote.alias.service.config.type` to `hashicorp.vault`
in gateway-site.xml. The table below highlights configuration parameters for the HashiCorp
Vault remote alias service. Knox needs to be restarted for this change to take effect.
+
+Property    | Description
+------------|------------
+`gateway.remote.alias.service.config.hashicorp.vault.address`|Address of the HashiCorp Vault
server
+`gateway.remote.alias.service.config.hashicorp.vault.secrets.engine`|HashiCorp Vault secrets
engine
+`gateway.remote.alias.service.config.hashicorp.vault.path.prefix`|HashiCorp Vault secrets
engine path prefix
+
+There are multiple authentication mechanisms supported by HashiCorp Vault. Knox supports
pluggable authentication mechanisms. The authentication type is configured by setting `gateway.remote.alias.service.config.hashicorp.vault.authentication.type`
in gateway-site.xml.
+
+__Token Authentication__
+
+Token authentication takes a single setting `gateway.remote.alias.service.config.hashicorp.vault.authentication.token`
and takes either the value of the authentication token or a local alias configured with `${ALIAS=token_name}`.
+
+__Kubernetes Authentication__
+
+Kubernetes authentication takes a single setting `gateway.remote.alias.service.config.hashicorp.vault.authentication.kubernetes.role`
which defines the role to use when connecting to Vault. The Kubernetes authentication mechanism
uses the secrets prepopulated into a K8S pod to authenticate to Vault. Knox can then use the
secrets from Vault after being authenticated.
+
+##### Remote Alias Service - Zookeeper #####
 
+The Zookeeper remote alias service is designed to store aliases into Apache Zookeeper. It
supports monitoring for remote aliases that are added, deleted or updated. The Zookeeper remote
alias service is configured by turning the Remote Configuration Monitor on and setting `gateway.remote.alias.service.config.type`
to `zookeeper` in gateway-site.xml. Knox needs to be restarted for this change to take effect.

 
 #### Logging ####
 



Mime
View raw message