docs/requirements/NB_interface.rst

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