Split Shim-layer architecture and Integrated architecture
[promise.git] / docs / requirements / NB_interface.rst
1 Detailed northbound interface specification
2 ===========================================
3
4 .. Note::
5    This is Work in Progress.
6
7 ETSI NFV IFA Information Models
8 -------------------------------
9
10 Compute Flavor
11 ^^^^^^^^^^^^^^
12
13 A compute flavor includes information about number of virtual CPUs, size of
14 virtual memory, size of virtual storage, and virtual network interfaces
15 [NFVIFA005]_.
16
17 .. figure:: images/computeflavor.png
18    :name: computeflavor
19    :width: 90%
20
21 Virtualised Compute Resources
22 -----------------------------
23
24 Compute Capacity Management
25 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
26
27 Subscribe Compute Capacity Change Event
28 """""""""""""""""""""""""""""""""""""""
29
30 Subscription from Consumer to VIM to be notified about compute capacity changes
31
32 .. http:post:: /capacity/compute/subscribe
33    :noindex:
34
35    **Example request**:
36
37    .. sourcecode:: http
38
39        POST /capacity/compute/subscribe HTTP/1.1
40        Accept: application/json
41
42        {
43           "zoneId": "12345",
44           "resourceDescriptor": [
45               {
46                  "computeResourceTypeId": "vcInstances"
47               }
48           ],
49           "threshold": [
50               {
51                  "capacity_info": "available",
52                  "condition": "lt",
53                  "value": 5
54               }
55           ]
56       }
57
58    **Example response**:
59
60    .. sourcecode:: http
61
62        HTTP/1.1 201 CREATED
63        Content-Type: application/json
64
65        {
66           "created": "2015-09-21T00:00:00Z",
67           "capacityChangeSubscriptionId": "abcdef-ghijkl-123456789"
68        }
69
70    :statuscode 400: resourceDescriptor is missing
71
72 Query Compute Capacity
73 """"""""""""""""""""""
74
75 Request to find out about available, reserved, total and allocated compute
76 capacity.
77
78 .. http:get:: /capacity/compute/query
79    :noindex:
80
81    **Example request**:
82
83    .. sourcecode:: http
84
85       GET /capacity/compute/query HTTP/1.1
86       Accept: application/json
87
88       {
89         "zoneId": "12345",
90         "resourceDescriptor":  {
91              "computeResourceTypeId": "vcInstances"
92         },
93         "timePeriod":  {
94              "startTime": "2015-09-21T00:00:00Z",
95              "stopTime": "2015-09-21T00:05:30Z"
96         }
97       }
98
99    **Example response**:
100
101    .. sourcecode:: http
102
103        HTTP/1.1 200 OK
104        Content-Type: application/json
105
106        {
107           "zoneId": "12345",
108           "lastUpdate": "2015-09-21T00:03:20Z",
109           "capacityInformation": {
110              "available": 4,
111              "reserved": 17,
112              "total": 50,
113              "allocated": 29
114           }
115        }
116
117    :query limit: Default is 10.
118    :statuscode 404: resource zone unknown
119
120 Notify Compute Capacity Change Event
121 """"""""""""""""""""""""""""""""""""
122
123 Notification about compute capacity changes
124
125 .. http:post:: /capacity/compute/notification
126    :noindex:
127
128    **Example notification**:
129
130    .. sourcecode:: http
131
132       Content-Type: application/json
133
134       {
135            "zoneId": "12345",
136            "notificationId": "zyxwvu-tsrqpo-987654321",
137            "capacityChangeTime": "2015-09-21T00:03:20Z",
138            "resourceDescriptor": {
139               "computeResourceTypeId": "vcInstances"
140            },
141            "capacityInformation": {
142               "available": 4,
143               "reserved": 17,
144               "total": 50,
145               "allocated": 29
146            }
147       }
148
149 Compute Resource Reservation
150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
151
152 Create Compute Resource Reservation
153 """""""""""""""""""""""""""""""""""
154
155 Request the reservation of compute resource capacity
156
157 .. http:post:: /reservation/compute/create
158    :noindex:
159
160    **Example request**:
161
162    .. sourcecode:: http
163
164        POST /reservation/compute/create HTTP/1.1
165        Accept: application/json
166
167        {
168            "startTime": "2015-09-21T01:00:00Z",
169            "computePoolReservation": {
170                "numCpuCores": 20,
171                "numVcInstances": 5,
172                "virtualMemSize": 10
173            }
174        }
175
176    **Example response**:
177
178    .. sourcecode:: http
179
180        HTTP/1.1 201 CREATED
181        Content-Type: application/json
182
183        {
184           "reservationData": {
185              "startTime": "2015-09-21T01:00:00Z",
186              "reservationStatus": "initialized",
187              "reservationId": "xxxx-yyyy-zzzz",
188              "computePoolReserved": {
189                  "numCpuCores": 20,
190                  "numVcInstances": 5,
191                  "virtualMemSize": 10,
192                  "zoneId": "23456"
193              }
194           }
195        }
196
197 and/or virtualized containers
198
199 .. http:post:: reservation/compute/create
200    :noindex:
201
202    **Example request**:
203
204    .. sourcecode:: http
205
206        POST /reservation/compute/create HTTP/1.1
207        Accept: application/json
208
209        {
210          "startTime": "2015-10-05T15:00:00Z",
211          "virtualizationContainerReservation": [
212            {
213               "containerId": "myContainer",
214               "containerFlavor": {
215                  "flavorId": "myFlavor",
216                  "virtualCpu": {
217                     "numVirtualCpu": 2,
218                     "cpuArchitecture": "x86"
219                  },
220                  "virtualMemory": {
221                      "numaEnabled": "False",
222                      "virtualMemSize": 16
223                  },
224                  "virtualStorage": {
225                      "typeOfStorage": "volume",
226                      "sizeOfStorage": 16
227                  }
228               }
229            }
230          ]
231        }
232
233    **Example response**:
234
235    .. sourcecode:: http
236
237        HTTP/1.1 201 CREATED
238        Content-Type: application/json
239
240        {
241           "reservationData": {
242              "startTime": "2015-10-05T15:00:00Z",
243              "reservationId": "aaaa-bbbb-cccc",
244              "reservationStatus": "initialized",
245              "virtualizationContainerReserved": [
246                  {
247                     "containerId": "myContainer",
248                     "containerFlavor": {
249                         "flavorId": "myFlavor",
250                         "virtualCpu": {
251                            "numVirtualCpu": 2,
252                            "cpuArchitecture": "x86"
253                         },
254                         "virtualMemory": {
255                            "numaEnabled": "False",
256                            "virtualMemSize": 16
257                         },
258                         "virtualStorage": {
259                             "typeOfStorage": "volume",
260                             "sizeOfStorage": 16
261                         }
262                     }
263                  }
264              ]
265           }
266        }
267
268
269
270 Query Compute Resource Reservation
271 """"""""""""""""""""""""""""""""""
272
273 Request to find out about reserved compute resources that the consumer has
274 access to.
275
276 .. http:get:: /reservation/compute/query
277    :noindex:
278
279    **Example request**:
280
281    .. sourcecode:: http
282
283       GET /reservation/compute/query HTTP/1.1
284       Accept: application/json
285
286       {
287          "queryReservationFilter": [
288              {
289                  "reservationId": "xxxx-yyyy-zzzz"
290              }
291          ]
292
293       }
294
295    **Example response**:
296
297    .. sourcecode:: http
298
299        HTTP/1.1 200 OK
300        Content-Type: application/json
301
302        {
303           "reservationData":
304           {
305              "startTime": "2015-09-21T01:00:00Z",
306              "reservationStatus": "active",
307              "reservationId": "xxxx-yyyy-zzzz",
308              "computePoolReserved":
309              {
310                  "numCpuCores": 20,
311                  "numVcInstances": 5,
312                  "virtualMemSize": 10,
313                  "zoneId": "23456"
314              }
315           }
316        }
317
318    :statuscode 404: reservation id unknown
319
320 Update Compute Resource Reservation
321 """""""""""""""""""""""""""""""""""
322
323 Request to update compute resource reservation
324
325 .. http:post:: /reservation/compute/update
326    :noindex:
327
328    **Example request**:
329
330    .. sourcecode:: http
331
332        POST /reservation/compute/update HTTP/1.1
333        Accept: application/json
334
335        {
336            "startTime": "2015-09-14T16:00:00Z",
337            "reservationId": "xxxx-yyyy-zzzz"
338        }
339
340    **Example response**:
341
342    .. sourcecode:: http
343
344        HTTP/1.1 201 CREATED
345        Content-Type: application/json
346
347        {
348          "reservationData": {
349              "startTime": "2015-09-14TT16:00:00Z",
350              "reservationStatus": "active",
351              "reservationId": "xxxx-yyyy-zzzz",
352              "computePoolReserved": {
353                  "numCpuCores": 20,
354                  "numVcInstances": 5,
355                  "virtualMemSize": 10,
356                  "zoneId": "23456"
357              }
358           }
359        }
360
361 Terminate Compute Resource Reservation
362 """"""""""""""""""""""""""""""""""""""
363
364 Request to terminate a compute resource reservation
365
366 .. http:delete:: /reservation/compute/(reservation_id)
367    :noindex:
368
369 Virtualised Network Resources
370 -----------------------------
371
372 Network Capacity Management
373 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
374
375 Subscribe Network Capacity Change Event
376 """""""""""""""""""""""""""""""""""""""
377
378 Susbcription from Consumer to VIM to be notified about network capacity changes
379
380 .. http:post:: /capacity/network/subscribe
381     :noindex:
382
383     **Example request**:
384
385     .. sourcecode:: http
386
387         POST /capacity/network/subscribe HTTP/1.1
388         Accept: application/json
389
390         {
391             "resourceDescriptor": [
392                 {
393                     "networkResourceTypeId": "publicIps"
394                 }
395             ],
396             "threshold": [
397                 {
398                     "capacity_info": "available",
399                     "condition": "lt",
400                     "value": 5
401                 }
402             ]
403         }
404
405     **Example response**:
406
407     .. sourcecode:: http
408
409         HTTP/1.1 201 CREATED
410         Content-Type: application/json
411
412         {
413            "created": "2015-09-28T00:00:00Z",
414            "capacityChangeSubscriptionId": "bcdefg-hijklm-234567890"
415         }
416
417 Query Network Capacity
418 """"""""""""""""""""""
419
420 Request to find out about available, reserved, total and allocated network
421 capacity.
422
423 .. http:get:: /capacity/network/query
424     :noindex:
425
426     **Example request**:
427
428     .. sourcecode:: http
429
430         GET /capacity/network/query HTTP/1.1
431         Accept: application/json
432
433         {
434             "resourceDescriptor":  {
435                 "networkResourceTypeId": "publicIps"
436             },
437             "timePeriod":  {
438                 "startTime": "2015-09-28T00:00:00Z",
439                 "stopTime": "2015-09-28T00:05:30Z"
440             }
441         }
442
443     **Example response**:
444
445     .. sourcecode:: http
446
447         HTTP/1.1 200 OK
448         Content-Type: application/json
449
450         {
451             "lastUpdate": "2015-09-28T00:02:10Z",
452             "capacityInformation": {
453                 "available": 4,
454                 "reserved": 10,
455                 "total": 64,
456                 "allocated": 50
457             }
458         }
459
460 Notify Network Capacity Change Event
461 """"""""""""""""""""""""""""""""""""
462
463 Notification about network capacity changes
464
465 .. http:post:: /capacity/network/notification
466     :noindex:
467
468     **Example notification**:
469
470     .. sourcecode:: http
471
472         Content-Type: application/json
473
474         {
475             "notificationId": "yxwvut-srqpon-876543210",
476             "capacityChangeTime": "2015-09-28T00:02:10Z",
477             "resourceDescriptor": {
478                 "networkResourceTypeId": "publicIps"
479             },
480             "capacityInformation": {
481                 "available": 4,
482                 "reserved": 10,
483                 "total": 64,
484                 "allocated": 50
485             }
486         }
487
488 Network Resource Reservation
489 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
490
491 Create Network Resource Reservation
492 """""""""""""""""""""""""""""""""""
493
494 Request the reservation of network resource capacity and/or virtual networks,
495 network ports
496
497 .. http:post:: /reservation/network/create
498     :noindex:
499
500     **Example request**:
501
502     .. sourcecode:: http
503
504         POST /reservation/network/create HTTP/1.1
505         Accept: application/json
506
507         {
508             "startTime": "2015-09-28T01:00:00Z",
509             "networkReservation": {
510                 "numPublicIps": 2
511             }
512         }
513
514     **Example response**:
515
516     .. sourcecode:: http
517
518         HTTP/1.1 201 CREATED
519         Content-Type: application/json
520
521         {
522             "reservationData": {
523                 "startTime": "2015-09-28T01:00:00Z",
524                 "reservationStatus": "initialized",
525                 "reservationId": "wwww-xxxx-yyyy",
526                 "networkReserved": {
527                     "publicIps": [
528                         "10.2.91.60",
529                         "10.2.91.61"
530                     ]
531                 }
532             }
533         }
534
535 Query Network Resource Reservation
536 """"""""""""""""""""""""""""""""""
537
538 Request to find out about reserved network resources that the consumer has
539 access to.
540
541 .. http:get:: /reservation/network/query
542     :noindex:
543
544     **Example request**:
545
546     .. sourcecode:: http
547
548         GET /reservation/network/query HTTP/1.1
549         Accept: application/json
550
551         {
552             "queryReservationFilter": [
553                 {
554                     "reservationId": "wwww-xxxx-yyyy"
555                 }
556             ]
557         }
558
559     **Example response**:
560
561     .. sourcecode:: http
562
563        HTTP/1.1 200 OK
564        Content-Type: application/json
565
566        {
567            "reservationData": {
568                "startTime": "2015-09-28T01:00:00Z",
569                "reservationStatus": "active",
570                "reservationId": "wwww-xxxx-yyyy",
571                "networkReserved": "publicIps": [
572                    "10.2.91.60",
573                    "10.2.91.61"
574                ]
575            }
576        }
577
578 Update Network Resource Reservation
579 """""""""""""""""""""""""""""""""""
580
581 Request to update network resource reservation
582
583 .. http:post:: /reservation/network/update
584     :noindex:
585
586     **Example request**:
587
588     .. sourcecode:: http
589
590          POST /reservation/network/update HTTP/1.1
591          Accept: application/json
592
593          {
594              "startTime": "2015-09-21T16:00:00Z",
595              "reservationId": "wwww-xxxx-yyyy"
596          }
597
598     **Example response**:
599
600     .. sourcecode:: http
601
602         HTTP/1.1 201 CREATED
603         Content-Type: application/json
604
605         {
606             "reservationData": {
607                 "startTime": "2015-09-21T16:00:00Z",
608                 "reservationStatus": "active",
609                 "reservationId": "wwww-xxxx-yyyy",
610                 "networkReserved": {
611                     "publicIps": [
612                         "10.2.91.60",
613                         "10.2.91.61"
614                      ]
615                 }
616             }
617         }
618
619 Terminate Network Resource Reservation
620 """"""""""""""""""""""""""""""""""""""
621
622 Request to terminate a network resource reservation
623
624 .. http:delete:: /reservation/network/(reservation_id)
625     :noindex:
626
627
628 Virtualised Storage Resources
629
630 -----------------------------
631
632 Storage Capacity Management
633 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
634
635 Subscribe Storage Capacity Change Event
636 """""""""""""""""""""""""""""""""""""""
637
638 Subscription from Consumer to VIM to be notified about storage capacity changes
639
640 .. http:post:: /capacity/storage/subscribe
641     :noindex:
642
643     **Example request**:
644
645     .. sourcecode:: http
646
647         POST /capacity/storage/subscribe HTTP/1.1
648         Accept: application/json
649
650         {
651            "resourceDescriptor": [
652                {
653                    "storageResourceTypeId": "volumes"
654                }
655            ],
656            "threshold": [
657                {
658                    "capacity_info": "available",
659                    "condition": "lt",
660                    "value": 3
661                }
662            ]
663         }
664
665     **Example response**:
666
667     .. sourcecode:: http
668
669         HTTP/1.1 201 CREATED
670         Content-Type: application/json
671
672         {
673             "created": "2015-09-28T12:00:00Z",
674             "capacityChangeSubscriptionId": "cdefgh-ijklmn-345678901"
675         }
676
677 Query Storage Capacity
678 """"""""""""""""""""""
679
680 Request to find out about available, reserved, total and allocated storage
681 capacity.
682
683 .. http:get:: /capacity/storage/query
684     :noindex:
685
686     **Example request**:
687
688     .. sourcecode:: http
689
690         GET /capacity/storage/query HTTP/1.1
691         Accept: application/json
692
693         {
694             "resourceDescriptor": {
695                 "storageResourceTypeId": "volumes"
696             },
697             "timePeriod":  {
698                 "startTime": "2015-09-28T12:00:00Z",
699                 "stopTime": "2015-09-28T12:04:45Z"
700             }
701         }
702
703     **Example response**:
704
705     .. sourcecode:: http
706
707        HTTP/1.1 200 OK
708        Content-Type: application/json
709
710        {
711            "lastUpdate": "2015-09-28T12:01:35Z",
712            "capacityInformation": {
713                "available": 2,
714                "reserved": 4,
715                "total": 10,
716                "allocated": 4
717            }
718        }
719
720 Notify Storage Capacity Change Event
721 """"""""""""""""""""""""""""""""""""
722
723 Notification about storage capacity changes
724
725 .. http:post:: /capacity/storage/notification
726     :noindex:
727
728     **Example notification**:
729
730     .. sourcecode:: http
731
732         Content-Type: application/json
733
734         {
735             "notificationId": "xwvuts-rqponm-765432109",
736             "capacityChangeTime": "2015-09-28T12:01:35Z",
737             "resourceDescriptor": {
738                 "storageResourceTypeId": "volumes"
739             },
740             "capacityInformation": {
741                 "available": 2,
742                 "reserved": 4,
743                 "total": 10,
744                 "allocated": 4
745             }
746        }
747
748 Storage Resource Reservation
749 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
750
751 Create Storage Resource Reservation
752 """""""""""""""""""""""""""""""""""
753
754 Request the reservation of storage resource capacity
755
756 .. http:post:: /reservation/storage/create
757     :noindex:
758
759     **Example request**:
760
761     .. sourcecode:: http
762
763         POST /reservation/storage/create HTTP/1.1
764         Accept: application/json
765
766         {
767             "startTime": "2015-09-28T13:00:00Z",
768             "storagePoolReservation": {
769                 "storageSize": 10,
770                 "numSnapshots": 3,
771                 "numVolumes": 2
772             }
773         }
774
775     **Example response**:
776
777     .. sourcecode:: http
778
779         HTTP/1.1 201 CREATED
780         Content-Type: application/json
781
782         {
783             "reservationData": {
784                 "startTime": "2015-09-28T13:00:00Z",
785                 "reservationStatus": "initialized",
786                 "reservationId": "vvvv-wwww-xxxx",
787                 "storagePoolReserved": {
788                     "storageSize": 10,
789                     "numSnapshots": 3,
790                     "numVolumes": 2
791                 }
792             }
793         }
794
795 Query Storage Resource Reservation
796 """"""""""""""""""""""""""""""""""
797
798 Request to find out about reserved storage resources that the consumer has
799 access to.
800
801 .. http:get:: /reservation/storage/query
802     :noindex:
803
804     **Example request**:
805
806     .. sourcecode:: http
807
808         GET /reservation/storage/query HTTP/1.1
809         Accept: application/json
810
811         {
812             "queryReservationFilter": [
813                 {
814                     "reservationId": "vvvv-wwww-xxxx"
815                 }
816             ]
817         }
818
819     **Example response**:
820
821     .. sourcecode:: http
822
823         HTTP/1.1 200 OK
824         Content-Type: application/json
825
826         {
827             "reservationData": {
828                 "startTime": "2015-09-28T13:00:00Z",
829                 "reservationStatus": "active",
830                 "reservationId": "vvvv-wwww-xxxx",
831                 "storagePoolReserved": {
832                     "storageSize": 10,
833                     "numSnapshots": 3,
834                     "numVolumes": 2
835                 }
836             }
837         }
838
839 Update Storage Resource Reservation
840 """""""""""""""""""""""""""""""""""
841
842 Request to update storage resource reservation
843
844 .. http:post:: /reservation/storage/update
845     :noindex:
846
847     **Example request**:
848
849     .. sourcecode:: http
850
851         POST /reservation/storage/update HTTP/1.1
852         Accept: application/json
853
854
855         {
856             "startTime": "2015-09-20T23:00:00Z",
857             "reservationId": "vvvv-wwww-xxxx"
858
859         }
860
861     **Example response**:
862
863     .. sourcecode:: http
864
865         HTTP/1.1 201 CREATED
866         Content-Type: application/json
867
868         {
869             "reservationData": {
870                 "startTime": "2015-09-20T23:00:00Z",
871                 "reservationStatus": "active",
872                 "reservationId": "vvvv-wwww-xxxx",
873                 "storagePoolReserved": {
874                     "storageSize": 10,
875                     "numSnapshots": 3,
876                     "numVolumes": 2
877                 }
878             }
879         }
880
881 Terminate Storage Resource Reservation
882 """"""""""""""""""""""""""""""""""""""
883
884 Request to terminate a storage resource reservation
885
886 .. http:delete:: /reservation/storage/(reservation_id)
887     :noindex: