Add architecture picture to RST 97/2997/2
authorLott, Christopher (cl778h) <cl778h@att.com>
Tue, 2 Oct 2018 19:18:26 +0000 (15:18 -0400)
committerLott, Christopher (cl778h) <cl778h@att.com>
Tue, 2 Oct 2018 20:39:19 +0000 (16:39 -0400)
Change-Id: I11b28c1fce7ce941aadd11916611cd5b64bc25e9
Signed-off-by: Lott, Christopher (cl778h) <cl778h@att.com>
docs/design-notes.rst [deleted file]
docs/design.rst [new file with mode: 0644]
docs/developer-guide.rst [moved from docs/federated-gateway.rst with 50% similarity]
docs/fed-gw-arch.png [new file with mode: 0644]
docs/index.rst
docs/overview.rst [new file with mode: 0644]
docs/release-notes.rst

diff --git a/docs/design-notes.rst b/docs/design-notes.rst
deleted file mode 100644 (file)
index a0a657b..0000000
+++ /dev/null
@@ -1,96 +0,0 @@
-.. ===============LICENSE_START=======================================================
-.. Acumos CC-BY-4.0
-.. ===================================================================================
-.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
-.. ===================================================================================
-.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
-.. under the Creative Commons Attribution 4.0 International License (the "License");
-.. you may not use this file except in compliance with the License.
-.. You may obtain a copy of the License at
-..
-.. http://creativecommons.org/licenses/by/4.0
-..
-.. This file is distributed on an "AS IS" BASIS,
-.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-.. See the License for the specific language governing permissions and
-.. limitations under the License.
-.. ===============LICENSE_END=========================================================
-
-==============================
-Federated Gateway Design Notes
-==============================
-
-The federation gateway is an optional component of an Acumos system whose role
-is to facilitate communication with other Acumos systems (i.e. with their gateways)
-or compatible systems (through adapters). Its role is to facilitate the exchange
-of models and their related information between Acumos instances.
-The federation gateway occupies the borderline of an Acumos system, from a logical
-and deployment perspective. From a logical perspective it is the point of control
-for the flow of model information in and out of an Acumos instance. From a deployment
-perspective (within an enterprise environment), the federation gateway will be deployed
-at the edge of the network (DMZ) with communication interfaces towards the enterprise
-network (where the rest of the Acumos instance components are deployed) and towards
-the outside world (where other Acumos instances are deployed).
-We call the external interface (towards the gateways of other Acumos instances) the
-*federation interface* and we call the internal interface (towards the other components
-of the same Acumos instance) the *local interface*.
-The design of the gateway reflects this duality: the gateway defines/offers a set of
-REST APIs on its federation interface for gateway-2-gateway (or gateway-2-adapter)
-communication and another set on the local interface for component-2-gateway communication.
-
-Federation concepts
-
-The federation gateway behaviour is driven by the peer and subscription information provisioned
-in the CDS. Through the local interface API other components can trigger gateway
-behaviour, i.e. trigger interactions with peers. 
-The peer information represents all other Acumos systems (or other through adapters) this system
-has agreed to communicate/exchange information with. The 'handshake' procedure by which 2 systems
-agreed to communicate and provision the required information can take place 'out-of-band' (email,etc
-+ provisining) or 'in-band' (a combination of federation REST API and provisioning actions).
-
-When enabling federation an Acumos system agrees to share its public, validated models (their
-revisions) with its peers. (a discussion on ACL driven/selective sharing control will come here later).
-Establishing a relationship does not in itself imply that any exchange of information takes place.
-Information exchange (models) is driven by subscriptions provisioned in the local CDS. In Acumos every
-peer is responsible for pulling from its peers the models it is interested in (such an interaction
-.goes through the peers' federation gateway who controls/filters access to its local models).
-A subscription towards a peer represents a subset of that peers' model set that this Acumos is interested in.
-The subscription information is there to drive the behaviour of the federation gateway (who does
-the actual peer polling and local provisining of the retrieved information); there is no subscription
-information shared between peers. An Acumos instance can have multiple subscriptions towards another
-peer. A subscription can range from one specific model to all the models a peer exposes (with any
-combination of model level selection criteria in between). A subscription further specifies
-options such as the frequency with each the federation gateway should check for updates, how much
-model information should be retrieved every time,etc.
-
-It is important to notice that the federation gateway mechanisms for model information exchange
-does not impose an overall peer organization/deployment architecture: tree like structures, fully or sparse
-connected graphs, etc are all possible.
-
-
-
-Federation mechanisms
-
-Before any interaction with a peer can take place the peer information needs to be provisoned
-in the local CDS. A federation gateway has a dual role, as a server when responding to requests
-from its peers and as a client when requesting information from them. The federation gateway
-uses mutual authentication (https,tls), i.e. when a connection is established between 2 gateways
-both sides need to present their certificates (signed by accepred CAs and so on). The subjectName
-entry in a certificate received from a peer serves to identify the peer against the locally (CDS)
-provisioned peer collection (the are no passwords or other credentials provisioned/exchanged).
-
-The gateway periodically processes the list of locally provisioned peers; where subscriptions
-towards a peer are found they are assigned to tasks who will query the peer with the given
-subscription selector. Each resulting model will be compared against locally available
-model information (in CDS) and new model/new revisions+artifacts will be fetched and provisioned.
-
-In addition to the model information exchange APIs the federation gateway offers APIs for:
-
-- status information (ping)
-- in-band registration
-- peer information sharing
-
-Other
-
-At this point the federation gateway relies on only one Acumos component, the CDS.
diff --git a/docs/design.rst b/docs/design.rst
new file mode 100644 (file)
index 0000000..ea26924
--- /dev/null
@@ -0,0 +1,153 @@
+.. ===============LICENSE_START=======================================================
+.. Acumos CC-BY-4.0
+.. ===================================================================================
+.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
+.. ===================================================================================
+.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
+.. under the Creative Commons Attribution 4.0 International License (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+===============================
+Federation Gateway Design Notes
+===============================
+
+The federation gateway is an optional component of an Acumos system whose role
+is to facilitate communication with other Acumos systems (i.e. with their gateways)
+or compatible systems (through adapters). Its role is to facilitate the exchange
+of models and their related information between Acumos instances.
+The federation gateway occupies the borderline of an Acumos system, from a logical
+and deployment perspective. From a logical perspective it is the point of control
+for the flow of model information in and out of an Acumos instance. From a deployment
+perspective (within an enterprise environment), the federation gateway will be deployed
+at the edge of the network (DMZ) with communication interfaces towards the enterprise
+network (where the rest of the Acumos instance components are deployed) and towards
+the outside world (where other Acumos instances are deployed).
+
+We call the external interface (towards the gateways of other Acumos instances) the
+*federation interface* (or public interface) and we call the internal interface (towards
+the other components of the same Acumos instance) the *local interface* (or private interface).
+The design of the gateway reflects this duality: the gateway defines/offers a set of
+REST APIs on its federation interface for gateway-to-gateway (or gateway-to-adapter)
+communication and another set on the local interface for component-to-gateway communication.
+
+
+The public "E5" interface
+-------------------------
+
+The federation (public) interface is also known in the Acumos project as the E5 interface.
+This is a public, REST-based API specification: any system that decides to federate needs to implement it.
+This interface assumes a pull-based mechanism. 
+As such, only the ‘server’ side is defined by E5.
+
+The client side is based on a set of subscriptions, where each subscription defines a set of solutions
+the client is interested in  (through a selector), and employs periodic polling to detect new material.
+This interface defines no shared state, nothing to synchronize; all responsibility resides with the interested party.
+Requires a pre-provisioned peer on the server side, and uses both client and server authentication (CA based),
+principal to certificate matching.
+
+
+The private interface
+---------------------
+
+The private (local) interface is system specific, because a localized mapping of information must be done.
+In Acumos, this includes interactions with the Common Data Service and Portal components and represents
+is a one-to-one mapping of solution information and related artifacts.
+In ONAP, this interacts with the SDC component based on its REST API and
+requires additional processing, for example transforming an Acumos artifact into a set of SDC Asset Artifacts.
+
+
+Federation concepts
+-------------------
+
+Peer
+~~~~
+
+A federation peer is another system supporting the E5 interface; i.e., another Acumos gateway or an adapter for another system.
+Peer information is provisioned in CDS.
+
+Handshake
+~~~~~~~~~
+
+Establishment of a peer relationship (known as a handshake) is done by out-of-band information exchange
+to obtain and share certificates.  Site administrators with adequate permissions exchange required information: 
+the E5 REST endpoint coordinates and the expected principal info.  They then proceed with local peer provisioning
+through the Acumos Portal federation administration page.
+
+Subscriptions
+~~~~~~~~~~~~~
+
+A federation subscription defines which models an Acumos system is interested in importing from a peer.
+The subscription is primarily a selector over a peer’s catalog, and can support different scopes,
+ranging from pinpointing one particular solution to all available solutions.
+Subscriptions are subject to policies in the peer regarding which models are exposed to whom.
+Current options on a subscription include the refresh period, 
+and full (copy everything) vs. by reference (no artifact content is transferred).
+
+Federating models
+~~~~~~~~~~~~~~~~~
+
+The federation gateway behavior is driven by the peer and subscription information provisioned
+in the CDS. Through the local interface API other components can trigger gateway
+behavior, i.e. trigger interactions with peers. 
+The peer information represents all other Acumos systems (or other through adapters) this system
+has agreed to communicate/exchange information with. The 'handshake' procedure by which two systems
+agree to communicate and provision the required information can take place 'out-of-band' (email etc.
+plus provisioning) or 'in-band' (a combination of federation REST API and provisioning actions).
+
+When enabling federation an Acumos system agrees to share its public, validated models (their
+revisions) with its peers.
+(A discussion on ACL driven/selective sharing control will come here later.)
+Establishing a relationship does not in itself imply that any exchange of information takes place.
+Information exchange of (models is driven by subscriptions provisioned in the local CDS.
+In Acumos every peer is responsible for pulling from its peers the models it is interested in
+(such an interaction goes through the peer's federation gateway which controls/filters access to its local models).
+A subscription towards a peer represents a subset of that peer's model set that this Acumos is interested in.
+The subscription information is there to drive the behavior of the federation gateway (which does
+the actual peer polling and local provisioning of the retrieved information); no subscription
+information is shared between peers. An Acumos instance can have multiple subscriptions towards another
+peer. A subscription can range from one specific model to all the models a peer exposes (with any
+combination of model level selection criteria in between). A subscription further specifies
+options such as the frequency with each the federation gateway should check for updates, how much
+model information should be retrieved every time,etc.
+
+It is important to notice that the federation gateway mechanisms for model information exchange
+does not impose an overall peer organization/deployment architecture: tree like structures, fully or sparse
+connected graphs, etc are all possible.
+
+
+Federation mechanisms
+---------------------
+
+Before any interaction with a peer can take place the peer information needs to be provisioned
+in the local CDS. A federation gateway has a dual role, as a server when responding to requests
+from its peers and as a client when requesting information from them. The federation gateway
+uses mutual authentication (https, tls), i.e. when a connection is established between two gateways
+both sides need to present their certificates (signed by accepted CAs and so on). The subjectName
+entry in a certificate received from a peer serves to identify the peer against the locally (CDS)
+provisioned peer collection (the are no passwords or other credentials provisioned/exchanged).
+
+The gateway periodically processes the list of locally provisioned peers; where subscriptions
+towards a peer are found they are assigned to tasks who will query the peer with the given
+subscription selector. Each resulting model will be compared against locally available
+model information (in CDS) and new model/new revisions+artifacts will be fetched and provisioned.
+
+In addition to the model information exchange APIs the federation gateway offers APIs for:
+
+- status information (ping)
+- in-band registration
+- peer information sharing
+
+
+Dependencies
+------------
+
+At this point the federation gateway relies on only one Acumos component, the Common Data Service.
similarity index 50%
rename from docs/federated-gateway.rst
rename to docs/developer-guide.rst
index d05e6a0..0122859 100644 (file)
@@ -16,9 +16,9 @@
 .. limitations under the License.
 .. ===============LICENSE_END=========================================================
 
-=================================
-Federated Gateway Developer Guide
-=================================
+==================================
+Federation Gateway Developer Guide
+==================================
 
 Building and Packaging
 ----------------------
@@ -31,6 +31,8 @@ The build machine needs the following:
 1. Java version 1.8
 2. Maven version 3
 3. Connectivity to Maven Central (for most jars)
+4. Connectivity to Linux Foundation Nexus (for CDS jar)
+
 
 Use below maven command to build and package the gateway service into a single jar::
 
@@ -39,54 +41,76 @@ Use below maven command to build and package the gateway service into a single j
 Development and Local Testing
 -----------------------------
 
-This section provides information for developing and testing the federaton gateway locally. We will run two instances of the gateway to depict 2 instance of acumos federated to each other.
+This section provides information for developing and testing the federaton gateway locally.
+We will run two instances of the gateway to depict two instance of Acumos federated to each other.
 In below scenario, we are going to run Acumos A and Acumos B for testing locally.
 
 Launching
 ~~~~~~~~~
 
-Start the microservice for development and testing like this::
+Start two microservice instances for development and testing like this::
+
+    java -Djavax.net.ssl.trustStore=src/test/resources/acumosTrustStore.jks \
+         -Djavax.net.ssl.trustStorePassword=acumos \
+         -jar target/federated-gateway-1.0.0-SNAPSHOT.jar \
+         --spring.profiles.active="default,acumosa" 
 
-       java -Djavax.net.ssl.trustStore=src/test/resources/acumosTrustStore.jks -Djavax.net.ssl.trustStorePassword=acumos -jar target/federated-gateway-1.0.0-SNAPSHOT.jar --spring.profiles.active="default,acumosa" 
+    java -Djavax.net.ssl.trustStore=src/test/resources/acumosTrustStore.jks \
+         -Djavax.net.ssl.trustStorePassword=acumos \
+         -jar target/federated-gateway-1.0.0-SNAPSHOT.jar \
+         --spring.profiles.active="default,acumosb"
 
-       java -Djavax.net.ssl.trustStore=src/test/resources/acumosTrustStore.jks -Djavax.net.ssl.trustStorePassword=acumos -jar target/federated-gateway-1.0.0-SNAPSHOT.jar --spring.profiles.active="default,acumosb"
 
-REST interface
+REST Interface
 --------------
 
-The federation interface allows access via the federation gateway to informationavailable in an Acumos system. The main category of information that is exposed via the gateway is solution information: solution/revision/artifact and artifact content.
-The federation gateway allows access from pre-registered peers via a REST interface running over HTTPS/SSL/TLS. The gateway requires mutual authentication, i.e. the client will be required to present a certificate. The gateway identifies a client as a pre-registered peer based on the certificates' subjectName (which implies that the subjectName must be communicated to the Acumos system administrator when the peer is provisioned).
+The federation interface allows access via the federation gateway to information available in an Acumos system.
+The main category of information that is exposed via the gateway is solution information: solution/revision/artifact and artifact content.
+The federation gateway allows access from pre-registered peers via a REST interface running over HTTPS/SSL/TLS.
+The gateway requires mutual authentication; i.e., the client will be required to present a certificate.
+The gateway identifies a client as a pre-registered peer based on the certificates' subjectName
+(which implies that the subjectName must be communicated to the Acumos system administrator when the peer is provisioned).
 
 API
 ~~~
 
-All APIs encode the response in JSON. There is a top level envelope containing error information, and under the entry 'responseBody' it contains the actual content. All identifiers are UUIDs.
+All APIs encode the response in JSON.
+There is a top level envelope containing error information, and under the entry 'responseBody' it contains the actual content.
+All identifiers are UUIDs.
+The following endpoints are defined:
 
 * /solutions
-   List all public solutions. Accepts a query parameter, 'selector', which contains a JSON object with selection criteria, base64 encoded. Acceptable selection criteria are the solution object attributes. The entries are ANDed.
+
+  List all public solutions. Accepts a query parameter, 'selector', which contains a JSON object with selection criteria, base64 encoded. Acceptable selection criteria are the solution object attributes. The entries are ANDed.
 
 * /solutions/{solutionId}
+
   Retrieve one solution details.
 
 * /solutions/{solutionId}/revisions
+
   List all revisions for a given solution.
 
 * /solutions/{solutionId}/revisions/{revisionId}
+
   Retrieve one revision details
 
 * /solutions/{solutionId}/revisions/{revisionId}/artifacts
+
   List all artifacts attached to a particular revision
 
 * /artifacts/{artifactId}
+
   Retrieve one artifact details
 
 * /artifacts/{artifactId}/download
+
   Download the artifact content.
 
-Example of solutions selector:
+Example of solutions selector: The following will select all CLassifiers::
 
- { "modelTypeCode":"CL" } will select all CLassifiers
+    { "modelTypeCode":"CL" }
 
-Multiple values for a solution attribute are allowed and ORed
+Multiple values for a solution attribute are allowed and ORed.  The following will select all CLassifiers and PRedictors::
 
- { "modelTypeCode":["CL","PR"] } will select all CLassifiers and PRedictors
+    { "modelTypeCode":["CL","PR"] }
diff --git a/docs/fed-gw-arch.png b/docs/fed-gw-arch.png
new file mode 100644 (file)
index 0000000..cd8f9c1
Binary files /dev/null and b/docs/fed-gw-arch.png differ
index 9f2cc87..c6f2f77 100644 (file)
 .. limitations under the License.
 .. ===============LICENSE_END=========================================================
 
-=================
-Federated Gateway
-=================
+==================
+Federation Gateway
+==================
     
 .. toctree::
        :maxdepth: 2
-    
-       
+
+
+       overview.rst
+       design.rst
+       developer-guide.rst
        release-notes.rst
-       federated-gateway.rst
-       design-notes.rst
diff --git a/docs/overview.rst b/docs/overview.rst
new file mode 100644 (file)
index 0000000..c8180c8
--- /dev/null
@@ -0,0 +1,62 @@
+.. ===============LICENSE_START=======================================================
+.. Acumos CC-BY-4.0
+.. ===================================================================================
+.. Copyright (C) 2017 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
+.. ===================================================================================
+.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
+.. under the Creative Commons Attribution 4.0 International License (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+===========================
+Federation Gateway Overview
+===========================
+
+
+The Acumos Federation Gateway feature provides a mechanism to exchange models
+between two Acumos instances via a secure network channel.
+The goal was to have a mechanism that provides great flexibility when designing a deployment.
+The Gateway feature does not define how multiple Acumos instances are to be interconnected
+or what roles they play.
+
+Like many other system components, the Gateway is implemented as a server that listens 
+for requests on a REST API.  The Gateway provides two interfaces, both using REST:
+
+* Public: towards peers (also known as the "E5" interface)
+* Private: changes between gateway and different adapter implementations
+
+Architecture
+------------
+
+The following picture shows how the gateway components communicate with each other and with
+other Acumos features.  All communication is secured by use of client and server certificates.
+
+.. image:: fed-gw-arch.png
+    :align: center
+    :alt: Federation Gateway Architecture
+
+Developer Resources
+-------------------
+The source is available from the Linux Foundation Gerrit server:
+    `<https://gerrit.acumos.org/r/gitweb?p=federation.git;a=summary>`_
+
+The build (CI) jobs are in the Linux Foundation Jenkins server:
+
+    `<https://jenkins.acumos.org/view/federation/>`_
+
+Issues are tracked in the Linux Foundation Jira server:
+
+    `<https://jira.acumos.org/secure/Dashboard.jspa>`_
+
+Project information is available in the Linux Foundation Wiki:
+
+    `<https://wiki.acumos.org/>`_
index c3eb8ca..568bf95 100644 (file)
 .. limitations under the License.
 .. ===============LICENSE_END=========================================================
 
-===============================
-Federated Gateway Release Notes
-===============================
+================================
+Federation Gateway Release Notes
+================================
 
-The Federated Gateway server is available as a Docker image in a Docker registry.
+This server is available as a Docker image in a Docker registry at the Linux Foundation.
 
 --------------------------
 Version 1.18.5, 2018-10-02