docs/requirements/NB_interface.rst

   1 .. _northbound_API:
   2
   3 Detailed northbound interface specification
   4 ===========================================
   5
   6 .. Note::
   7    This is Work in Progress.
   8
   9 ETSI NFV IFA Information Models
  10 -------------------------------
  11
  12 Compute Flavor
  13 ^^^^^^^^^^^^^^
  14
  15 A compute flavor includes information about number of virtual CPUs, size of
  16 virtual memory, size of virtual storage, and virtual network interfaces
  17 [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
  78 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
 325 Request to update compute resource reservation
 326
 327 .. http:post:: /reservation/compute/update
 328    :noindex:
 329
 330    **Example request**:
 331
 332    .. sourcecode:: http
 333
 334        POST /reservation/compute/update HTTP/1.1
 335        Accept: application/json
 336
 337        {
 338            "startTime": "2015-09-14T16:00:00Z",
 339            "reservationId": "xxxx-yyyy-zzzz"
 340        }
 341
 342    **Example response**:
 343
 344    .. sourcecode:: http
 345
 346        HTTP/1.1 201 CREATED
 347        Content-Type: application/json
 348
 349        {
 350          "reservationData": {
 351              "startTime": "2015-09-14TT16:00:00Z",
 352              "reservationStatus": "active",
 353              "reservationId": "xxxx-yyyy-zzzz",
 354              "computePoolReserved": {
 355                  "numCpuCores": 20,
 356                  "numVcInstances": 5,
 357                  "virtualMemSize": 10,
 358                  "zoneId": "23456"
 359              }
 360           }
 361        }
 362
 363 Terminate Compute Resource Reservation
 364 """"""""""""""""""""""""""""""""""""""
 365
 366 Request to terminate a compute resource reservation
 367
 368 .. http:delete:: /reservation/compute/(reservation_id)
 369    :noindex:
 370
 371 Virtualised Network Resources
 372 -----------------------------
 373
 374 Network Capacity Management
 375 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 376
 377 Subscribe Network Capacity Change Event
 378 """""""""""""""""""""""""""""""""""""""
 379
 380 Susbcription from Consumer to VIM to be notified about network capacity changes
 381
 382 .. http:post:: /capacity/network/subscribe
 383     :noindex:
 384
 385     **Example request**:
 386
 387     .. sourcecode:: http
 388
 389         POST /capacity/network/subscribe HTTP/1.1
 390         Accept: application/json
 391
 392         {
 393             "resourceDescriptor": [
 394                 {
 395                     "networkResourceTypeId": "publicIps"
 396                 }
 397             ],
 398             "threshold": [
 399                 {
 400                     "capacity_info": "available",
 401                     "condition": "lt",
 402                     "value": 5
 403                 }
 404             ]
 405         }
 406
 407     **Example response**:
 408
 409     .. sourcecode:: http
 410
 411         HTTP/1.1 201 CREATED
 412         Content-Type: application/json
 413
 414         {
 415            "created": "2015-09-28T00:00:00Z",
 416            "capacityChangeSubscriptionId": "bcdefg-hijklm-234567890"
 417         }
 418
 419 Query Network Capacity
 420 """"""""""""""""""""""
 421
 422 Request to find out about available, reserved, total and allocated network
 423 capacity.
 424
 425 .. http:get:: /capacity/network/query
 426     :noindex:
 427
 428     **Example request**:
 429
 430     .. sourcecode:: http
 431
 432         GET /capacity/network/query HTTP/1.1
 433         Accept: application/json
 434
 435         {
 436             "resourceDescriptor":  {
 437                 "networkResourceTypeId": "publicIps"
 438             },
 439             "timePeriod":  {
 440                 "startTime": "2015-09-28T00:00:00Z",
 441                 "stopTime": "2015-09-28T00:05:30Z"
 442             }
 443         }
 444
 445     **Example response**:
 446
 447     .. sourcecode:: http
 448
 449         HTTP/1.1 200 OK
 450         Content-Type: application/json
 451
 452         {
 453             "lastUpdate": "2015-09-28T00:02:10Z",
 454             "capacityInformation": {
 455                 "available": 4,
 456                 "reserved": 10,
 457                 "total": 64,
 458                 "allocated": 50
 459             }
 460         }
 461
 462 Notify Network Capacity Change Event
 463 """"""""""""""""""""""""""""""""""""
 464
 465 Notification about network capacity changes
 466
 467 .. http:post:: /capacity/network/notification
 468     :noindex:
 469
 470     **Example notification**:
 471
 472     .. sourcecode:: http
 473
 474         Content-Type: application/json
 475
 476         {
 477             "notificationId": "yxwvut-srqpon-876543210",
 478             "capacityChangeTime": "2015-09-28T00:02:10Z",
 479             "resourceDescriptor": {
 480                 "networkResourceTypeId": "publicIps"
 481             },
 482             "capacityInformation": {
 483                 "available": 4,
 484                 "reserved": 10,
 485                 "total": 64,
 486                 "allocated": 50
 487             }
 488         }
 489
 490 Network Resource Reservation
 491 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 492
 493 Create Network Resource Reservation
 494 """""""""""""""""""""""""""""""""""
 495
 496 Request the reservation of network resource capacity and/or virtual networks,
 497 network ports
 498
 499 .. http:post:: /reservation/network/create
 500     :noindex:
 501
 502     **Example request**:
 503
 504     .. sourcecode:: http
 505
 506         POST /reservation/network/create HTTP/1.1
 507         Accept: application/json
 508
 509         {
 510             "startTime": "2015-09-28T01:00:00Z",
 511             "networkReservation": {
 512                 "numPublicIps": 2
 513             }
 514         }
 515
 516     **Example response**:
 517
 518     .. sourcecode:: http
 519
 520         HTTP/1.1 201 CREATED
 521         Content-Type: application/json
 522
 523         {
 524             "reservationData": {
 525                 "startTime": "2015-09-28T01:00:00Z",
 526                 "reservationStatus": "initialized",
 527                 "reservationId": "wwww-xxxx-yyyy",
 528                 "networkReserved": {
 529                     "publicIps": [
 530                         "10.2.91.60",
 531                         "10.2.91.61"
 532                     ]
 533                 }
 534             }
 535         }
 536
 537 Query Network Resource Reservation
 538 """"""""""""""""""""""""""""""""""
 539
 540 Request to find out about reserved network resources that the consumer has
 541 access to.
 542
 543 .. http:get:: /reservation/network/query
 544     :noindex:
 545
 546     **Example request**:
 547
 548     .. sourcecode:: http
 549
 550         GET /reservation/network/query HTTP/1.1
 551         Accept: application/json
 552
 553         {
 554             "queryReservationFilter": [
 555                 {
 556                     "reservationId": "wwww-xxxx-yyyy"
 557                 }
 558             ]
 559         }
 560
 561     **Example response**:
 562
 563     .. sourcecode:: http
 564
 565        HTTP/1.1 200 OK
 566        Content-Type: application/json
 567
 568        {
 569            "reservationData": {
 570                "startTime": "2015-09-28T01:00:00Z",
 571                "reservationStatus": "active",
 572                "reservationId": "wwww-xxxx-yyyy",
 573                "networkReserved": "publicIps": [
 574                    "10.2.91.60",
 575                    "10.2.91.61"
 576                ]
 577            }
 578        }
 579
 580 Update Network Resource Reservation
 581 """""""""""""""""""""""""""""""""""
 582
 583 Request to update network resource reservation
 584
 585 .. http:post:: /reservation/network/update
 586     :noindex:
 587
 588     **Example request**:
 589
 590     .. sourcecode:: http
 591
 592          POST /reservation/network/update HTTP/1.1
 593          Accept: application/json
 594
 595          {
 596              "startTime": "2015-09-21T16:00:00Z",
 597              "reservationId": "wwww-xxxx-yyyy"
 598          }
 599
 600     **Example response**:
 601
 602     .. sourcecode:: http
 603
 604         HTTP/1.1 201 CREATED
 605         Content-Type: application/json
 606
 607         {
 608             "reservationData": {
 609                 "startTime": "2015-09-21T16:00:00Z",
 610                 "reservationStatus": "active",
 611                 "reservationId": "wwww-xxxx-yyyy",
 612                 "networkReserved": {
 613                     "publicIps": [
 614                         "10.2.91.60",
 615                         "10.2.91.61"
 616                      ]
 617                 }
 618             }
 619         }
 620
 621 Terminate Network Resource Reservation
 622 """"""""""""""""""""""""""""""""""""""
 623
 624 Request to terminate a network resource reservation
 625
 626 .. http:delete:: /reservation/network/(reservation_id)
 627     :noindex:
 628
 629
 630 Virtualised Storage Resources
 631
 632 -----------------------------
 633
 634 Storage Capacity Management
 635 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 636
 637 Subscribe Storage Capacity Change Event
 638 """""""""""""""""""""""""""""""""""""""
 639
 640 Subscription from Consumer to VIM to be notified about storage capacity changes
 641
 642 .. http:post:: /capacity/storage/subscribe
 643     :noindex:
 644
 645     **Example request**:
 646
 647     .. sourcecode:: http
 648
 649         POST /capacity/storage/subscribe HTTP/1.1
 650         Accept: application/json
 651
 652         {
 653            "resourceDescriptor": [
 654                {
 655                    "storageResourceTypeId": "volumes"
 656                }
 657            ],
 658            "threshold": [
 659                {
 660                    "capacity_info": "available",
 661                    "condition": "lt",
 662                    "value": 3
 663                }
 664            ]
 665         }
 666
 667     **Example response**:
 668
 669     .. sourcecode:: http
 670
 671         HTTP/1.1 201 CREATED
 672         Content-Type: application/json
 673
 674         {
 675             "created": "2015-09-28T12:00:00Z",
 676             "capacityChangeSubscriptionId": "cdefgh-ijklmn-345678901"
 677         }
 678
 679 Query Storage Capacity
 680 """"""""""""""""""""""
 681
 682 Request to find out about available, reserved, total and allocated storage
 683 capacity.
 684
 685 .. http:get:: /capacity/storage/query
 686     :noindex:
 687
 688     **Example request**:
 689
 690     .. sourcecode:: http
 691
 692         GET /capacity/storage/query HTTP/1.1
 693         Accept: application/json
 694
 695         {
 696             "resourceDescriptor": {
 697                 "storageResourceTypeId": "volumes"
 698             },
 699             "timePeriod":  {
 700                 "startTime": "2015-09-28T12:00:00Z",
 701                 "stopTime": "2015-09-28T12:04:45Z"
 702             }
 703         }
 704
 705     **Example response**:
 706
 707     .. sourcecode:: http
 708
 709        HTTP/1.1 200 OK
 710        Content-Type: application/json
 711
 712        {
 713            "lastUpdate": "2015-09-28T12:01:35Z",
 714            "capacityInformation": {
 715                "available": 2,
 716                "reserved": 4,
 717                "total": 10,
 718                "allocated": 4
 719            }
 720        }
 721
 722 Notify Storage Capacity Change Event
 723 """"""""""""""""""""""""""""""""""""
 724
 725 Notification about storage capacity changes
 726
 727 .. http:post:: /capacity/storage/notification
 728     :noindex:
 729
 730     **Example notification**:
 731
 732     .. sourcecode:: http
 733
 734         Content-Type: application/json
 735
 736         {
 737             "notificationId": "xwvuts-rqponm-765432109",
 738             "capacityChangeTime": "2015-09-28T12:01:35Z",
 739             "resourceDescriptor": {
 740                 "storageResourceTypeId": "volumes"
 741             },
 742             "capacityInformation": {
 743                 "available": 2,
 744                 "reserved": 4,
 745                 "total": 10,
 746                 "allocated": 4
 747             }
 748        }
 749
 750 Storage Resource Reservation
 751 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 752
 753 Create Storage Resource Reservation
 754 """""""""""""""""""""""""""""""""""
 755
 756 Request the reservation of storage resource capacity
 757
 758 .. http:post:: /reservation/storage/create
 759     :noindex:
 760
 761     **Example request**:
 762
 763     .. sourcecode:: http
 764
 765         POST /reservation/storage/create HTTP/1.1
 766         Accept: application/json
 767
 768         {
 769             "startTime": "2015-09-28T13:00:00Z",
 770             "storagePoolReservation": {
 771                 "storageSize": 10,
 772                 "numSnapshots": 3,
 773                 "numVolumes": 2
 774             }
 775         }
 776
 777     **Example response**:
 778
 779     .. sourcecode:: http
 780
 781         HTTP/1.1 201 CREATED
 782         Content-Type: application/json
 783
 784         {
 785             "reservationData": {
 786                 "startTime": "2015-09-28T13:00:00Z",
 787                 "reservationStatus": "initialized",
 788                 "reservationId": "vvvv-wwww-xxxx",
 789                 "storagePoolReserved": {
 790                     "storageSize": 10,
 791                     "numSnapshots": 3,
 792                     "numVolumes": 2
 793                 }
 794             }
 795         }
 796
 797 Query Storage Resource Reservation
 798 """"""""""""""""""""""""""""""""""
 799
 800 Request to find out about reserved storage resources that the consumer has
 801 access to.
 802
 803 .. http:get:: /reservation/storage/query
 804     :noindex:
 805
 806     **Example request**:
 807
 808     .. sourcecode:: http
 809
 810         GET /reservation/storage/query HTTP/1.1
 811         Accept: application/json
 812
 813         {
 814             "queryReservationFilter": [
 815                 {
 816                     "reservationId": "vvvv-wwww-xxxx"
 817                 }
 818             ]
 819         }
 820
 821     **Example response**:
 822
 823     .. sourcecode:: http
 824
 825         HTTP/1.1 200 OK
 826         Content-Type: application/json
 827
 828         {
 829             "reservationData": {
 830                 "startTime": "2015-09-28T13:00:00Z",
 831                 "reservationStatus": "active",
 832                 "reservationId": "vvvv-wwww-xxxx",
 833                 "storagePoolReserved": {
 834                     "storageSize": 10,
 835                     "numSnapshots": 3,
 836                     "numVolumes": 2
 837                 }
 838             }
 839         }
 840
 841 Update Storage Resource Reservation
 842 """""""""""""""""""""""""""""""""""
 843
 844 Request to update storage resource reservation
 845
 846 .. http:post:: /reservation/storage/update
 847     :noindex:
 848
 849     **Example request**:
 850
 851     .. sourcecode:: http
 852
 853         POST /reservation/storage/update HTTP/1.1
 854         Accept: application/json
 855
 856
 857         {
 858             "startTime": "2015-09-20T23:00:00Z",
 859             "reservationId": "vvvv-wwww-xxxx"
 860
 861         }
 862
 863     **Example response**:
 864
 865     .. sourcecode:: http
 866
 867         HTTP/1.1 201 CREATED
 868         Content-Type: application/json
 869
 870         {
 871             "reservationData": {
 872                 "startTime": "2015-09-20T23:00:00Z",
 873                 "reservationStatus": "active",
 874                 "reservationId": "vvvv-wwww-xxxx",
 875                 "storagePoolReserved": {
 876                     "storageSize": 10,
 877                     "numSnapshots": 3,
 878                     "numVolumes": 2
 879                 }
 880             }
 881         }
 882
 883 Terminate Storage Resource Reservation
 884 """"""""""""""""""""""""""""""""""""""
 885
 886 Request to terminate a storage resource reservation
 887
 888 .. http:delete:: /reservation/storage/(reservation_id)
 889     :noindex: