You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@knox.apache.org by kr...@apache.org on 2019/03/18 18:42:50 UTC
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
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 “gateway.remote.alias.service.enabled” 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><property>
<name>gateway.remote.alias.service.enabled</name>
<value>false</value>
- <description>Turn on/off Remote Alias Discovery(true by default)</description>
+ <description>Turn on/off Remote Alias service (true by default)</description>
</property>
</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 ####