Author: pzampino
Date: Sat Jun 30 17:05:31 2018
New Revision: 1834754
URL: http://svn.apache.org/viewvc?rev=1834754&view=rev
Log:
Minor updates to Knox HA section
Modified:
knox/site/books/knox-1-1-0/user-guide.html
knox/trunk/books/1.1.0/config_ha.md
Modified: knox/site/books/knox-1-1-0/user-guide.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-1-0/user-guide.html?rev=1834754&r1=1834753&r2=1834754&view=diff
==============================================================================
--- knox/site/books/knox-1-1-0/user-guide.html (original)
+++ knox/site/books/knox-1-1-0/user-guide.html Sat Jun 30 17:05:31 2018
@@ -3225,15 +3225,16 @@ exit
</code></pre><p>Copy knox.service.keytab created on KDC host on to your Knox
host <code>{GATEWAY_HOME}/conf/knox.service.keytab</code></p>
<pre><code>chown knox knox.service.keytab
chmod 400 knox.service.keytab
-</code></pre><h4><a
id="Update+`krb5.conf`+at+`{GATEWAY_HOME}/conf/krb5.conf`+on+Knox+host">Update
<code>krb5.conf</code> at <code>{GATEWAY_HOME}/conf/krb5.conf</code> on Knox
host</a> <a
href="#Update+`krb5.conf`+at+`{GATEWAY_HOME}/conf/krb5.conf`+on+Knox+host"><img
src="markbook-section-link.png"/></a></h4><p>You could copy the
<code>{GATEWAY_HOME}/templates/krb5.conf</code> file provided in the Knox
binary download and customize it to suit your cluster.</p><h4><a
id="Update+`krb5JAASLogin.conf`+at+`/etc/knox/conf/krb5JAASLogin.conf`+on+Knox+host">Update
<code>krb5JAASLogin.conf</code> at
<code>/etc/knox/conf/krb5JAASLogin.conf</code> on Knox host</a> <a
href="#Update+`krb5JAASLogin.conf`+at+`/etc/knox/conf/krb5JAASLogin.conf`+on+Knox+host"><img
src="markbook-section-link.png"/></a></h4><p>You could copy the
<code>{GATEWAY_HOME}/templates/krb5JAASLogin.conf</code> file provided in the
Knox binary download and customize it to suit your cluster.</p><h4><a
id="Update+`gateway-site.xm
l`+on+Knox+host">Update <code>gateway-site.xml</code> on Knox host</a> <a
href="#Update+`gateway-site.xml`+on+Knox+host"><img
src="markbook-section-link.png"/></a></h4><p>Update
<code>conf/gateway-site.xml</code> in your Knox installation and set the value
of <code>gateway.hadoop.kerberos.secured</code> to true.</p><h4><a
id="Restart+Knox">Restart Knox</a> <a href="#Restart+Knox"><img
src="markbook-section-link.png"/></a></h4><p>After you do the above
configurations and restart Knox, Knox would use SPNego to authenticate with
Hadoop services and Oozie. There is no change in the way you make calls to Knox
whether you use Curl or Knox DSL.</p><h3><a id="High+Availability">High
Availability</a> <a href="#High+Availability"><img
src="markbook-section-link.png"/></a></h3><p>This describes how Knox itself can
be made highly available.</p><p>All Knox instances must be synced to use the
same topology credential keystores. These files are located under
<code>{GATEWAY_HOME}/conf/security/keys
tores/{TOPOLOGY_NAME}-credentials.jceks</code>. They are generated after the
first topology deployment.</p><p>In addition to these topology-specific
credentials, gateway credentials and topologies must also be kept in-sync for
Knox to operate in an HA manner.</p><h4><a
id="Manually+Synchronize+Knox+Instances">Manually Synchronize Knox
Instances</a> <a href="#Manually+Synchronize+Knox+Instances"><img
src="markbook-section-link.png"/></a></h4><p>Here are the steps to manually
sync topology credential keystores:</p>
+</code></pre><h4><a
id="Update+`krb5.conf`+at+`{GATEWAY_HOME}/conf/krb5.conf`+on+Knox+host">Update
<code>krb5.conf</code> at <code>{GATEWAY_HOME}/conf/krb5.conf</code> on Knox
host</a> <a
href="#Update+`krb5.conf`+at+`{GATEWAY_HOME}/conf/krb5.conf`+on+Knox+host"><img
src="markbook-section-link.png"/></a></h4><p>You could copy the
<code>{GATEWAY_HOME}/templates/krb5.conf</code> file provided in the Knox
binary download and customize it to suit your cluster.</p><h4><a
id="Update+`krb5JAASLogin.conf`+at+`/etc/knox/conf/krb5JAASLogin.conf`+on+Knox+host">Update
<code>krb5JAASLogin.conf</code> at
<code>/etc/knox/conf/krb5JAASLogin.conf</code> on Knox host</a> <a
href="#Update+`krb5JAASLogin.conf`+at+`/etc/knox/conf/krb5JAASLogin.conf`+on+Knox+host"><img
src="markbook-section-link.png"/></a></h4><p>You could copy the
<code>{GATEWAY_HOME}/templates/krb5JAASLogin.conf</code> file provided in the
Knox binary download and customize it to suit your cluster.</p><h4><a
id="Update+`gateway-site.xm
l`+on+Knox+host">Update <code>gateway-site.xml</code> on Knox host</a> <a
href="#Update+`gateway-site.xml`+on+Knox+host"><img
src="markbook-section-link.png"/></a></h4><p>Update
<code>conf/gateway-site.xml</code> in your Knox installation and set the value
of <code>gateway.hadoop.kerberos.secured</code> to true.</p><h4><a
id="Restart+Knox">Restart Knox</a> <a href="#Restart+Knox"><img
src="markbook-section-link.png"/></a></h4><p>After you do the above
configurations and restart Knox, Knox would use SPNego to authenticate with
Hadoop services and Oozie. There is no change in the way you make calls to Knox
whether you use Curl or Knox DSL.</p><h3><a id="High+Availability">High
Availability</a> <a href="#High+Availability"><img
src="markbook-section-link.png"/></a></h3><p>This describes how Knox itself can
be made highly available.</p><p>All Knox instances must be configured to use
the same topology credential keystores. These files are located under
<code>{GATEWAY_HOME}/conf/security/
keystores/{TOPOLOGY_NAME}-credentials.jceks</code>. They are generated after
the first topology deployment.</p><p>In addition to these topology-specific
credentials, gateway credentials and topologies must also be kept in-sync for
Knox to operate in an HA manner.</p><h4><a
id="Manually+Synchronize+Knox+Instances">Manually Synchronize Knox
Instances</a> <a href="#Manually+Synchronize+Knox+Instances"><img
src="markbook-section-link.png"/></a></h4><p>Here are the steps to manually
sync topology credential keystores:</p>
<ol>
<li>Choose a Knox instance that will be the source for topology credential
keystores. Let’s call it <em>keystores master</em></li>
<li>Replace the topology credential keystores in the other Knox instances
with topology credential keystores from the <em>keystores master</em></li>
<li>Restart Knox instances</li>
-</ol><p>Manually synchronizing the gateway credentials and topologies involves
using ssh/scp to copy the topology-related files to all the participating Knox
instances, and running the Knox CLI on each participating instance to define
the credential aliases.</p><p>This manual process can be tedious and
error-prone. As such, ZooKeeper-based HA is recommended to simplify the
management of these deployments.</p><h4><a
id="High+Availability+with+Apache+ZooKeeper">High Availability with Apache
ZooKeeper</a> <a href="#High+Availability+with+Apache+ZooKeeper"><img
src="markbook-section-link.png"/></a></h4><p>Rather than manually keeping Knox
HA instances in sync (in terms of credentials and topology), Knox can get
it’s state from Apache ZooKeeper. By configuring all the Knox instances
to monitor the same ZooKeeper ensemble, they can be kept in-sync by modifying
the topology-related configuration and/or credential aliases at only one of the
instances (using the Admin UI, Admin API, or
Knox CLI).</p><h5><a
id="What+is+Automatically+Synchronized+Across+Instances?">What is Automatically
Synchronized Across Instances?</a> <a
href="#What+is+Automatically+Synchronized+Across+Instances?"><img
src="markbook-section-link.png"/></a></h5>
+</ol><p>Manually synchronizing the gateway credentials and topologies involves
using ssh/scp to copy the topology-related files to all the participating Knox
instances, and running the Knox CLI on each participating instance to define
the gateway credential aliases.</p><p>This manual process can be tedious and
error-prone. As such, <a
href="High+Availability+with+Apache+ZooKeeper">ZooKeeper-based HA</a> is
recommended to simplify the management of these deployments.</p><h4><a
id="High+Availability+with+Apache+ZooKeeper">High Availability with Apache
ZooKeeper</a> <a href="#High+Availability+with+Apache+ZooKeeper"><img
src="markbook-section-link.png"/></a></h4><p>Rather than manually keeping Knox
HA instances in sync (in terms of credentials and topology), Knox can get
it’s state from Apache ZooKeeper. By configuring all the Knox instances
to monitor the same ZooKeeper ensemble, they can be kept in-sync by modifying
the topology-related configuration and/or credential aliases a
t only one of the instances (using the Admin UI, Admin API, or Knox
CLI).</p><h5><a id="What+is+Automatically+Synchronized+Across+Instances?">What
is Automatically Synchronized Across Instances?</a> <a
href="#What+is+Automatically+Synchronized+Across+Instances?"><img
src="markbook-section-link.png"/></a></h5>
<ul>
<li>Provider Configurations</li>
<li>Descriptors</li>
+ <li><em>Topologies</em> (generated only)</li>
<li>Credential Aliases</li>
</ul><p>When a provider configuration or descriptor is added or updated to the
ZooKeeper ensemble, all of the participating Knox instances will get the
change, and the affected topologies will be [re]generated and [re]deployed.
Similarly, if one of these is deleted, the affected topologies will be deleted
and undeployed.</p><p>When provider configurations and descriptors are added,
modified or removed using the Admin UI or API (when the Knox instance is
configured to monitor a ZooKeeper ensemble), then those changes will be
automatically reflected in the associated ZooKeeper ensemble. Those changes
will subsequently be consumed by all the other Knox instances monitoring that
ensemble. By using the Admin UI or API, ssh/scp access to the Knox hosts can be
avoided completely for the purpose of effecting topology
changes.</p><p>Similarly, when the Knox CLI is used to create or delete a
gateway alias (when the Knox instance is configured to monitor a ZooKeeper
ensemble), that alias chang
e is reflected in the ZooKeeper ensemble, and all other Knox instances
montoring that ensemble will apply the change.</p><h5><a
id="What+is+NOT+Automatically+Synchronized+Across+Instances?">What is NOT
Automatically Synchronized Across Instances?</a> <a
href="#What+is+NOT+Automatically+Synchronized+Across+Instances?"><img
src="markbook-section-link.png"/></a></h5>
<ul>
@@ -7166,7 +7167,7 @@ curl -i -k -u username:password -H "
<td><code>https://{gateway-host}:{gateway-port}/{gateway-path}/manager/admin-ui/</code>
</td>
</tr>
</tbody>
-</table><h5><a id="Authentication">Authentication</a> <a
href="#Authentication"><img src="markbook-section-link.png"/></a></h5><p>The
admin UI is deployed using the <strong>manager</strong> topology . The
out-of-box authentication mechanism is KNOXSSO, backed by the demo LDAP server.
Only someone in the <strong>admin</strong> role can access the UI
functionality.</p><h5><a id="Basic+Navigation">Basic Navigation</a> <a
href="#Basic+Navigation"><img
src="markbook-section-link.png"/></a></h5><p>Initially, the Admin UI presents
the types of resources which can be managed: <a
href="#Provider+Configurations"><strong>Provider Configurations</strong></a>,
<a href="#Descriptors"><strong>Descriptors</strong></a>, and <a
href="#Topologies"><strong>Topologies</strong></a>.</p><p><img
src="adminui/image1.png" style="width:6.5in;height:3.28403in"
/></p><p>Selecting a resource type yields a listing of the existing resources
of that type in the adjacent column, and selecting an individual resource
presents the details of that selected resource.</p><p>For the provider
configuration and descriptor resources types, the <img
src="adminui/plus-icon.png"
style="width:20px;height:20px;vertical-align:bottom"/> icon next to the
resource list header is the trigger for the respective facility for creating a
new resource of that type.<br> Modification options, including deletion, are
available from the detail view for an individual resource.</p><h5><a
id="Provider+Configurations">Provider Configurations</a> <a
href="#Provider+Configurations"><img
src="markbook-section-link.png"/></a></h5><p>The Admin UI lists the provider
configurations currently deployed to Knox.</p><p>By choosing a particular
provider configuration from the list, its details can be viewed and edited.<br>
The provider configuration can also be deleted (as long as there are no
referencing descriptors).</p><p>By default, there is a provider configuration
named <strong><em>default-providers</em></strong>.</p><p><img src="
adminui/image2.png" style="width:6.5in;height:3.76597in" /></p><h6><a
id="Editing+Provider+Configurations">Editing Provider Configurations</a> <a
href="#Editing+Provider+Configurations"><img
src="markbook-section-link.png"/></a></h6><p>For each provider in a given
provider configuration, the attributes can be modified:</p>
+</table><h5><a id="Authentication">Authentication</a> <a
href="#Authentication"><img src="markbook-section-link.png"/></a></h5><p>The
admin UI is deployed using the <strong>manager</strong> topology. The
out-of-box authentication mechanism is KNOXSSO, backed by the demo LDAP server.
Only someone in the <strong>admin</strong> role can access the UI
functionality.</p><h5><a id="Basic+Navigation">Basic Navigation</a> <a
href="#Basic+Navigation"><img
src="markbook-section-link.png"/></a></h5><p>Initially, the Admin UI presents
the types of resources which can be managed: <a
href="#Provider+Configurations"><strong>Provider Configurations</strong></a>,
<a href="#Descriptors"><strong>Descriptors</strong></a>, and <a
href="#Topologies"><strong>Topologies</strong></a>.</p><p><img
src="adminui/image1.png" style="width:6.5in;height:3.28403in"
/></p><p>Selecting a resource type yields a listing of the existing resources
of that type in the adjacent column, and selecting an individual resource
presents the details of that selected resource.</p><p>For the provider
configuration and descriptor resources types, the <img
src="adminui/plus-icon.png"
style="width:20px;height:20px;vertical-align:bottom"/> icon next to the
resource list header is the trigger for the respective facility for creating a
new resource of that type.<br> Modification options, including deletion, are
available from the detail view for an individual resource.</p><h5><a
id="Provider+Configurations">Provider Configurations</a> <a
href="#Provider+Configurations"><img
src="markbook-section-link.png"/></a></h5><p>The Admin UI lists the provider
configurations currently deployed to Knox.</p><p>By choosing a particular
provider configuration from the list, its details can be viewed and edited.<br>
The provider configuration can also be deleted (as long as there are no
referencing descriptors).</p><p>By default, there is a provider configuration
named <strong><em>default-providers</em></strong>.</p><p><img src="a
dminui/image2.png" style="width:6.5in;height:3.76597in" /></p><h6><a
id="Editing+Provider+Configurations">Editing Provider Configurations</a> <a
href="#Editing+Provider+Configurations"><img
src="markbook-section-link.png"/></a></h6><p>For each provider in a given
provider configuration, the attributes can be modified:</p>
<ul>
<li>The provider can be enabled/disabled</li>
<li>Parameters can be added (<img src="adminui/plus-icon.png"
style="width:20px;height:20px;vertical-align:bottom"/>) or removed (<img
src="adminui/x-icon.png" style="height:12px;vertical-align:middle"/>)</li>
Modified: knox/trunk/books/1.1.0/config_ha.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/1.1.0/config_ha.md?rev=1834754&r1=1834753&r2=1834754&view=diff
==============================================================================
--- knox/trunk/books/1.1.0/config_ha.md (original)
+++ knox/trunk/books/1.1.0/config_ha.md Sat Jun 30 17:05:31 2018
@@ -19,7 +19,7 @@
This describes how Knox itself can be made highly available.
-All Knox instances must be synced to use the same topology credential
keystores.
+All Knox instances must be configured to use the same topology credential
keystores.
These files are located under
`{GATEWAY_HOME}/conf/security/keystores/{TOPOLOGY_NAME}-credentials.jceks`.
They are generated after the first topology deployment.
@@ -33,9 +33,9 @@ Here are the steps to manually sync topo
2. Replace the topology credential keystores in the other Knox instances with
topology credential keystores from the _keystores master_
3. Restart Knox instances
-Manually synchronizing the gateway credentials and topologies involves using
ssh/scp to copy the topology-related files to all the participating Knox
instances, and running the Knox CLI on each participating instance to define
the credential aliases.
+Manually synchronizing the gateway credentials and topologies involves using
ssh/scp to copy the topology-related files to all the participating Knox
instances, and running the Knox CLI on each participating instance to define
the gateway credential aliases.
-This manual process can be tedious and error-prone. As such, ZooKeeper-based
HA is recommended to simplify the management of these deployments.
+This manual process can be tedious and error-prone. As such, [ZooKeeper-based
HA](High+Availability+with+Apache+ZooKeeper) is recommended to simplify the
management of these deployments.
#### High Availability with Apache ZooKeeper ####
@@ -47,6 +47,7 @@ configuration and/or credential aliases
* Provider Configurations
* Descriptors
+* *Topologies* (generated only)
* Credential Aliases
When a provider configuration or descriptor is added or updated to the
ZooKeeper ensemble, all of the participating Knox instances will get the
change, and the affected topologies will be [re]generated and [re]deployed.
Similarly, if one of these is deleted, the affected topologies will be deleted
and undeployed.
