docs/APPC-OAM-API-Guide/APPC-OAM-API-Guide.rst

   1 .. ============LICENSE_START==========================================
   2 .. ===================================================================
   3 .. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
   4 .. ===================================================================
   5 .. Licensed under the Creative Commons License, Attribution 4.0 Intl.  (the "License");
   6 .. you may not use this documentation except in compliance with the License.
   7 .. You may obtain a copy of the License at
   8 ..
   9 ..  https://creativecommons.org/licenses/by/4.0/
  10 ..
  11 .. Unless required by applicable law or agreed to in writing, software
  12 .. distributed under the License is distributed on an "AS IS" BASIS,
  13 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 .. See the License for the specific language governing permissions and
  15 .. limitations under the License.
  16 .. ============LICENSE_END============================================
  17 .. ECOMP is a trademark and service mark of AT&T Intellectual Property.
  18
  19 APPC OAM API Guide
  20 ==================
  21
  22 This guide describes the APPC OAM API that allows the user to manage and control the APPC application/component itself.
  23
  24 APPC OAM Overview
  25 -----------------
  26
  27 APPC **OAM** API commands affect the state of the APPC application instance itself; whereas the APPC **LCM** API commands are issued via APPC and affect the state of VM/VNF/VNFCs.
  28
  29 The APPC OAM API currently provides the following commands:
  30
  31 +--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
  32 | **APPC OAM API**   | **Description**                                                                                                                                              |
  33 +====================+==============================================================================================================================================================+
  34 | maintenance-mode   | Puts the APPC instance into maintenance mode. When APPC is in Maintenance Mode,                                                                              |
  35 |                    |                                                                                                                                                              |
  36 |                    | -  APPC will stop accepting new requests                                                                                                                     |
  37 |                    |                                                                                                                                                              |
  38 |                    | -  The action will be considered complete once all existing requests have completed                                                                          |
  39 +--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
  40 | get-appc-state     | Returns the current state of the running APPC instance                                                                                                       |
  41 +--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
  42 | get-metrics        | Gets list of registered Metrics in APP-C                                                                                                                     |
  43 +--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
  44 | stop               | Force stop an APPC instance. In this mode, all APPC bundles will be stopped via an OSGI API                                                                  |
  45 +--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
  46 | restart            | Restarts an APPC instance, picking up any configuration changes. This command invokes the stop command followed by the start command.                        |
  47 +--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
  48 | start              | Starts the APPC instance; enables appc-provider-lcm so that it can begin to accept LCM request. This includes starting any APPC bundles which are stopped.   |
  49 +--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
  50
  51 The APPC database data is not affected by any of the OAM operations. The existing APPC configurations are not affected unless a Stop or Restart command is issues (just putting the APPC into maintenance mode and then starting it again is not sufficient). Notifications are sent out for state transitions. Refer to table below for details on state transitions supported.
  52
  53 Detailed Description
  54 --------------------
  55
  56 All APIs are implemented via RESTCONF and can be access via the Application Controller dashboard.
  57
  58 To access the dashboard, go to: ``https://<controller-ip>:8282/apidoc/explorer/index.html``
  59
  60 You should see something similar to below.
  61
  62         .. image:: media/AppcAPIdocdiagram.png
  63
  64 The current set of OAM APIs currently available are:
  65
  66 -  maintenance-mode
  67 -  get-appc-state
  68 -  get-metrics
  69 -  stop
  70 -  restart
  71 -  start
  72
  73 These commands operate on the APPC instance. Some usage notes below
  74
  75 -  After a Start or Restart, the APPC should be fully operational, meaning that all APPC bundles have been started, MYSQL is running, and the APPC is accepting new requests
  76
  77 -  When issuing the API which puts the APPC into maintenance mode, wait for all existing operations to complete
  78
  79    -  If the existing operations still have not completed after a maximum timeout of 60 minutes, the API will abort and be considered as having failed
  80
  81 -  Issuing a Stop does not wait for existing operations to complete
  82
  83    -  If you want to wait for all existing operations to complete and then stop the APPC, then first issue the API to put the APPC into maintenance mode and \ *then* issue a Stop API
  84
  85    -  There is a flag on the stop operation to make it "brutal" in order to skip waiting for requests to complete
  86
  87 -  If you change the configuration parameters before performing a restart, it should pick up the new configuration parameters
  88
  89 -  A healthy APPC instance is one which:
  90
  91    -  Can talk to DMaaP
  92    -  Can talk to A&AI
  93    -  Has all Karaf bundles from an APPC installation running
  94    -  Has MYSQL running
  95
  96 OAM-API State Transitions
  97 --------------------------
  98
  99 The table below documents the current state transition behaves. This is currently hard coded.
 100
 101 +--------------------------+-------------------+----------------------------+----------------+-----------------+----------------------------------+-----------------------+------------------+-------------+
 102 | **OAM API Command**      |                                                 **APPC Status**                                                                                                               |
 103 +==========================+===================+============================+================+=================+==================================+=======================+==================+=============+
 104 |                          | **Started**       | **In Maintenance Mode**    | **Stopped**    | **Starting**    | **Entering Maintenance Mode**    | **Force Stopping**    | **Restarting**   | **Error**   |
 105 +--------------------------+-------------------+----------------------------+----------------+-----------------+----------------------------------+-----------------------+------------------+-------------+
 106 | Start                    | Reject            | Accept                     | Accept         | Reject          | Reject                           | Reject                | Reject           | Accept      |
 107 +--------------------------+-------------------+----------------------------+----------------+-----------------+----------------------------------+-----------------------+------------------+-------------+
 108 | Enter Maintenance Mode   | Accept            | Reject                     | Reject         | Reject          | Reject                           | Reject                | Reject           | Reject      |
 109 +--------------------------+-------------------+----------------------------+----------------+-----------------+----------------------------------+-----------------------+------------------+-------------+
 110 | Force Stop               | Accept            | Accept                     | Reject         | Accept          | Accept                           | Reject                | Reject           | Accept      |
 111 +--------------------------+-------------------+----------------------------+----------------+-----------------+----------------------------------+-----------------------+------------------+-------------+
 112 | Restart                  | Accept            | Accept                     | Accept         | Accept          | Accept                           | Reject                | Reject           | Accept      |
 113 +--------------------------+-------------------+----------------------------+----------------+-----------------+----------------------------------+-----------------------+------------------+-------------+
 114
 115 OAM Commands
 116 ------------
 117
 118 This section descripted the OAM API commands that are available for the Amsterdam release.
 119
 120 Maintenance Mode API
 121 ~~~~~~~~~~~~~~~~~~~~
 122
 123 **Functional Description:**
 124
 125 -  Puts an APP-C instance into the Maintenance Mode state
 126 -  Waits for all currently executing or queued requests to complete
 127 -  Can only be issued from the Started state
 128
 129
 130
 131 **Request (Input) Example:**
 132
 133 **POST** ``https://10.147.104.163:8443/restconf/operations/appc-oam:maintenance-mode``
 134
 135   ::
 136
 137       {
 138         "input": {
 139           "common-header": {
 140             "flags": {
 141               "request-timeout": "0"
 142             },
 143             "request-id": " ecompController ",
 144             "originator-id": "demo-oam-maintenanceMode-id#1"
 145            }
 146         }
 147       }
 148
 149
 150
 151 **Response (Output) Example:**
 152
 153   **Maintenance-mode Response – Success Case**
 154
 155    ::
 156
 157        {
 158          "output": {
 159            "status": {
 160              "code": 100,
 161              "message": "ACCEPTED - request accepted"
 162            },
 163            "common-header": {
 164              "request-id": "demo-oam-maintenanceMode-id#1",
 165              "originator-id": "ecompController"
 166            }
 167          }
 168        }
 169
 170
 171   **Maintenance-mode Response – Rejection Case**
 172
 173    ::
 174
 175        {
 176          "output": {
 177            "status": {
 178              "code": 300,
 179              "message": "REJECTED - Invalid State Transition"
 180            },
 181            "common-header": {
 182              "request-id": "demo-oam-maintenanceMode-id#1",
 183              "originator-id": "ecompController"
 184            }
 185          }
 186        }
 187
 188
 189 **Audit Log Examples- Success Case**
 190
 191   ::
 192
 193     2017-06-02T13:58:55Z\|2017-06-02T13:58:55Z\|demo-oam-maintenance-mode-id#1\|\|qtp1068080075-58
 194     -
 195     /restconf/operations/appc-oam:maintenance-mode\|appc\|maintenance\_mode\|ecompController\|COMPLETE\|100\|ACCEPTED
 196     - request accepted\|\|INFO
 197     \|\|127.0.0.1\|9\|localhost\|\|org.onap.appc.oam.AppcOam\|\|\|\|\|\|\|APPC0154W
 198     Application APPC is entering maintenance mode...
 199
 200     2017-06-02T13:58:55Z\|2017-06-02T13:59:05Z\|demo-oam-maintenance-mode-id#1\|\|org.onap.appc.oam-bundle
 201     scheduledExecutor\|appc\|maintenance\_mode\|ecompController\|COMPLETE\|400\|SUCCESS
 202     - request has been processed successfully\|\|INFO
 203     \|\|127.0.0.1\|10033\|localhost\|\|\|\|\|\|\|\|\|APPC0155W
 204     Application APPC is in maintenance mode
 205
 206 Get APPC State API
 207 ~~~~~~~~~~~~~~~~~~
 208
 209 **Functional Description:**
 210
 211 -  Retrieves the current state of the APP-C instance.
 212
 213    -  If none of the other APPC State APIs have been used yet (i.e.; ``appc-oam:start``, ``appc-oam:maintenance-mode``, ``appc-oam:stop``, ``appc-oam:restart``), this command will read all the APPC-LCM bundles states and pick up the lowest bundle state as its response.
 214
 215 -  The APPC States versus the OSGI Bundle state mapping is defined as
 216    follows:
 217
 218 +---------------------------+-------------------------+
 219 | **Appc State**            | **OSGi Bundle State**   |
 220 +===========================+=========================+
 221 | EnteringMaintenanceMode   | ACTIVE                  |
 222 +---------------------------+-------------------------+
 223 | Error                     |                         |
 224 +---------------------------+-------------------------+
 225 | Instantiated              | INSTALLED               |
 226 +---------------------------+-------------------------+
 227 | MaintenanceMode           | ACTIVE                  |
 228 +---------------------------+-------------------------+
 229 | NotInstantiated           | UNINSTALLED             |
 230 +---------------------------+-------------------------+
 231 | Restarting                |                         |
 232 +---------------------------+-------------------------+
 233 | Started                   | ACTIVE                  |
 234 +---------------------------+-------------------------+
 235 | Starting                  | STARTING                |
 236 +---------------------------+-------------------------+
 237 | Stopped                   | RESOLVED                |
 238 +---------------------------+-------------------------+
 239 | Stopping                  | STOPPING                |
 240 +---------------------------+-------------------------+
 241 | Unknown                   |                         |
 242 +---------------------------+-------------------------+
 243
 244 **Request (Input) example:**
 245
 246 **POST**  ``https://10.147.104.163:8443/restconf/operations/appc-oam:get-appc-state``
 247
 248 **Response (Output) example:**
 249
 250   **Response: Get-Appc-Status – when APPC in Running state**
 251
 252     ::
 253
 254        {
 255          "output": {
 256            "state": "Started"
 257          }
 258        }
 259
 260   **Response: Get-Appc-Status – when APPC in Maintenance Mode state**
 261
 262     ::
 263
 264        {
 265          "output": {
 266            "state": "MaintenanceMode"
 267          }
 268        }
 269
 270   **Response: Get-Appc-Status – when APPC in Entering-Maintenance-Mode state**
 271
 272     ::
 273
 274        {
 275          "output": {
 276            "state": "EnteringMaintenanceMode"
 277          }
 278        }
 279
 280   **Response: Get-Appc-Status – when APPC in Error state**
 281
 282    ::
 283
 284        {
 285          "output": {
 286            "state": "Error"
 287        }
 288
 289
 290 Get Metrics API
 291 ~~~~~~~~~~~~~~~
 292
 293 **Functional Description:**
 294
 295 -  This operation gets list of registered Metrics in APPC.
 296 -  Metrics service must be enabled.
 297
 298 **Request (Input) example:**
 299
 300 **POST** ``https://10.147.104.163:8443/restconf/operations/appc-oam:get-metrics``
 301
 302 **Response (Output) example:**
 303
 304     **Response: get-metrics-Status – when APPC Metrics service is not enabled**
 305
 306    ::
 307
 308        {
 309          "errors": {
 310            "error": [
 311              {
 312                "error-type": "application",
 313                "error-tag": "operation-failed",
 314                "error-message": "Metric Service not enabled",
 315                "error-info": "<severity>error</severity>"
 316              }
 317            ]
 318          }
 319        }
 320
 321
 322 Stop API
 323 ~~~~~~~~
 324
 325 **Functional Description:**
 326
 327 -  Force stops the APPC bundles that accept LCM requests
 328 -  Does not wait for any currently executing or queued requests to complete
 329 -  Can be issued from the Started, Maintenance Mode, Starting or Entering Maintenance Mode states,
 330
 331 **Request (Input) example:**
 332
 333 **POST** ``https://10.147.104.163:8443/restconf/operations/appc-oam:stop``
 334
 335   ::
 336
 337        {
 338          "input": {
 339             "common-header": {
 340               "flags": {
 341                 "request-timeout": "0"
 342               },
 343               "request-id": "ecompController",,
 344               "originator-id": " demo-oam-stop-id#1"
 345             }
 346           }
 347        }
 348
 349 **Response (Output) example:**
 350
 351   **Stop Response – Success Case**  Expand source
 352
 353   ::
 354
 355                 {
 356                    "output": {
 357                          "status": {
 358                            "code": 100,
 359                            "message": "ACCEPTED - request accepted"
 360                          },
 361                          "common-header": {
 362                            "request-id": "demo-oam-stop-id#1",
 363                            "originator-id": "ecompController"
 364                          }
 365                         }
 366                 }
 367
 368 Restart API
 369 ~~~~~~~~~~~
 370
 371 **Functional Description:**
 372
 373 -  Restarts an APP-C instance
 374 -  Does not wait for any currently executing or queued requests to complete
 375 -  Can be issued from any state
 376 -  Restart command will
 377
 378    -  Tell dispatcher to start to reject new APPC LCM operation requests
 379    -  Immediately kill all currently running APPC LCM operations
 380    -  Stops all APPC bundles
 381    -  Stop MYSQL
 382    -  Start MYSQL
 383    -  Start all APPC Bundles
 384    -  Tell dispatcher to allow APPC to start accepting operations
 385    -  Return success
 386
 387 -  APPC DB data should not be affected
 388 -  Any configuration parameters which were changed prior to the restart have been picked up
 389
 390 **Request (Input) example:**
 391
 392 **POST** ``https://10.147.104.163:8443/restconf/operations/appc-oam:restart``
 393
 394   ::
 395
 396     {
 397       "input": {
 398         "common-header" : {
 399           "originator-id" : "ecompController",
 400           "request-id" : "demo-oam-restart-id#1"
 401         }
 402       }
 403     }
 404
 405 **Response (Output) example:**
 406
 407     **Restart Response – Success Case**
 408
 409        ::
 410
 411                 {
 412                   "output": {
 413                     "status": {
 414                       "code": 100,
 415                       "message": "ACCEPTED - request accepted"
 416                     },
 417                     "common-header": {
 418                       "request-id": "demo-oam-restart-id#1",
 419                       "originator-id": "ecompController"
 420                     }
 421                   }
 422                 }
 423
 424     **Restart Response – Rejection case**  Expand source
 425
 426        ::
 427
 428                 {
 429                   "output": {
 430                     "status": {
 431                       "code": 300,
 432                       "message": "REJECTED - Restart API is not allowed when APPC is in the Restarting state."
 433                     },
 434                     "common-header": {
 435                       "request-id": "demo-oam-restart-id#1",
 436                       "originator-id": "ecompController"
 437                     }
 438                   }
 439                 }
 440
 441 **Audit Log Examples - Success Case**
 442
 443   ::
 444
 445                 C2017-06-23T16:11:02Z\|2017-06-23T16:11:02Z\|demo-oam-restart-id#1\|\|qtp1752316482-134
 446                 -
 447                 /restconf/operations/appc-oam:restart\|appc\|restart\|ecompController\|COMPLETE\|100\|ACCEPTED
 448                 - request accepted\|\|INFO
 449                 \|\|127.0.0.1\|13\|localhost\|\|org.onap.appc.oam.AppcOam\|\|\|\|\|\|\|APPC0162W
 450                 Application APPC is Restarting
 451
 452                 2017-06-23T16:11:02Z\|2017-06-23T16:11:51Z\|demo-oam-restart-id#1\|\|org.onap.appc.oam-bundle
 453                 scheduledExecutor\|appc\|restart\|ecompController\|COMPLETE\|400\|SUCCESS
 454                 - request has been processed successfully\|\|INFO
 455                 \|\|127.0.0.1\|49198\|localhost\|\|org.onap.appc.oam.AppcOam\|\|\|\|\|\|\|APPC0157I
 456                 Application APPC is Started
 457
 458
 459
 460 Start API
 461 ~~~~~~~~~
 462
 463 **Functional Description:**
 464
 465 -  Starts an APP-C instance
 466 -  Can only be issued from the Stopped or Maintenance Mode states
 467
 468 **Request (Input) example:**
 469
 470 **POST** ``https://10.147.104.163:8443/restconf/operations/appc-oam:start``
 471
 472   ::
 473
 474     {
 475       "input": {
 476         "common-header": {
 477           "flags": {
 478             "request-timeout": "0"
 479           },
 480           "request-id": "ecompController",
 481           "originator-id": "demo-oam-start-id#1"
 482         }
 483       }
 484     }
 485
 486
 487 **Response (Output) example:**
 488
 489     **Response: appc-oam:start – Success case**
 490
 491           ::
 492
 493                 {
 494                   "output": {
 495                     "status": {
 496                       "code": 100,
 497                       "message": "ACCEPTED - request accepted"
 498                     },
 499                     "common-header": {
 500                       "request-id": "demo-oam-start-id#1",
 501                       "originator-id": "ecompController"
 502                     }
 503                   }
 504                 }
 505
 506     **Response: appc-oam-status – Rejection case**
 507
 508           ::
 509
 510                 {
 511                   "output": {
 512                     "status": {
 513                       "code": 300,
 514                       "message": "REJECTED - Invalid State Transition"
 515                     },
 516                     "common-header": {
 517                       "request-id": "demo-oam-start-id#1",
 518                       "originator-id": "ecompController"
 519                     }
 520                   }
 521                 }
 522
 523 **Audit Log Examples**
 524
 525     **Audit Log - Rejection**
 526
 527           ::
 528
 529                 2017-06-02T13:58:39Z\|2017-06-02T13:58:39Z\|\|\|qtp1068080075-57 -
 530                 /restconf/operations/appc-oam:start\|\|\|\|ERROR\|300\|REJECTED -
 531                 Invalid State Transition\|\|INFO
 532                 \|\|\|15\|\|\|org.onap.appc.oam.AppcOam\|\|\|\|\|\|\|APPC0156I
 533                 Application APPC is starting...
 534
 535     **Audit Log - Success case**
 536
 537           ::
 538
 539                 2017-06-02T13:59:16Z\|2017-06-02T13:59:16Z\|demo-oam-start-id#1\|\|qtp1068080075-58-
 540                 /restconf/operations/appc-oam:start\|appc\|start\|ecompController\|COMPLETE\|100\|ACCEPTED
 541                 - request accepted\|\|INFO
 542                 \|\|127.0.0.1\|2\|localhost\|\|org.onap.appc.oam.AppcOam\|\|\|\|\|\|\|APPC0156I
 543                 Application APPC is starting...
 544                 2017-06-02T13:59:16Z\|2017-06-02T13:59:17Z\|demo-oam-start-id#1\|\|org.onap.appc.oam-bundle
 545                 scheduledExecutor\|appc\|start\|ecompController\|COMPLETE\|400\|SUCCESS
 546                 - request has been processed successfully\|\|INFO
 547                 \|\|127.0.0.1\|1007\|localhost\|\|\|\|\|\|\|\|\|APPC0157I
 548                 Application APPC is started