Gitiles
Code Review Sign In
gerrit.nordix.org / onap / appc / ed9fd62c6060a3a5ae34a6fd61939f13be07973c / . / docs / APPC OAM API Guide / APPC OAM API Guide.rst
blob: ac79e935bfa3892156e1f63088ecaaa5a1268970 [file] [log] [blame]
Scott Seabolt7498c912017-10-30 09:35:09 -0400[diff] [blame]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
Hector Anapan9613c042017-10-18 21:02:18 -0400[diff] [blame]19APPC OAM API Guide
20==================
Scott Seabolt7498c912017-10-30 09:35:09 -0400[diff] [blame]21
22This guide describes the APPC OAM API that allows the user to manage and control the APPC application/component itself.
23
24APPC OAM Overview
25-----------------
26
27APPC **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
29The 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
51The 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
53Detailed Description
54--------------------
55
56All APIs are implemented via RESTCONF and can be access via the Application Controller dashboard.
57
58To access the dashboard, go to: ``https://<controller-ip>:8282/apidoc/explorer/index.html``
59
60You should see something similar to below.
61
62 .. image:: media/AppcAPIdocdiagram.png
63
64The 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
73These 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
96OAM-API State Transitions
97--------------------------
98
99The 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
115OAM Commands
116------------
117
118This section descripted the OAM API commands that are available for the Amsterdam release.
119
120Maintenance 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.openecomp.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.openecomp.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
206Get 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
290Get 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
322Stop 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
368Restart 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.openecomp.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.openecomp.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.openecomp.appc.oam.AppcOam\|\|\|\|\|\|\|APPC0157I
456 Application APPC is Started
457
458
459
460Start 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.openecomp.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.openecomp.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.openecomp.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