Author: sumit
Date: Fri Feb 24 16:43:45 2017
New Revision: 1784297
URL: http://svn.apache.org/viewvc?rev=1784297&view=rev
Log:
KNOX-839 admin ui dev guide docs
Added:
knox/trunk/books/0.12.0/dev-guide/admin-ui.md
Modified:
knox/site/books/knox-0-12-0/dev-guide.html
knox/trunk/books/0.12.0/dev-guide/book.md
Modified: knox/site/books/knox-0-12-0/dev-guide.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/dev-guide.html?rev=1784297&r1=1784296&r2=1784297&view=diff
==============================================================================
--- knox/site/books/knox-0-12-0/dev-guide.html (original)
+++ knox/site/books/knox-0-12-0/dev-guide.html Fri Feb 24 16:43:45 2017
@@ -31,6 +31,7 @@
<li><a href="#Auditing">Auditing</a></li>
<li><a href="#Logging">Logging</a></li>
<li><a href="#Internationalization">Internationalization</a></li>
+ <li><a href="#Admin+UI">Admin UI</a></li>
</ul><h2><a id="Overview">Overview</a> <a href="#Overview"><img
src="markbook-section-link.png"/></a></h2><p>Apache Knox gateway is a
specialized reverse proxy gateway for various Hadoop REST APIs. However, the
gateway is built entirely upon a fairly generic framework. This framework is
used to “plug-in” all of the behavior that makes it specific to
Hadoop in general and any particular Hadoop REST API. It would be equally as
possible to create a customized reverse proxy for other non-Hadoop HTTP
endpoints. This approach is taken to ensure that the Apache Knox gateway can
scale with the rapidly evolving Hadoop ecosystem.</p><p>Throughout this guide
we will be using a publicly available REST API to demonstrate the development
of various extension mechanisms. <a
href="http://openweathermap.org/";>http://openweathermap.org/</a></p><h3><a
id="Architecture+Overview">Architecture Overview</a> <a
href="#Architecture+Overview"><img
src="markbook-section-link.png"/></a></h3><p>The
gateway itself is a layer over an embedded Jetty JEE server. At the very
highest level the gateway processes requests by using request URLs to lookup
specific JEE Servlet Filter chain that is used to process the request. The
gateway framework provides extensible mechanisms to assemble chains of custom
filters that support secured access to services.</p><p>The gateway has two
primary extensibility mechanisms: Service and Provider. The Service
extensibility framework provides a way to add support for new HTTP/REST
endpoints. For example, the support for WebHdfs is plugged into the Knox
gateway as a Service. The Provider extensibility framework allows adding new
features to the gateway that can be used across Services. An example of a
Provider is an authentication provider. Providers can also expose APIs that
other service and provider extensions can utilize.</p><p>Service and Provider
integrations interact with the gateway framework in two distinct phases:
Deployment and Runtime. The
gateway framework can be thought of as a layer over the JEE Servlet framework.
Specifically all runtime processing within the gateway is performed by JEE
Servlet Filters. The two phases interact with this JEE Servlet Filter based
model in very different ways. The first phase, Deployment, is responsible for
converting fairly simple to understand configuration called topology into JEE
WebArchive (WAR) based implementation details. The second phase, Runtime, is
the processing of requests via a set of Filters configured in the
WAR.</p><p>From an “ethos” perspective, Service and Provider
extensions should attempt to incur complexity associated with configuration in
the deployment phase. This should allow for very streamlined request processing
that is very high performance and easily testable. The preference at runtime,
in OO style, is for small classes that perform a specific function. The ideal
set of implementation classes are then assembled by the Service and Provider plu
gins during deployment.</p><p>A second critical design consideration is
streaming. The processing infrastructure is build around JEE Servlet Filters as
they provide a natural streaming interception model. All Provider
implementations should make every attempt to maintaining this streaming
characteristic.</p><h3><a id="Project+Overview">Project Overview</a> <a
href="#Project+Overview"><img src="markbook-section-link.png"/></a></h3><p>The
table below describes the purpose of the current modules in the project. Of
particular importance are the root pom.xml and the gateway-release module. The
root pom.xml is critical because this is where all dependency version must be
declared. There should be no dependency version information in module pom.xml
files. The gateway-release module is critical because the dependencies declared
there essentially define the classpath of the released gateway server. This is
also true of the other -release modules in the project.</p>
<table>
<thead>
@@ -1569,6 +1570,21 @@ public interface CustomResources {
}
}
+</code></pre><h2><a id="Admin+UI">Admin UI</a> <a href="#Admin+UI"><img
src="markbook-section-link.png"/></a></h2><h3><a
id="Introduction">Introduction</a> <a href="#Introduction"><img
src="markbook-section-link.png"/></a></h3><p>The Admin UI is a work in
progress. It has started with viewpoint of being a simple web interface for
Admin API functions but will hopefully grow into being able to also provide
visibility into the gateway in terms of logs and metrics.</p><h3><a
id="Source+and+Binaries">Source and Binaries</a> <a
href="#Source+and+Binaries"><img
src="markbook-section-link.png"/></a></h3><p>The Admin UI application follows
the architecture of a hosted application in Knox. To that end it needs to be
packaged up in the gateway-applications module in the source tree so that in
the installation it can wind up
here</p><p><code><GATEWAY_HOME>/data/applications/admin-ui</code></p><p>However
since the application is built using angular and various node modules the
source tre
e is not something we want to place into the gateway-applications module.
Instead we will place the production ‘binaries’ in
gateway-applications and have the source in a module called
‘gateway-admin-ui’.</p><p>To work with the angular application you
need to install some prerequisite tools. </p><p>The main tool needed is the <a
href="https://github.com/angular/angular-cli#installation";>angular cli</a> and
while installing that you will get its dependencies which should fulfill any
other requirements <a
href="https://github.com/angular/angular-cli#prerequisites";>Prerequisites</a></p><p>Also
be aware that there is a package.json file in the module, so to get all
dependencies in the module simply type </p><p><code>npm install</code></p><p>At
the time of writing this the gateway-admin-ui module is not part of the maven
build.</p><p>Any changes in the module must be promoted to the
gateway-application modules. The following ant commands can be used to make this
easy.</p><p><code>ant build-admin-ui</code></p><p>This uses the ng cli to
build the source.</p><p><code>ant promote-admin-ui</code></p><p>This copies
over the minified files for the application to the gateway-applications
module.</p><h3><a id="Manager+Topology">Manager Topology</a> <a
href="#Manager+Topology"><img src="markbook-section-link.png"/></a></h3><p>The
Admin UI is deployed to a fixed topology. The topology file can be found
under</p><p><code><GATEWAY_HOME>/conf/topologies/manager.xml</code></p><p>The
topology hosts an instance of the Admin API for the UI to use. The reason for
this is that the existing Admin API needs to have a different security model
from that used by the Admin UI. The key components of this topology are:</p>
+<pre><code class="xml"> <provider>
+ <role>webappsec</role>
+ <name>WebAppSec</name>
+ <enabled>true</enabled>
+
<param><name>csrf.enabled</name><value>true</value></param>
+
<param><name>csrf.customHeader</name><value>X-XSRF-Header</value></param>
+
<param><name>csrf.methodsToIgnore</name><value>GET,OPTIONS,HEAD</value></param>
+
<param><name>xframe-options.enabled</name><value>true</value></param>
+ </provider>
+
+</code></pre><p>and </p>
+<pre><code class="xml"> <application>
+ <role>admin-ui</role>
+ </application>
</code></pre><h2><a id="Trademarks">Trademarks</a> <a href="#Trademarks"><img
src="markbook-section-link.png"/></a></h2><p>Apache Knox, Apache Knox Gateway,
Apache, the Apache feather logo and the Apache Knox Gateway project logos are
trademarks of The Apache Software Foundation. All other marks mentioned may be
trademarks or registered trademarks of their respective owners.</p><h2><a
id="License">License</a> <a href="#License"><img
src="markbook-section-link.png"/></a></h2><p>Apache Knox uses the standard <a
href="http://www.apache.org/licenses/LICENSE-2.0";>Apache license</a>.</p><h2><a
id="Privacy+Policy">Privacy Policy</a> <a href="#Privacy+Policy"><img
src="markbook-section-link.png"/></a></h2><p>Apache Knox uses the standard
Apache privacy policy.</p><p>Information about your use of this website is
collected using server access logs and a tracking cookie. The collected
information consists of the following:</p>
<ul>
<li>The IP address from which you access the website;</li>
Added: knox/trunk/books/0.12.0/dev-guide/admin-ui.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/dev-guide/admin-ui.md?rev=1784297&view=auto
==============================================================================
--- knox/trunk/books/0.12.0/dev-guide/admin-ui.md (added)
+++ knox/trunk/books/0.12.0/dev-guide/admin-ui.md Fri Feb 24 16:43:45 2017
@@ -0,0 +1,70 @@
+###Introduction
+
+The Admin UI is a work in progress. It has started with viewpoint of being a
simple web interface for
+ Admin API functions but will hopefully grow into being able to also provide
visibility into the gateway
+ in terms of logs and metrics.
+
+###Source and Binaries
+
+The Admin UI application follows the architecture of a hosted application in
Knox. To that end it needs to be
+packaged up in the gateway-applications module in the source tree so that in
the installation it can wind up here
+
+`<GATEWAY_HOME>/data/applications/admin-ui`
+
+However since the application is built using angular and various node modules
the source tree is not something
+we want to place into the gateway-applications module. Instead we will place
the production 'binaries' in gateway-applications
+ and have the source in a module called 'gateway-admin-ui'.
+
+To work with the angular application you need to install some prerequisite
tools.
+
+The main tool needed is the [angular
cli](https://github.com/angular/angular-cli#installation) and while installing
that you
+ will get its dependencies which should fulfill any other requirements
[Prerequisites](https://github.com/angular/angular-cli#prerequisites)
+
+ Also be aware that there is a package.json file in the module, so to get all
dependencies in the module simply type
+
+ `npm install`
+
+At the time of writing this the gateway-admin-ui module is not part of the
maven build.
+
+Any changes in the module must be promoted to the gateway-application modules.
The following ant commands can be used to
+make this easy.
+
+`ant build-admin-ui`
+
+This uses the ng cli to build the source.
+
+`ant promote-admin-ui`
+
+This copies over the minified files for the application to the
gateway-applications module.
+
+
+
+###Manager Topology
+
+The Admin UI is deployed to a fixed topology. The topology file can be found
under
+
+`<GATEWAY_HOME>/conf/topologies/manager.xml`
+
+The topology hosts an instance of the Admin API for the UI to use. The reason
for this is that the existing Admin API needs
+ to have a different security model from that used by the Admin UI. The key
components of this topology are:
+
+```xml
+ <provider>
+ <role>webappsec</role>
+ <name>WebAppSec</name>
+ <enabled>true</enabled>
+ <param><name>csrf.enabled</name><value>true</value></param>
+
<param><name>csrf.customHeader</name><value>X-XSRF-Header</value></param>
+
<param><name>csrf.methodsToIgnore</name><value>GET,OPTIONS,HEAD</value></param>
+
<param><name>xframe-options.enabled</name><value>true</value></param>
+ </provider>
+
+```
+
+ and
+
+```xml
+ <application>
+ <role>admin-ui</role>
+ </application>
+```
\ No newline at end of file
Modified: knox/trunk/books/0.12.0/dev-guide/book.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/dev-guide/book.md?rev=1784297&r1=1784296&r2=1784297&view=diff
==============================================================================
--- knox/trunk/books/0.12.0/dev-guide/book.md (original)
+++ knox/trunk/books/0.12.0/dev-guide/book.md Fri Feb 24 16:43:45 2017
@@ -39,6 +39,7 @@
* #[Auditing]
* #[Logging]
* #[Internationalization]
+* #[Admin UI]
## Overview ##
@@ -1551,6 +1552,10 @@ public class CustomResourceSample {
}
```
+## Admin UI ##
+
+<<admin-ui.md>>
+
<<../../common/footer.md>>
