Author: more
Date: Mon Sep 10 15:55:40 2018
New Revision: 1840473
URL: http://svn.apache.org/viewvc?rev=1840473&view=rev
Log:
KNOX-1426 - Document overriding service dispatch in a topology
Modified:
knox/site/books/knox-1-1-0/dev-guide.html
knox/site/books/knox-1-1-0/user-guide.html
knox/site/index.html
knox/site/issue-tracking.html
knox/site/license.html
knox/site/mail-lists.html
knox/site/project-info.html
knox/site/team-list.html
knox/trunk/books/1.1.0/config.md
knox/trunk/books/1.1.0/dev-guide/book.md
Modified: knox/site/books/knox-1-1-0/dev-guide.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-1-0/dev-guide.html?rev=1840473&r1=1840472&r2=1840473&view=diff
==============================================================================
--- knox/site/books/knox-1-1-0/dev-guide.html (original)
+++ knox/site/books/knox-1-1-0/dev-guide.html Mon Sep 10 15:55:40 2018
@@ -565,10 +565,18 @@ rewrite.xml
<name>weather</name>
<version>0.1.0</version>
<url>http://api.openweathermap.org/data</url>
+ <dispatch>
+ <contributor-name>custom-client</contributor-name>
+ <ha-contributor-name>ha-client</ha-contributor-name>
+
<classname>org.apache.knox.gateway.dispatch.PassAllHeadersDispatch</classname>
+ <ha-classname></ha-classname>
+ <http-client-factory></http-client-factory>
+ <use-two-way-ssl>false</use-two-way-ssl>
+ </dispatch>
</service>
....
</topology>
-</code></pre><p>If only <em>role</em> is specified in the topology file (the
only required element other than <em>url</em>) then the first service
definition of that role found will be used with the highest version of that
role and name. Similarly if only the <em>version</em> is omitted from the
topology specification of the service, the service definition of the highest
version will be used. It is therefore important to specify a version for a
service if it is desired that a topology be locked down to a specific version
of a service.</p>
+</code></pre><p>If only <em>role</em> is specified in the topology file (the
only required element other than <em>url</em>) then the first service
definition of that role found will be used with the highest version of that
role and name. Similarly if only the <em>version</em> is omitted from the
topology specification of the service, the service definition of the highest
version will be used. It is therefore important to specify a version for a
service if it is desired that a topology be locked down to a specific version
of a service.</p><p>The optional <code>dispatch</code> element can be used to
override the dispatch specified in service.xml file for the service, this can
be useful in cases where you want a specific topology to override the dispatch,
which is useful for topology based federation from one Knox instance to
another. <code>dispatch\classname</code> is the most commonly used option, but
other options are available if one wants more fine grained control over
topology di
spatch override. </p>
<dl><dt><strong>routes</strong></dt><dd>Wrapper element for one or more
routes.</dd><dt><strong>route</strong></dt><dd>A route specifies the
<em>path</em> that the service is routing as well as any rewrite bindings or
policy bindings. Another child element that may be used here is a
<em>dispatch</em> element.</dd><dt><strong>rewrite</strong></dt><dd>A rewrite
rule or function that is to be applied to the path. A rewrite element contains
a <em>apply</em> attribute that references the rewrite function or rule by
name. Along with the <em>apply</em> attribute, a <em>to</em> attribute must be
used. The <em>to</em> specifies what part of the request or response to
rewrite. The valid values for the <em>to</em> attribute are:</dd>
</dl>
<ul>
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=1840473&r1=1840472&r2=1840473&view=diff
==============================================================================
--- knox/site/books/knox-1-1-0/user-guide.html (original)
+++ knox/site/books/knox-1-1-0/user-guide.html Mon Sep 10 15:55:40 2018
@@ -1066,7 +1066,7 @@ services:
{"name":"AMBARIUI",
"urls":["http://sandbox.hortonworks.com:8080"]}
]
}
-</code></pre><p>Both of these examples illustrate the specification of
credentials for the interaction with Ambari. If no credentials are specified,
then the default aliases are queried. Use of the default aliases is sufficient
for scenarios where topology discovery will only interact with a single Ambari
instance. For multiple Ambari instances however, it’s most likely that
each will require different sets of credentials. The discovery-user and
discovery-pwd-alias properties exist for this purpose. Note that whether using
the default credential aliases or specifying a custom password alias, these <a
href="#Alias+creation">aliases must be defined</a> prior to any attempt to
deploy a topology using a simplified descriptor.</p><h5><a
id="Deployment+Directories">Deployment Directories</a> <a
href="#Deployment+Directories"><img
src="markbook-section-link.png"/></a></h5><p>Effecting topology changes is as
simple as modifying files in two specific directories.</p><p>The <code>{GATEW
AY_HOME}/conf/shared-providers/</code> directory is the location where Knox
looks for provider configurations. This directory is monitored for changes,
such that modifying a provider configuration file therein will trigger updates
to any referencing simplified descriptors in the
<code>{GATEWAY_HOME}/conf/descriptors/</code> directory. <em>Care should be
taken when deleting these files if there are referencing descriptors; any
subsequent modifications of referencing descriptors will fail when the deleted
provider configuration cannot be found. The references should all be modified
before deleting the provider configuration.</em></p><p>Likewise, the
<code>{GATEWAY_HOME}/conf/descriptors/</code> directory is monitored for
changes, such that adding or modifying a simplified descriptor file in this
directory will trigger the generation and deployment of a topology descriptor.
Deleting a descriptor from this directory will conversely result in the removal
of the previously-generated topol
ogy descriptor, and the associated topology will be undeployed.</p><p>If the
service details for a deployed (generated) topology are changed in the cluster,
then the Knox topology can be updated by ’touch’ing the simplified
descriptor. This will trigger discovery and regeneration/redeployment of the
topology descriptor.</p><p>Note that deleting a generated topology descriptor
from <code>{GATEWAY_HOME}/conf/topologies/</code> is not sufficient for its
removal. If the source descriptor is modified, or Knox is restarted, the
topology descriptor will be regenerated and deployed. Removing generated
topology descriptors should be done by removing the associated simplified
descriptor. For the same reason, editing generated topology descriptors is
strongly discouraged since they can be inadvertently overwritten.</p><p>Another
means by which these topology changes can be effected is the <a
href="#Admin+API">Admin API</a>.</p><h5><a
id="Cluster+Configuration+Monitoring">Cluster Co
nfiguration Monitoring</a> <a href="#Cluster+Configuration+Monitoring"><img
src="markbook-section-link.png"/></a></h5><p>Another benefit gained through the
use of simplified topology descriptors, and the associated service discovery,
is the ability to monitor clusters for configuration changes. <strong>Like
service discovery, this is currently only available for clusters managed by
Ambari.</strong></p><p>The gateway can monitor Ambari cluster configurations,
and respond to changes by dynamically regenerating and redeploying the affected
topologies. The following properties in gateway-site.xml can be used to control
this behavior.</p>
+</code></pre><p>Both of these examples illustrate the specification of
credentials for the interaction with Ambari. If no credentials are specified,
then the default aliases are queried. Use of the default aliases is sufficient
for scenarios where topology discovery will only interact with a single Ambari
instance. For multiple Ambari instances however, it’s most likely that
each will require different sets of credentials. The discovery-user and
discovery-pwd-alias properties exist for this purpose. Note that whether using
the default credential aliases or specifying a custom password alias, these <a
href="#Alias+creation">aliases must be defined</a> prior to any attempt to
deploy a topology using a simplified descriptor.</p><h5><a
id="Deployment+Directories">Deployment Directories</a> <a
href="#Deployment+Directories"><img
src="markbook-section-link.png"/></a></h5><p>Effecting topology changes is as
simple as modifying files in two specific directories.</p><p>The <code>{GATEW
AY_HOME}/conf/shared-providers/</code> directory is the location where Knox
looks for provider configurations. This directory is monitored for changes,
such that modifying a provider configuration file therein will trigger updates
to any referencing simplified descriptors in the
<code>{GATEWAY_HOME}/conf/descriptors/</code> directory. <em>Care should be
taken when deleting these files if there are referencing descriptors; any
subsequent modifications of referencing descriptors will fail when the deleted
provider configuration cannot be found. The references should all be modified
before deleting the provider configuration.</em></p><p>Likewise, the
<code>{GATEWAY_HOME}/conf/descriptors/</code> directory is monitored for
changes, such that adding or modifying a simplified descriptor file in this
directory will trigger the generation and deployment of a topology descriptor.
Deleting a descriptor from this directory will conversely result in the removal
of the previously-generated topol
ogy descriptor, and the associated topology will be undeployed.</p><p>If the
service details for a deployed (generated) topology are changed in the cluster,
then the Knox topology can be updated by ’touch’ing the simplified
descriptor. This will trigger discovery and regeneration/redeployment of the
topology descriptor.</p><p>Note that deleting a generated topology descriptor
from <code>{GATEWAY_HOME}/conf/topologies/</code> is not sufficient for its
removal. If the source descriptor is modified, or Knox is restarted, the
topology descriptor will be regenerated and deployed. Removing generated
topology descriptors should be done by removing the associated simplified
descriptor. For the same reason, editing generated topology descriptors is
strongly discouraged since they can be inadvertently overwritten.</p><p>Another
means by which these topology changes can be effected is the <a
href="#Admin+API">Admin API</a>.</p><h5><a
id="Cloud+Federation+Configuration">Cloud Federa
tion Configuration</a> <a href="#Cloud+Federation+Configuration"><img
src="markbook-section-link.png"/></a></h5><p>Cloud Federation feature allows
for a topology based federation from one Knox instance to another (from on-prem
Knox instance to cloud knox instance).</p><h5><a
id="Cluster+Configuration+Monitoring">Cluster Configuration Monitoring</a> <a
href="#Cluster+Configuration+Monitoring"><img
src="markbook-section-link.png"/></a></h5><p>Another benefit gained through the
use of simplified topology descriptors, and the associated service discovery,
is the ability to monitor clusters for configuration changes. <strong>Like
service discovery, this is currently only available for clusters managed by
Ambari.</strong></p><p>The gateway can monitor Ambari cluster configurations,
and respond to changes by dynamically regenerating and redeploying the affected
topologies. The following properties in gateway-site.xml can be used to control
this behavior.</p>
<pre><code><property>
<name>gateway.cluster.config.monitor.ambari.enabled</name>
<value>false</value>
Modified: knox/site/index.html
URL:
http://svn.apache.org/viewvc/knox/site/index.html?rev=1840473&r1=1840472&r2=1840473&view=diff
==============================================================================
--- knox/site/index.html (original)
+++ knox/site/index.html Mon Sep 10 15:55:40 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2018-08-08
+ | Generated by Apache Maven Doxia at 2018-09-10
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180808" />
+ <meta name="Date-Revision-yyyymmdd" content="20180910" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Announcing Apache Knox 1.1.0!</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published:
2018-08-08</li>
+ <li id="publishDate" class="pull-right">Last Published:
2018-09-10</li>
</ul>
</div>
Modified: knox/site/issue-tracking.html
URL:
http://svn.apache.org/viewvc/knox/site/issue-tracking.html?rev=1840473&r1=1840472&r2=1840473&view=diff
==============================================================================
--- knox/site/issue-tracking.html (original)
+++ knox/site/issue-tracking.html Mon Sep 10 15:55:40 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2018-08-08
+ | Generated by Apache Maven Doxia at 2018-09-10
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180808" />
+ <meta name="Date-Revision-yyyymmdd" content="20180910" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Issue Tracking</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published:
2018-08-08</li>
+ <li id="publishDate" class="pull-right">Last Published:
2018-09-10</li>
</ul>
</div>
Modified: knox/site/license.html
URL:
http://svn.apache.org/viewvc/knox/site/license.html?rev=1840473&r1=1840472&r2=1840473&view=diff
==============================================================================
--- knox/site/license.html (original)
+++ knox/site/license.html Mon Sep 10 15:55:40 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2018-08-08
+ | Generated by Apache Maven Doxia at 2018-09-10
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180808" />
+ <meta name="Date-Revision-yyyymmdd" content="20180910" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project License</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published:
2018-08-08</li>
+ <li id="publishDate" class="pull-right">Last Published:
2018-09-10</li>
</ul>
</div>
Modified: knox/site/mail-lists.html
URL:
http://svn.apache.org/viewvc/knox/site/mail-lists.html?rev=1840473&r1=1840472&r2=1840473&view=diff
==============================================================================
--- knox/site/mail-lists.html (original)
+++ knox/site/mail-lists.html Mon Sep 10 15:55:40 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2018-08-08
+ | Generated by Apache Maven Doxia at 2018-09-10
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180808" />
+ <meta name="Date-Revision-yyyymmdd" content="20180910" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Mailing Lists</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published:
2018-08-08</li>
+ <li id="publishDate" class="pull-right">Last Published:
2018-09-10</li>
</ul>
</div>
Modified: knox/site/project-info.html
URL:
http://svn.apache.org/viewvc/knox/site/project-info.html?rev=1840473&r1=1840472&r2=1840473&view=diff
==============================================================================
--- knox/site/project-info.html (original)
+++ knox/site/project-info.html Mon Sep 10 15:55:40 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2018-08-08
+ | Generated by Apache Maven Doxia at 2018-09-10
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180808" />
+ <meta name="Date-Revision-yyyymmdd" content="20180910" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Information</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published:
2018-08-08</li>
+ <li id="publishDate" class="pull-right">Last Published:
2018-09-10</li>
</ul>
</div>
Modified: knox/site/team-list.html
URL:
http://svn.apache.org/viewvc/knox/site/team-list.html?rev=1840473&r1=1840472&r2=1840473&view=diff
==============================================================================
--- knox/site/team-list.html (original)
+++ knox/site/team-list.html Mon Sep 10 15:55:40 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2018-08-08
+ | Generated by Apache Maven Doxia at 2018-09-10
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180808" />
+ <meta name="Date-Revision-yyyymmdd" content="20180910" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Team list</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published:
2018-08-08</li>
+ <li id="publishDate" class="pull-right">Last Published:
2018-09-10</li>
</ul>
</div>
Modified: knox/trunk/books/1.1.0/config.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/1.1.0/config.md?rev=1840473&r1=1840472&r2=1840473&view=diff
==============================================================================
--- knox/trunk/books/1.1.0/config.md (original)
+++ knox/trunk/books/1.1.0/config.md Mon Sep 10 15:55:40 2018
@@ -620,6 +620,9 @@ For the same reason, editing generated t
Another means by which these topology changes can be effected is the [Admin
API](#Admin+API).
+##### Cloud Federation Configuration #####
+
+Cloud Federation feature allows for a topology based federation from one Knox
instance to another (from on-prem Knox instance to cloud knox instance).
##### Cluster Configuration Monitoring #####
Modified: knox/trunk/books/1.1.0/dev-guide/book.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/1.1.0/dev-guide/book.md?rev=1840473&r1=1840472&r2=1840473&view=diff
==============================================================================
--- knox/trunk/books/1.1.0/dev-guide/book.md (original)
+++ knox/trunk/books/1.1.0/dev-guide/book.md Mon Sep 10 15:55:40 2018
@@ -856,6 +856,14 @@ service definition from others. To ensur
<name>weather</name>
<version>0.1.0</version>
<url>http://api.openweathermap.org/data</url>
+ <dispatch>
+ <contributor-name>custom-client</contributor-name>
+ <ha-contributor-name>ha-client</ha-contributor-name>
+
<classname>org.apache.knox.gateway.dispatch.PassAllHeadersDispatch</classname>
+ <ha-classname></ha-classname>
+ <http-client-factory></http-client-factory>
+ <use-two-way-ssl>false</use-two-way-ssl>
+ </dispatch>
</service>
....
</topology>
@@ -866,6 +874,8 @@ will be used with the highest version of
the service definition of the highest version will be used. It is therefore
important to specify a version for a service if it is desired that
a topology be locked down to a specific version of a service.
+The optional `dispatch` element can be used to override the dispatch specified
in service.xml file for the service, this can be useful in cases where you want
a specific topology to override the dispatch, which is useful for topology
based federation from one Knox instance to another. `dispatch\classname` is the
most commonly used option, but other options are available if one wants more
fine grained control over topology dispatch override.
+
**routes**
: Wrapper element for one or more routes.
