summaryrefslogtreecommitdiffstats
path: root/grToolkit/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'grToolkit/README.md')
-rwxr-xr-xgrToolkit/README.md316
1 files changed, 316 insertions, 0 deletions
diff --git a/grToolkit/README.md b/grToolkit/README.md
new file mode 100755
index 00000000..84594496
--- /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