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: