grToolkit/README.md

   1 Introduction
   2 ======================
   3 You have generated an MD-SAL module.
   4
   5 * You should be able to successfully run ```mvn clean install``` on this project.
   6
   7 Next Steps
   8 ======================
   9 * Run a ```mvn clean install``` if you haven't already. This will generate some code from the yang models.
  10 * Modify the model yang file under the model project.
  11 * Follow the comments in the generated provider class to wire your new provider into the generated
  12 code.
  13 * Modify the generated provider model to respond to and handle the yang model. Depending on what
  14 you added to your model you may need to inherit additional interfaces or make other changes to
  15 the provider model.
  16
  17 Generated Bundles
  18 ======================
  19 * model
  20     - Provides the yang model for your application. This is your primary northbound interface.
  21 * provider
  22     - Provides a template implementation for a provider to respond to your yang model.
  23 * features
  24     - Defines a karaf feature. If you add dependencies on third-party bundles then you will need to
  25       modify the features.xml to list out the dependencies.
  26 * installer
  27     - Bundles all of the jars and third party dependencies (minus ODL dependencies) into a single
  28       .zip file.
  29
  30 Usage
  31 ======================
  32 ## Purpose
  33 The purpose of this ODL feature is to support geo-redundancy through a series of ODL integrated health checks and tools.
  34
  35 ## Properties File
  36 On initialization gr-toolkit expects to find a file named ```gr-toolkit.properties``` located in the ```SDNC_CONFIG``` directory. The properties file should contain:
  37 - ```akka.conf.location```
  38     - The path to the akka.conf configuration file.
  39 - ```adm.useSsl```
  40     - true/false; Determines whether or not to use http or https when making requests to the Admin Portal.
  41 - ```adm.fqdn```
  42     - The FQDN or url of the site's Admin Portal.
  43 - ```adm.healthcheck```
  44     - The url path of the Admin Portal's health check page.
  45 - ```adm.port.http```
  46     - The HTTP port for the Admin Portal.
  47 - ```adm.port.ssl```
  48     - The HTTPS port for the Admin Portal.
  49 - ```controller.credentials```
  50     - username:password; The credentials used to make requests to the ODL controller.
  51 - ```controller.useSsl```
  52     - true/false; Determines whether or not to use http or https when making requests to the controller.
  53 - ```controller.port.http```
  54     - The HTTP port for the ODL Controller.
  55 - ```controller.port.ssl```
  56     - The HTTPS port for the ODL Controller.
  57 - ```controller.port.akka```
  58     - The port used for Akka communications on the ODL Controller.
  59 - ```mbean.cluster```
  60     - The Jolokia path for the Akka Cluster MBean.
  61 - ```mbean.shardManager```
  62     - The Jolokia path for the Akka ShardManager MBean.
  63 - ```mbean.shard.config```
  64     - 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.
  65 - ```site.identifier```
  66     - A unique identifier for the site the ODL Controller resides on.
  67
  68 ## Site Identifier
  69 Returns a unique site identifier of the site the ODL resides on.
  70
  71 > ### Input: None
  72 >
  73 > ### Output
  74 > ```json
  75 > {
  76 >   "output": {
  77 >     "id": "UNIQUE_IDENTIFIER_HERE",
  78 >     "status": "200"
  79 >   }
  80 > }
  81 > ```
  82
  83 ## Admin Health
  84 Returns HEALTHY/FAULTY based on whether or not a 200 response is received from the Admin Portal's health check page.
  85
  86 > ### Input: None
  87 >
  88 > ### Output
  89 > ```json
  90 > {
  91 >   "output": {
  92 >     "status": "200",
  93 >     "health": "HEALTHY"
  94 >   }
  95 > }
  96 > ```
  97
  98 ## Database Health
  99 Returns HEALTHY/FAULTY based on if DbLib can obtain a writeable connection from its pool.
 100
 101 > ### Input: None
 102 >
 103 > ### Output
 104 > ```json
 105 > {
 106 >   "output": {
 107 >     "status": "200",
 108 >     "health": "HEALTHY"
 109 >   }
 110 > }
 111 > ```
 112
 113 ## Cluster Health
 114 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.
 115
 116 > ### Input: None
 117 >
 118 > ### Output
 119 > ```json
 120 > {
 121 >   "output": {
 122 >     "site1-health": "HEALTHY",
 123 >     "members": [
 124 >       {
 125 >         "address": "member-3.node",
 126 >         "role": "member-3",
 127 >         "unreachable": false,
 128 >         "voting": true,
 129 >         "up": true,
 130 >         "replicas": [
 131 >           {
 132 >             "shard": "member-3-shard-default-config"
 133 >           }
 134 >         ]
 135 >       },
 136 >       {
 137 >         "address": "member-1.node",
 138 >         "role": "member-1",
 139 >         "unreachable": false,
 140 >         "voting": true,
 141 >         "up": true,
 142 >         "replicas": [
 143 >           {
 144 >             "shard": "member-1-shard-default-config"
 145 >           }
 146 >         ]
 147 >       },
 148 >       {
 149 >         "address": "member-5.node",
 150 >         "role": "member-5",
 151 >         "unreachable": false,
 152 >         "voting": false,
 153 >         "up": true,
 154 >         "replicas": [
 155 >           {
 156 >             "shard": "member-5-shard-default-config"
 157 >           }
 158 >         ]
 159 >       },
 160 >       {
 161 >         "address": "member-2.node",
 162 >         "role": "member-2",
 163 >         "unreachable": false,
 164 >         "leader": [
 165 >           {
 166 >             "shard": "member-2-shard-default-config"
 167 >           }
 168 >         ],
 169 >         "commit-status": [
 170 >           {
 171 >             "shard": "member-5-shard-default-config",
 172 >             "delta": 148727
 173 >           },
 174 >           {
 175 >             "shard": "member-4-shard-default-config",
 176 >             "delta": 148869
 177 >           }
 178 >         ],
 179 >         "voting": true,
 180 >         "up": true,
 181 >         "replicas": [
 182 >           {
 183 >             "shard": "member-2-shard-default-config"
 184 >           }
 185 >         ]
 186 >       },
 187 >       {
 188 >         "address": "member-4.node",
 189 >         "role": "member-4",
 190 >         "unreachable": false,
 191 >         "voting": false,
 192 >         "up": true,
 193 >         "replicas": [
 194 >           {
 195 >             "shard": "member-4-shard-default-config"
 196 >           }
 197 >         ]
 198 >       },
 199 >       {
 200 >         "address": "member-6.node",
 201 >         "role": "member-6",
 202 >         "unreachable": false,
 203 >         "voting": false,
 204 >         "up": true,
 205 >         "replicas": [
 206 >           {
 207 >             "shard": "member-6-shard-default-config"
 208 >           }
 209 >         ]
 210 >       }
 211 >     ],
 212 >     "status": "200",
 213 >     "site2-health": "HEALTHY"
 214 >   }
 215 > }
 216 > ```
 217
 218 ## Site Health
 219 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.
 220
 221 > ### Input: None
 222 >
 223 > ### Output
 224 > ```json
 225 > {
 226 >   "output": {
 227 >     "sites": [
 228 >       {
 229 >         "id": "SITE_1",
 230 >         "role": "ACTIVE",
 231 >         "health": "HEALTHY"
 232 >       },
 233 >       {
 234 >         "id": "SITE_2",
 235 >         "role": "STANDBY",
 236 >         "health": "FAULTY"
 237 >       }
 238 >     ],
 239 >     "status": "200"
 240 >   }
 241 > }
 242 > ```
 243
 244 ## Halt Akka Traffic
 245 Places rules in IP Tables to block Akka traffic to/from a specific node on a specified port.
 246
 247 > ### Input:
 248 > ```json
 249 > {
 250 >   "input": {
 251 >     "node-info": [
 252 >       {
 253 >         "node": "your.odl.node",
 254 >         "port": "2550"
 255 >       }
 256 >     ]
 257 >   }
 258 > }
 259 > ```
 260 >
 261 > ### Output
 262 > ```json
 263 > {
 264 >   "output": {
 265 >     "status": "200"
 266 >   }
 267 > }
 268 > ```
 269
 270 ## Resume Akka Traffic
 271 Removes rules in IP Tables to allow Akka traffic to/from a specifc node on a specified port.
 272
 273 > ### Input:
 274 > ```json
 275 > {
 276 >   "input": {
 277 >     "node-info": [
 278 >       {
 279 >         "node": "your.odl.node",
 280 >         "port": "2550"
 281 >       }
 282 >     ]
 283 >   }
 284 > }
 285 > ```
 286 >
 287 > ### Output
 288 > ```json
 289 > {
 290 >   "output": {
 291 >     "status": "200"
 292 >   }
 293 > }
 294 > ```
 295
 296 ## Failover
 297 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).
 298
 299 > ### Input:
 300 > ```json
 301 > {
 302 >   "input": {
 303 >     "backupData": "true"
 304 >   }
 305 > }
 306 > ```
 307 >
 308 > ### Output
 309 > ```json
 310 > {
 311 >   "output": {
 312 >     "status": "200",
 313 >     "message": "Failover complete."
 314 >   }
 315 > }
 316 > ```