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 ####
