Merge branch 'master' of /home/jwagantall/linuxfoundation/onap/IT-21112/sli-plugins

Signed-off-by: Jessica Wagantall <jwagantall@linuxfoundation.org>

1 files changed, 316 insertions, 0 deletions

diff --git a/grToolkit/README.md b/grToolkit/README.md
new file mode 100755
index 000000000..84594496b
--- /dev/null
+++ b/grToolkit/README.md
@@ -0,0 +1,316 @@
+Introduction
+======================
+You have generated an MD-SAL module.
+
+* You should be able to successfully run ```mvn clean install``` on this project.
+
+Next Steps
+======================
+* Run a ```mvn clean install``` if you haven't already. This will generate some code from the yang models.
+* Modify the model yang file under the model project.
+* Follow the comments in the generated provider class to wire your new provider into the generated 
+code.
+* Modify the generated provider model to respond to and handle the yang model. Depending on what
+you added to your model you may need to inherit additional interfaces or make other changes to
+the provider model.
+
+Generated Bundles
+======================
+* model
+    - Provides the yang model for your application. This is your primary northbound interface.
+* provider
+    - Provides a template implementation for a provider to respond to your yang model.
+* features
+    - Defines a karaf feature. If you add dependencies on third-party bundles then you will need to
+      modify the features.xml to list out the dependencies.
+* installer
+    - Bundles all of the jars and third party dependencies (minus ODL dependencies) into a single
+      .zip file.
+
+Usage
+======================
+## Purpose
+The purpose of this ODL feature is to support geo-redundancy through a series of ODL integrated health checks and tools.
+
+## Properties File
+On initialization gr-toolkit expects to find a file named ```gr-toolkit.properties``` located in the ```SDNC_CONFIG``` directory. The properties file should contain:
+- ```akka.conf.location```
+    - The path to the akka.conf configuration file.
+- ```adm.useSsl```
+    - true/false; Determines whether or not to use http or https when making requests to the Admin Portal.
+- ```adm.fqdn```
+    - The FQDN or url of the site's Admin Portal.
+- ```adm.healthcheck```
+    - The url path of the Admin Portal's health check page.
+- ```adm.port.http```
+    - The HTTP port for the Admin Portal.
+- ```adm.port.ssl```
+    - The HTTPS port for the Admin Portal.
+- ```controller.credentials```
+    - username:password; The credentials used to make requests to the ODL controller.
+- ```controller.useSsl```
+    - true/false; Determines whether or not to use http or https when making requests to the controller.
+- ```controller.port.http```
+    - The HTTP port for the ODL Controller.
+- ```controller.port.ssl```
+    - The HTTPS port for the ODL Controller.
+- ```controller.port.akka```
+    - The port used for Akka communications on the ODL Controller.
+- ```mbean.cluster```
+    - The Jolokia path for the Akka Cluster MBean.
+- ```mbean.shardManager```
+    - The Jolokia path for the Akka ShardManager MBean.
+- ```mbean.shard.config```
+    - The Jolokia path for the Akka Shard MBean. This should be templated to look like ```/jolokia/read/org.opendaylight.controller:Category=Shards,name=%s,type=DistributedConfigDatastore```. GR Toolkit will use this template with information pulled from the Akka ShardManager MBean.
+- ```site.identifier```
+    - A unique identifier for the site the ODL Controller resides on.
+
+## Site Identifier
+Returns a unique site identifier of the site the ODL resides on.
+
+> ### Input: None
+> 
+> ### Output
+> ```json
+> {
+>   "output": {
+>     "id": "UNIQUE_IDENTIFIER_HERE",
+>     "status": "200"
+>   }
+> }
+> ```
+
+## Admin Health
+Returns HEALTHY/FAULTY based on whether or not a 200 response is received from the Admin Portal's health check page.
+
+> ### Input: None
+> 
+> ### Output
+> ```json
+> {
+>   "output": {
+>     "status": "200",
+>     "health": "HEALTHY"
+>   }
+> }
+> ```
+
+## Database Health
+Returns HEALTHY/FAULTY based on if DbLib can obtain a writeable connection from its pool.
+
+> ### Input: None
+> 
+> ### Output
+> ```json
+> {
+>   "output": {
+>     "status": "200",
+>     "health": "HEALTHY"
+>   }
+> }
+> ```
+
+## Cluster Health
+Uses Jolokia queries to determine shard health and voting status. In a 3 ODL node configuration, 2 FAULTY nodes constitutes a FAULTY site. In a 6 node configuration it is assumed that there are 2 sites consiting of 3 nodes each.
+
+> ### Input: None
+> 
+> ### Output
+> ```json
+> {
+>   "output": {
+>     "site1-health": "HEALTHY",
+>     "members": [
+>       {
+>         "address": "member-3.node",
+>         "role": "member-3",
+>         "unreachable": false,
+>         "voting": true,
+>         "up": true,
+>         "replicas": [
+>           {
+>             "shard": "member-3-shard-default-config"
+>           }
+>         ]
+>       },
+>       {
+>         "address": "member-1.node",
+>         "role": "member-1",
+>         "unreachable": false,
+>         "voting": true,
+>         "up": true,
+>         "replicas": [
+>           {
+>             "shard": "member-1-shard-default-config"
+>           }
+>         ]
+>       },
+>       {
+>         "address": "member-5.node",
+>         "role": "member-5",
+>         "unreachable": false,
+>         "voting": false,
+>         "up": true,
+>         "replicas": [
+>           {
+>             "shard": "member-5-shard-default-config"
+>           }
+>         ]
+>       },
+>       {
+>         "address": "member-2.node",
+>         "role": "member-2",
+>         "unreachable": false,
+>         "leader": [
+>           {
+>             "shard": "member-2-shard-default-config"
+>           }
+>         ],
+>         "commit-status": [
+>           {
+>             "shard": "member-5-shard-default-config",
+>             "delta": 148727
+>           },
+>           {
+>             "shard": "member-4-shard-default-config",
+>             "delta": 148869
+>           }
+>         ],
+>         "voting": true,
+>         "up": true,
+>         "replicas": [
+>           {
+>             "shard": "member-2-shard-default-config"
+>           }
+>         ]
+>       },
+>       {
+>         "address": "member-4.node",
+>         "role": "member-4",
+>         "unreachable": false,
+>         "voting": false,
+>         "up": true,
+>         "replicas": [
+>           {
+>             "shard": "member-4-shard-default-config"
+>           }
+>         ]
+>       },
+>       {
+>         "address": "member-6.node",
+>         "role": "member-6",
+>         "unreachable": false,
+>         "voting": false,
+>         "up": true,
+>         "replicas": [
+>           {
+>             "shard": "member-6-shard-default-config"
+>           }
+>         ]
+>       }
+>     ],
+>     "status": "200",
+>     "site2-health": "HEALTHY"
+>   }
+> }
+> ```
+
+## Site Health
+Aggregates data from Admin Health, Database Health, and Cluster Health and returns a simplified payload containing the health of a site. A FAULTY Admin Portal or Database health status will constitute a FAULTY site; in a 3 ODL node configuration, 2 FAULTY nodes constitutes a FAULTY site. If any portion of the health check registers as FAULTY, the entire site will be designated as FAULTY. In a 6 node configuration these health checks are performed cross site as well.
+
+> ### Input: None
+> 
+> ### Output
+> ```json
+> {
+>   "output": {
+>     "sites": [
+>       {
+>         "id": "SITE_1",
+>         "role": "ACTIVE",
+>         "health": "HEALTHY"
+>       },
+>       {
+>         "id": "SITE_2",
+>         "role": "STANDBY",
+>         "health": "FAULTY"
+>       }
+>     ],
+>     "status": "200"
+>   }
+> }
+> ```
+
+## Halt Akka Traffic
+Places rules in IP Tables to block Akka traffic to/from a specific node on a specified port.
+
+> ### Input:
+> ```json
+> {
+>   "input": {
+>     "node-info": [
+>       {
+>         "node": "your.odl.node",
+>         "port": "2550"
+>       }
+>     ]
+>   }
+> }
+> ```
+> 
+> ### Output
+> ```json
+> {
+>   "output": {
+>     "status": "200"
+>   }
+> }
+> ```
+
+## Resume Akka Traffic
+Removes rules in IP Tables to allow Akka traffic to/from a specifc node on a specified port.
+
+> ### Input:
+> ```json
+> {
+>   "input": {
+>     "node-info": [
+>       {
+>         "node": "your.odl.node",
+>         "port": "2550"
+>       }
+>     ]
+>   }
+> }
+> ```
+> 
+> ### Output
+> ```json
+> {
+>   "output": {
+>     "status": "200"
+>   }
+> }
+> ```
+
+## Failover
+Only usable in a 6 ODL node configuration. Determines which site is active/standby, switches voting to the standby site, and isolates the old active site. If backupData=true an MD-SAL export will be scheduled and backed up to a Nexus server (requires ccsdk.sli.northbound.daexim-offsite-backup feature).
+
+> ### Input:
+> ```json
+> {
+>   "input": {
+>     "backupData": "true"
+>   }
+> }
+> ```
+> 
+> ### Output
+> ```json
+> {
+>   "output": {
+>     "status": "200",
+>     "message": "Failover complete."
+>   }
+> }
+> ```
\ No newline at end of file