From 1723b4e1b4115f3ad4c9a3d5b61fdf72010e6493 Mon Sep 17 00:00:00 2001 From: abatos Date: Tue, 13 Jun 2017 12:09:02 -0400 Subject: [PATCH] Addition of Synapse readmes Change-Id: I3620724dc9980b0d0fb0ab686480e43bf495f67f Signed-off-by: abatos --- CONCEPTS.md | 3 ++ FUNCTIONS.md | 75 ++++++++++++++++++++++++++++++++++ README.md | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 206 insertions(+) create mode 100644 CONCEPTS.md create mode 100644 FUNCTIONS.md create mode 100644 README.md diff --git a/CONCEPTS.md b/CONCEPTS.md new file mode 100644 index 0000000..7a51216 --- /dev/null +++ b/CONCEPTS.md @@ -0,0 +1,3 @@ +# High Level Concepts + +As it's core routing engine, Synapse uses Apache Camel routes to solve a number of enterprise integration problems. This allows us to take data from an arbitrary source, perform any necessary processing on it, and pass that data to an arbitrary target. For further information on Apache Camel refer to their documentation at http://camel.apache.org/ \ No newline at end of file diff --git a/FUNCTIONS.md b/FUNCTIONS.md new file mode 100644 index 0000000..b2090e1 --- /dev/null +++ b/FUNCTIONS.md @@ -0,0 +1,75 @@ +# ONAP Functions + +The _Synapse_ data router comes packaged with a set of functionality that needs to be configured (as described at [Synapse README](./README.md)). This section describes specific functionality that _Synapse_ is capable of fulfilling given the appropriate configuration. + +## Entity Change Event + + +### Configuration + +##### Contents of the /opt/app/datarouter-service/dynamic/conf Directory + +_entity-event-policy.xml_ + +In order to take advantage of the entity change event functionality the following configuration spring bean file should be present with the appropriate fields filled in: + + + + + + + + + + + + + + + + + + + + + + +Description of configuration fields: + +sourceDomain: AAI adds a domain tag against all entity change event records published to the event bus. If the configured sourceDomain does not match with the domain value provided in the entity change event, that event is silently discarded. +searchBaseURL: the URL for the search service that this version of Synapse should send entity change records to. The format should be https://host:port. +searchEndpoint: the base endpoint for the indexes resource on the search service. There should be no need to modify this value from the default unless the version of the search service API changes. +searchEndpointDocuments: the resource path identifier for documents in the search service. This value is appended to the searchEndpoint to build up the resource path for documents. There should be no need to modfiy this value from the default. +searchEntitySearchIndex: the name of the index in search service that will hold the entity change record. +searchTopographySearchIndex: the index name for storing topographical data in the search service. This index holds geographic coordinates for entities, and is used to plot points on a map within the AAIUI. +searchEntityAutoSuggestIndex: the index name for storing auto-suggestion data in the search service. Data stored in this index is used in AAIUI to populate VNF search suggestions. +searchAggregationVnfIndex: the index name for storing VNF data in the search service. Data stored in this index is used in AAIUI to populate summary information about VNFs on certain attributes like provisioning status and orchestration status. +searchCertName: the name of the search service certificate file. Synapse looks for this file in the /opt/app/datarouter-service/app-config/auth directory. +searchKeystorePwd: the obsfuscated password for the configured keystore file. This keystore password should be obfuscated using the Jetty password obfuscation tool. +searchKeystore: the name of the Synapse data router service keystore file. Synapse looks for this file in the /opt/app/datarouter-service/app-config/auth directory. + +##### Contents of the /opt/app/datarouter-service/dynamic/routes Directory + +The purpose of this configuration directory is to maintain Camel route files specific to _Synapse_ use cases. +The following option files should be present in this directory on the host machine: + +_entity-event.route_ + +In order to take advantage of the entity change event functionality the following configuration Apache Camel route file should be present with the appropriate fields filled in: + + + + + + +Description of configuration fields: + +event-bus-client-name: a unique name identifying this consumer of the event bus +event-topic: the name of the topic that this client should consume from +groupName: the consumer group name for this client. The name here should be carefully considered. If this client is added to an existing consumer group, then the client will become responsible for a set of partitions on the topic. +groupId: a unique identifier for this client among the consumer group +dmaap-url: a set of one or more comma separated urls of dmaap servers that this client should attempt to connect to ie: http://dmaap1:3904,http://dmaap2:3904 \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..f020a07 --- /dev/null +++ b/README.md @@ -0,0 +1,128 @@ +# Synapse Micro Service + +## Overview +The Synapse microservice (data router service) acts as a message broker between different sources of information and business logic within the context of AAI. The goal is to provide an extensible framework that can stitch sources of data and business logic together to satisfy use cases through configuration and minimal coding. + +Please refer to the following sub-sections for more detailed information: + +[High Level Concepts](./CONCEPTS.md) - Discussion of the high level concepts and building blocks of the _SYNAPSE_ Data Router service. + +[Synapse Functions](./FUNCTIONS.md) - Discussion of the high level use cases that Synapse can fulfill upon deployment and configuration + +## Getting Started + +### Building The Micro Service + +After cloning the project, execute the following Maven command from the project's top level directory to build the project: + + > mvn clean install + +Now, you can build your Docker image: + + > docker build -t onap/datarouter-service target + +### Deploying The Micro Service + +Push the Docker image that you have built to your Docker repository and pull it down to the location that you will be running Synapse from. + +Note that in order to take advantage of some of the base functionality of Synapse, you will need to have the following: + +* optional access to DMaaP in order to pull data off of configured topics +* optional access to a search service installation in order to be able to write indexable data + + +**Create the following directories on the host machine:** + + /logs + /opt/app/datarouter-service/appconfig + +You will be mounting these as data volumes when you start the Docker container. + +**Populate these directories as follows:** + +##### Contents of /opt/app/datarouter-service/appconfig + +The purpose of this configuration directory is to maintain general configuration files for the _Synapse_ data routing service. +The following files must be present in this directory on the host machine: + +_data-router.properties_ + +This file currently requires no configuration but should still remain for future use cases + +##### Contents of the /opt/app/datarouter-service/app-config/auth Directory + +The purpose of this configuration directory is to maintain configuration files specific to authentication/authorization for the _Synapse_ data routing service. +The following files must be present in this directory on the host machine: + +_data-router\_policy.json_ + +Create a policy file defining the roles and users that will be allowed to access _Synapse_ data routing service. This is a JSON format file which will look something like the following example: + + { + "roles": [ + { + "name": "admin", + "functions": [ + { + "name": "search", "methods": [ { "name": "GET" },{ "name": "DELETE" }, { "name": "PUT" }, { "name": "POST" } ] + } + ], + "users": [ + { + "username": "CN=synapseadmin, OU=My Organization Unit, O=, L=Sometown, ST=SomeProvince, C=CA" + } + ] + } + ] + } + +_tomcat\_keystore_ + +Create a keystore with this name containing whatever CA certificates that you want your instance of the _Synapse_ data routing service to accept for HTTPS traffic. + +_search-certificate_ + +Provide a certificate that will allow the _Synapse_ data routing service to communicate with the configured search service via HTTPS + +##### Contents of the /opt/app/datarouter-service/app-config/model Directory + +The purpose of this configuration directory is to maintain model configuration files for the _Synapse_ data routing service. +The following files must be present in this directory on the host machine: + +_aai_oxm_(.*).xml_ + +Any AAI OXM model files must be placed in the model directory and be named with the aai_oxm_ prefix. ex: aai_oxm_v9.xml. These files are used for use cases that are model driven. + +##### Contents of the /opt/app/datarouter-service/dynamic/conf Directory + +The purpose of this configuration directory is to maintain configuration spring bean files specific to _Synapse_ use cases. Please refer to [Synapse Functions](./FUNCTIONS.md) for information on specific use cases. + + +##### Contents of the /opt/app/datarouter-service/dynamic/routes Directory + +The purpose of this configuration directory is to maintain Camel route files specific to _Synapse_ use cases. Please refer to [Synapse Functions](./FUNCTIONS.md) for information on specific use cases. + +**Start the service:** + +You can now start the Docker container for the _Synapse_ data router service, in the following manner: + + docker run -d \ + -p 9502:9502 \ + -e CONFIG_HOME=/opt/app/datarouter-service/config/ \ + -e KEY_STORE_PASSWORD=OBF:{{obfuscated password}} \ + -e KEY_MANAGER_PASSWORD=OBF:{{obfuscated password}} \ + -e MAX_HEAP={{jvmmaxheap}} \ + -v /logs:/opt/aai/logroot/AAI-DR \ + -v /opt/app/datarouter-service/appconfig:/opt/app/datarouter-service/config \ + --name datarouter-service \ + {{your docker repo}}/datarouter-service + +Where, + + {{your docker repo}} = The Docker repository you have published the Synapse Data Router Service image to. + {{obfuscated password}} = The password for your key store/key manager after running it through the Jetty obfuscation tool. + {{jvmmaxheap}} = The max heap size of the JVM for the microservice + + + + \ No newline at end of file -- 2.16.6