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