You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@knox.apache.org by su...@apache.org on 2017/02/24 16:43:45 UTC
svn commit: r1784297 - in /knox: site/books/knox-0-12-0/dev-guide.html
trunk/books/0.12.0/dev-guide/admin-ui.md trunk/books/0.12.0/dev-guide/book.md
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>>