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