From 78aa63af02df682b3c8d825c1bec9cec6cd3b207 Mon Sep 17 00:00:00 2001
From: Gerald Kunzmann <kunzmann@docomolab-euro.com>
Date: Thu, 9 Feb 2017 09:36:29 +0000
Subject: Update docs structure according to new guidelines in
https://wiki.opnfv.org/display/DOC
Change-Id: I69e6536d9044dd9db2ed3cd698059aa3a800c318
Signed-off-by: Gerald Kunzmann <kunzmann@docomolab-euro.com>
---
docs/development/requirements/NB_interface.rst | 1061 ++++++++++++++++++++
docs/development/requirements/annex1.rst | 37 +
docs/development/requirements/architecture.rst | 258 +++++
docs/development/requirements/gap_analysis.rst | 99 ++
docs/development/requirements/glossary.rst | 73 ++
docs/development/requirements/images/LICENSE | 14 +
.../requirements/images/computeflavor.png | Bin 0 -> 105698 bytes
docs/development/requirements/images/figure1.png | Bin 0 -> 32278 bytes
docs/development/requirements/images/figure2.png | Bin 0 -> 149390 bytes
docs/development/requirements/images/figure3.png | Bin 0 -> 38065 bytes
docs/development/requirements/images/figure4.png | Bin 0 -> 218419 bytes
docs/development/requirements/images/figure5.png | Bin 0 -> 38402 bytes
.../requirements/images/figure5_new.png | Bin 0 -> 69226 bytes
docs/development/requirements/images/figure6.png | Bin 0 -> 401171 bytes
.../requirements/images/figure6_new.png | Bin 0 -> 129286 bytes
.../requirements/images/figure7_new.png | Bin 0 -> 172805 bytes
.../development/requirements/impl_architecture.rst | 313 ++++++
docs/development/requirements/index.rst | 52 +
docs/development/requirements/intro.rst | 39 +
docs/development/requirements/references.rst | 25 +
docs/development/requirements/revision.rst | 43 +
docs/development/requirements/schemas.rst | 658 ++++++++++++
docs/development/requirements/summary.rst | 27 +
docs/development/requirements/supported_apis.rst | 608 +++++++++++
docs/development/requirements/usecase.rst | 121 +++
.../feature.configuration.rst | 63 --
docs/installationprocedure/images/LICENSE | 14 -
.../images/screenshot_promise.png | Bin 101419 -> 0 bytes
.../images/screenshot_promise_install.png | Bin 77709 -> 0 bytes
docs/installationprocedure/index.rst | 13 -
docs/release/configguide/feature.configuration.rst | 63 ++
docs/release/configguide/images/LICENSE | 14 +
.../configguide/images/screenshot_promise.png | Bin 0 -> 101419 bytes
.../images/screenshot_promise_install.png | Bin 0 -> 77709 bytes
docs/release/configguide/index.rst | 13 +
docs/release/userguide/feature.userguide.rst | 294 ++++++
docs/release/userguide/index.rst | 12 +
docs/requirements/NB_interface.rst | 1061 --------------------
docs/requirements/annex1.rst | 37 -
docs/requirements/architecture.rst | 258 -----
docs/requirements/gap_analysis.rst | 99 --
docs/requirements/glossary.rst | 73 --
docs/requirements/images/LICENSE | 14 -
docs/requirements/images/computeflavor.png | Bin 105698 -> 0 bytes
docs/requirements/images/figure1.png | Bin 32278 -> 0 bytes
docs/requirements/images/figure2.png | Bin 149390 -> 0 bytes
docs/requirements/images/figure3.png | Bin 38065 -> 0 bytes
docs/requirements/images/figure4.png | Bin 218419 -> 0 bytes
docs/requirements/images/figure5.png | Bin 38402 -> 0 bytes
docs/requirements/images/figure5_new.png | Bin 69226 -> 0 bytes
docs/requirements/images/figure6.png | Bin 401171 -> 0 bytes
docs/requirements/images/figure6_new.png | Bin 129286 -> 0 bytes
docs/requirements/images/figure7_new.png | Bin 172805 -> 0 bytes
docs/requirements/impl_architecture.rst | 313 ------
docs/requirements/index.rst | 52 -
docs/requirements/intro.rst | 39 -
docs/requirements/references.rst | 25 -
docs/requirements/revision.rst | 43 -
docs/requirements/schemas.rst | 658 ------------
docs/requirements/summary.rst | 27 -
docs/requirements/supported_apis.rst | 608 -----------
docs/requirements/usecase.rst | 121 ---
docs/userguide/feature.userguide.rst | 294 ------
docs/userguide/index.rst | 12 -
64 files changed, 3824 insertions(+), 3824 deletions(-)
create mode 100644 docs/development/requirements/NB_interface.rst
create mode 100644 docs/development/requirements/annex1.rst
create mode 100644 docs/development/requirements/architecture.rst
create mode 100644 docs/development/requirements/gap_analysis.rst
create mode 100644 docs/development/requirements/glossary.rst
create mode 100644 docs/development/requirements/images/LICENSE
create mode 100755 docs/development/requirements/images/computeflavor.png
create mode 100644 docs/development/requirements/images/figure1.png
create mode 100755 docs/development/requirements/images/figure2.png
create mode 100755 docs/development/requirements/images/figure3.png
create mode 100755 docs/development/requirements/images/figure4.png
create mode 100755 docs/development/requirements/images/figure5.png
create mode 100644 docs/development/requirements/images/figure5_new.png
create mode 100755 docs/development/requirements/images/figure6.png
create mode 100644 docs/development/requirements/images/figure6_new.png
create mode 100644 docs/development/requirements/images/figure7_new.png
create mode 100644 docs/development/requirements/impl_architecture.rst
create mode 100644 docs/development/requirements/index.rst
create mode 100644 docs/development/requirements/intro.rst
create mode 100644 docs/development/requirements/references.rst
create mode 100644 docs/development/requirements/revision.rst
create mode 100644 docs/development/requirements/schemas.rst
create mode 100644 docs/development/requirements/summary.rst
create mode 100644 docs/development/requirements/supported_apis.rst
create mode 100644 docs/development/requirements/usecase.rst
delete mode 100644 docs/installationprocedure/feature.configuration.rst
delete mode 100644 docs/installationprocedure/images/LICENSE
delete mode 100755 docs/installationprocedure/images/screenshot_promise.png
delete mode 100644 docs/installationprocedure/images/screenshot_promise_install.png
delete mode 100644 docs/installationprocedure/index.rst
create mode 100644 docs/release/configguide/feature.configuration.rst
create mode 100644 docs/release/configguide/images/LICENSE
create mode 100755 docs/release/configguide/images/screenshot_promise.png
create mode 100644 docs/release/configguide/images/screenshot_promise_install.png
create mode 100644 docs/release/configguide/index.rst
create mode 100644 docs/release/userguide/feature.userguide.rst
create mode 100644 docs/release/userguide/index.rst
delete mode 100644 docs/requirements/NB_interface.rst
delete mode 100644 docs/requirements/annex1.rst
delete mode 100644 docs/requirements/architecture.rst
delete mode 100644 docs/requirements/gap_analysis.rst
delete mode 100644 docs/requirements/glossary.rst
delete mode 100644 docs/requirements/images/LICENSE
delete mode 100755 docs/requirements/images/computeflavor.png
delete mode 100644 docs/requirements/images/figure1.png
delete mode 100755 docs/requirements/images/figure2.png
delete mode 100755 docs/requirements/images/figure3.png
delete mode 100755 docs/requirements/images/figure4.png
delete mode 100755 docs/requirements/images/figure5.png
delete mode 100644 docs/requirements/images/figure5_new.png
delete mode 100755 docs/requirements/images/figure6.png
delete mode 100644 docs/requirements/images/figure6_new.png
delete mode 100644 docs/requirements/images/figure7_new.png
delete mode 100644 docs/requirements/impl_architecture.rst
delete mode 100644 docs/requirements/index.rst
delete mode 100644 docs/requirements/intro.rst
delete mode 100644 docs/requirements/references.rst
delete mode 100644 docs/requirements/revision.rst
delete mode 100644 docs/requirements/schemas.rst
delete mode 100644 docs/requirements/summary.rst
delete mode 100644 docs/requirements/supported_apis.rst
delete mode 100644 docs/requirements/usecase.rst
delete mode 100644 docs/userguide/feature.userguide.rst
delete mode 100644 docs/userguide/index.rst
diff --git a/docs/development/requirements/NB_interface.rst b/docs/development/requirements/NB_interface.rst
new file mode 100644
index 0000000..8dba601
--- /dev/null
+++ b/docs/development/requirements/NB_interface.rst
@@ -0,0 +1,1061 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _northbound_API:
+
+Detailed northbound interface specification
+===========================================
+
+.. Note::
+ This is Work in Progress.
+
+ETSI NFV IFA Information Models
+-------------------------------
+
+Compute Flavor
+^^^^^^^^^^^^^^
+
+A compute flavor includes information about number of virtual CPUs, size of
+virtual memory, size of virtual storage, and virtual network interfaces
+[NFVIFA005]_.
+
+.. figure:: images/computeflavor.png
+ :name: computeflavor
+ :width: 90%
+
+Virtualised Compute Resources
+-----------------------------
+
+Compute Capacity Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Subscribe Compute Capacity Change Event
+"""""""""""""""""""""""""""""""""""""""
+
+Subscription from Consumer to VIM to be notified about compute capacity changes
+
+.. http:post:: /capacity/compute/subscribe
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /capacity/compute/subscribe HTTP/1.1
+ Accept: application/json
+
+ {
+ "zoneId": "12345",
+ "computeResourceTypeId": "vcInstances",
+ "threshold": {
+ "thresholdType" : "absoluteValue",
+ "threshold": {
+ "capacity_info": "available",
+ "condition": "lt",
+ "value": 5
+ }
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "created": "2015-09-21T00:00:00Z",
+ "capacityChangeSubscriptionId": "abcdef-ghijkl-123456789"
+ }
+
+ :statuscode 400: computeResourceTypeId is missing
+
+Query Compute Capacity for a defined resource type
+""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Request to find out about available, reserved, total and allocated compute
+capacity.
+
+.. http:get:: /capacity/compute/query
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ GET /capacity/compute/query HTTP/1.1
+ Accept: application/json
+
+ {
+ "zoneId": "12345",
+ "computeResourceTypeId": "vcInstances",
+ "timePeriod": {
+ "startTime": "2015-09-21T00:00:00Z",
+ "stopTime": "2015-09-21T00:05:30Z"
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "zoneId": "12345",
+ "lastUpdate": "2015-09-21T00:03:20Z",
+ "capacityInformation": {
+ "available": 4,
+ "reserved": 17,
+ "total": 50,
+ "allocated": 29
+ }
+ }
+
+ :query limit: Default is 10.
+ :statuscode 404: resource zone unknown
+
+
+Query Compute Capacity with required attributes
+"""""""""""""""""""""""""""""""""""""""""""""""
+Request to find out available compute capacity with given characteristics
+
+.. http:get:: /capacity/compute/query
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ GET /capacity/compute/query HTTP/1.1
+ Accept: application/json
+
+ {
+ "zoneId": "12345",
+ "resourceCriteria": {
+ "virtualCPU": {
+ "cpuArchitecture": "x86",
+ "numVirtualCpu": 8
+ }
+ },
+ "attributeSelector": "available",
+ "timePeriod": {
+ "startTime": "2015-09-21T00:00:00Z",
+ "stopTime": "2015-09-21T00:05:30Z"
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "zoneId": "12345",
+ "lastUpdate": "2015-09-21T00:03:20Z",
+ "capacityInformation": {
+ "available": 50
+ }
+ }
+
+ :query limit: Default is 10.
+ :statuscode 404: resource zone unknown
+
+Notify Compute Capacity Change Event
+""""""""""""""""""""""""""""""""""""
+
+Notification about compute capacity changes
+
+.. http:post:: /capacity/compute/notification
+ :noindex:
+
+ **Example notification**:
+
+ .. sourcecode:: http
+
+ Content-Type: application/json
+
+ {
+ "zoneId": "12345",
+ "notificationId": "zyxwvu-tsrqpo-987654321",
+ "capacityChangeTime": "2015-09-21T00:03:20Z",
+ "resourceDescriptor": {
+ "computeResourceTypeId": "vcInstances"
+ },
+ "capacityInformation": {
+ "available": 4,
+ "reserved": 17,
+ "total": 50,
+ "allocated": 29
+ }
+ }
+
+Compute Resource Reservation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create Compute Resource Reservation
+"""""""""""""""""""""""""""""""""""
+
+Request the reservation of compute resource capacity
+
+.. http:post:: /reservation/compute/create
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /reservation/compute/create HTTP/1.1
+ Accept: application/json
+
+ {
+ "startTime": "2015-09-21T01:00:00Z",
+ "computePoolReservation": {
+ "numCpuCores": 20,
+ "numVcInstances": 5,
+ "virtualMemSize": 10
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "reservationData": {
+ "startTime": "2015-09-21T01:00:00Z",
+ "reservationStatus": "initialized",
+ "reservationId": "xxxx-yyyy-zzzz",
+ "computePoolReserved": {
+ "numCpuCores": 20,
+ "numVcInstances": 5,
+ "virtualMemSize": 10,
+ "zoneId": "23456"
+ }
+ }
+ }
+
+or virtualization containers
+
+.. http:post:: reservation/compute/create
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /reservation/compute/create HTTP/1.1
+ Accept: application/json
+
+ {
+ "startTime": "2015-10-05T15:00:00Z",
+ "virtualizationContainerReservation": [
+ {
+ "containerId": "myContainer",
+ "containerFlavor": {
+ "flavorId": "myFlavor",
+ "virtualCpu": {
+ "numVirtualCpu": 2,
+ "cpuArchitecture": "x86"
+ },
+ "virtualMemory": {
+ "numaEnabled": "False",
+ "virtualMemSize": 16
+ },
+ "storageAttributes": {
+ "typeOfStorage": "volume",
+ "sizeOfStorage": 16
+ }
+ }
+ }
+ ]
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "reservationData": {
+ "startTime": "2015-10-05T15:00:00Z",
+ "reservationId": "aaaa-bbbb-cccc",
+ "reservationStatus": "initialized",
+ "virtualizationContainerReserved": [
+ {
+ "containerId": "myContainer",
+ "flavorId": "myFlavor",
+ "virtualCpu": {
+ "numVirtualCpu": 2,
+ "cpuArchitecture": "x86"
+ },
+ "virtualMemory": {
+ "numaEnabled": "False",
+ "virtualMemSize": 16
+ },
+ "virtualDisks": {
+ "storageId": "myStorage",
+ "flavourId": "myStorageFlavour",
+ "typeOfStorage": "volume",
+ "sizeOfStorage": 16,
+ "operationalState": "enabled"
+ }
+ }
+ ]
+ }
+ }
+
+
+
+Query Compute Resource Reservation
+""""""""""""""""""""""""""""""""""
+
+Request to find out about reserved compute resources that the consumer has
+access to.
+
+.. http:get:: /reservation/compute/query
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ GET /reservation/compute/query HTTP/1.1
+ Accept: application/json
+
+ {
+ "queryReservationFilter": [
+ {
+ "reservationId": "xxxx-yyyy-zzzz"
+ }
+ ]
+
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "queryResult":
+ {
+ "startTime": "2015-09-21T01:00:00Z",
+ "reservationStatus": "active",
+ "reservationId": "xxxx-yyyy-zzzz",
+ "computePoolReserved":
+ {
+ "numCpuCores": 20,
+ "numVcInstances": 5,
+ "virtualMemSize": 10,
+ "zoneId": "23456"
+ }
+ }
+ }
+
+ :statuscode 404: reservation id unknown
+
+Update Compute Resource Reservation
+"""""""""""""""""""""""""""""""""""
+
+Request to update compute resource reservation
+
+.. http:post:: /reservation/compute/update
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /reservation/compute/update HTTP/1.1
+ Accept: application/json
+
+ {
+ "startTime": "2015-09-14T16:00:00Z",
+ "reservationId": "xxxx-yyyy-zzzz"
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "reservationData": {
+ "startTime": "2015-09-14TT16:00:00Z",
+ "reservationStatus": "active",
+ "reservationId": "xxxx-yyyy-zzzz",
+ "computePoolReserved": {
+ "numCpuCores": 20,
+ "numVcInstances": 5,
+ "virtualMemSize": 10,
+ "zoneId": "23456"
+ }
+ }
+ }
+
+Terminate Compute Resource Reservation
+""""""""""""""""""""""""""""""""""""""
+
+Request to terminate a compute resource reservation
+
+.. http:delete:: /reservation/compute/(reservation_id)
+ :noindex:
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200
+ Content-Type: application/json
+
+ {
+ "reservationId": "xxxx-yyyy-zzzz",
+ }
+
+
+Subscribe Resource Reservation Change Event
+"""""""""""""""""""""""""""""""""""""""""""
+
+Subscription from Consumer to VIM to be notified about changes
+related to a reservation or to the resources associated to it.
+
+.. http:post:: /reservation/subscribe
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /reservation/subscribe HTTP/1.1
+ Accept: application/json
+
+ {
+ "inputFilter": [
+ {
+ "reservationId": "xxxx-yyyy-zzzz",
+ }
+ ]
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "created": "2015-09-21T00:00:00Z",
+ "reservationChangeSubscriptionId": "abcdef-ghijkl-123456789"
+ }
+
+ :statuscode 400: inputFilter is missing
+
+
+Notify Resource Reservation Change Event
+""""""""""""""""""""""""""""""""""""""""
+
+Notification about changes in a compute resource reservation
+
+.. http:post:: /capacity/compute/notification
+ :noindex:
+
+ **Example notification**:
+
+ .. sourcecode:: http
+
+ Content-Type: application/json
+
+ {
+ "changeId": "aaaaaa-btgxxx-987654321",
+ "reservationId": "xxxx-yyyy-zzzz",
+ "vimId": "vim-CX-03"
+ "changeType": "Reservation time change"
+ "changedReservationData": {
+ "endTime": "2015-10-14TT16:00:00Z",
+ }
+ }
+
+
+
+Virtualised Network Resources
+-----------------------------
+
+Network Capacity Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Subscribe Network Capacity Change Event
+"""""""""""""""""""""""""""""""""""""""
+
+Susbcription from Consumer to VIM to be notified about network capacity changes
+
+.. http:post:: /capacity/network/subscribe
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /capacity/network/subscribe HTTP/1.1
+ Accept: application/json
+
+ {
+ "networkResourceTypeId": "publicIps",
+ "threshold": {
+ "thresholdType": "absoluteValue",
+ "threshold": {
+ "capacity_info": "available",
+ "condition": "lt",
+ "value": 5
+ }
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "created": "2015-09-28T00:00:00Z",
+ "capacityChangeSubscriptionId": "bcdefg-hijklm-234567890"
+ }
+
+Query Network Capacity
+""""""""""""""""""""""
+
+Request to find out about available, reserved, total and allocated network
+capacity.
+
+.. http:get:: /capacity/network/query
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ GET /capacity/network/query HTTP/1.1
+ Accept: application/json
+
+ {
+ "networkResourceTypeId": "publicIps",
+ "timePeriod": {
+ "startTime": "2015-09-28T00:00:00Z",
+ "stopTime": "2015-09-28T00:05:30Z"
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "lastUpdate": "2015-09-28T00:02:10Z",
+ "capacityInformation": {
+ "available": 4,
+ "reserved": 10,
+ "total": 64,
+ "allocated": 50
+ }
+ }
+
+Notify Network Capacity Change Event
+""""""""""""""""""""""""""""""""""""
+
+Notification about network capacity changes
+
+.. http:post:: /capacity/network/notification
+ :noindex:
+
+ **Example notification**:
+
+ .. sourcecode:: http
+
+ Content-Type: application/json
+
+ {
+ "notificationId": "yxwvut-srqpon-876543210",
+ "capacityChangeTime": "2015-09-28T00:02:10Z",
+ "resourceDescriptor": {
+ "networkResourceTypeId": "publicIps"
+ },
+ "capacityInformation": {
+ "available": 4,
+ "reserved": 10,
+ "total": 64,
+ "allocated": 50
+ }
+ }
+
+Network Resource Reservation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create Network Resource Reservation
+"""""""""""""""""""""""""""""""""""
+
+Request the reservation of network resource capacity and/or virtual networks,
+network ports
+
+.. http:post:: /reservation/network/create
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /reservation/network/create HTTP/1.1
+ Accept: application/json
+
+ {
+ "startTime": "2015-09-28T01:00:00Z",
+ "networkReservation": {
+ "numPublicIps": 2
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "reservationData": {
+ "startTime": "2015-09-28T01:00:00Z",
+ "reservationStatus": "initialized",
+ "reservationId": "wwww-xxxx-yyyy",
+ "publicIps": [
+ "10.2.91.60",
+ "10.2.91.61"
+ ]
+ }
+ }
+
+Query Network Resource Reservation
+""""""""""""""""""""""""""""""""""
+
+Request to find out about reserved network resources that the consumer has
+access to.
+
+.. http:get:: /reservation/network/query
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ GET /reservation/network/query HTTP/1.1
+ Accept: application/json
+
+ {
+ "queryReservationFilter": [
+ {
+ "reservationId": "wwww-xxxx-yyyy"
+ }
+ ]
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "queryResult": {
+ "startTime": "2015-09-28T01:00:00Z",
+ "reservationStatus": "active",
+ "reservationId": "wwww-xxxx-yyyy",
+ "publicIps": [
+ "10.2.91.60",
+ "10.2.91.61"
+ ]
+ }
+ }
+
+Update Network Resource Reservation
+"""""""""""""""""""""""""""""""""""
+
+Request to update network resource reservation
+
+.. http:post:: /reservation/network/update
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /reservation/network/update HTTP/1.1
+ Accept: application/json
+
+ {
+ "startTime": "2015-09-21T16:00:00Z",
+ "reservationId": "wwww-xxxx-yyyy"
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "reservationData": {
+ "startTime": "2015-09-21T16:00:00Z",
+ "reservationStatus": "active",
+ "reservationId": "wwww-xxxx-yyyy",
+ "publicIps": [
+ "10.2.91.60",
+ "10.2.91.61"
+ ]
+ }
+ }
+
+Terminate Network Resource Reservation
+""""""""""""""""""""""""""""""""""""""
+
+Request to terminate a network resource reservation
+
+.. http:delete:: /reservation/network/(reservation_id)
+ :noindex:
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200
+ Content-Type: application/json
+
+ {
+ "reservationId": "xxxx-yyyy-zzzz",
+ }
+
+Virtualised Storage Resources
+-----------------------------
+
+Storage Capacity Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Subscribe Storage Capacity Change Event
+"""""""""""""""""""""""""""""""""""""""
+
+Subscription from Consumer to VIM to be notified about storage capacity changes
+
+.. http:post:: /capacity/storage/subscribe
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /capacity/storage/subscribe HTTP/1.1
+ Accept: application/json
+
+ {
+ "storageResourceTypeId": "volumes",
+ "threshold": {
+ "thresholdType": "absoluteValue",
+ "threshold": {
+ "capacity_info": "available",
+ "condition": "lt",
+ "value": 3
+ }
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "created": "2015-09-28T12:00:00Z",
+ "capacityChangeSubscriptionId": "cdefgh-ijklmn-345678901"
+ }
+
+Query Storage Capacity for a defined resource type
+""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Request to find out about available, reserved, total and allocated storage
+capacity.
+
+.. http:get:: /capacity/storage/query
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ GET /capacity/storage/query HTTP/1.1
+ Accept: application/json
+
+ {
+ "storageResourceTypeId": "volumes",
+ "timePeriod": {
+ "startTime": "2015-09-28T12:00:00Z",
+ "stopTime": "2015-09-28T12:04:45Z"
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "lastUpdate": "2015-09-28T12:01:35Z",
+ "capacityInformation": {
+ "available": 2,
+ "reserved": 4,
+ "total": 10,
+ "allocated": 4
+ }
+ }
+
+Query Storage Capacity with required attributes
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+Request to find out available capacity.
+
+.. http:get:: /capacity/storage/query
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ GET /capacity/storage/query HTTP/1.1
+ Accept: application/json
+
+ {
+ "resourceCriteria": {
+ "typeOfStorage" : "volume",
+ "sizeOfStorage" : 200,
+ "rdmaSupported" : "True",
+ },
+ "attributeSelector": "available",
+ "timePeriod": {
+ "startTime": "2015-09-28T12:00:00Z",
+ "stopTime": "2015-09-28T12:04:45Z"
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "lastUpdate": "2015-09-28T12:01:35Z",
+ "capacityInformation": {
+ "available": 2
+ }
+ }
+
+Notify Storage Capacity Change Event
+""""""""""""""""""""""""""""""""""""
+
+Notification about storage capacity changes
+
+.. http:post:: /capacity/storage/notification
+ :noindex:
+
+ **Example notification**:
+
+ .. sourcecode:: http
+
+ Content-Type: application/json
+
+ {
+ "notificationId": "xwvuts-rqponm-765432109",
+ "capacityChangeTime": "2015-09-28T12:01:35Z",
+ "resourceDescriptor": {
+ "storageResourceTypeId": "volumes"
+ },
+ "capacityInformation": {
+ "available": 2,
+ "reserved": 4,
+ "total": 10,
+ "allocated": 4
+ }
+ }
+
+Storage Resource Reservation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create Storage Resource Reservation
+"""""""""""""""""""""""""""""""""""
+
+Request the reservation of storage resource capacity
+
+.. http:post:: /reservation/storage/create
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /reservation/storage/create HTTP/1.1
+ Accept: application/json
+
+ {
+ "startTime": "2015-09-28T13:00:00Z",
+ "storagePoolReservation": {
+ "storageSize": 10,
+ "numSnapshots": 3,
+ "numVolumes": 2
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "reservationData": {
+ "startTime": "2015-09-28T13:00:00Z",
+ "reservationStatus": "initialized",
+ "reservationId": "vvvv-wwww-xxxx",
+ "storagePoolReserved": {
+ "storageSize": 10,
+ "numSnapshots": 3,
+ "numVolumes": 2
+ }
+ }
+ }
+
+Query Storage Resource Reservation
+""""""""""""""""""""""""""""""""""
+
+Request to find out about reserved storage resources that the consumer has
+access to.
+
+.. http:get:: /reservation/storage/query
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ GET /reservation/storage/query HTTP/1.1
+ Accept: application/json
+
+ {
+ "queryReservationFilter": [
+ {
+ "reservationId": "vvvv-wwww-xxxx"
+ }
+ ]
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "queryResult": {
+ "startTime": "2015-09-28T13:00:00Z",
+ "reservationStatus": "active",
+ "reservationId": "vvvv-wwww-xxxx",
+ "storagePoolReserved": {
+ "storageSize": 10,
+ "numSnapshots": 3,
+ "numVolumes": 2
+ }
+ }
+ }
+
+Update Storage Resource Reservation
+"""""""""""""""""""""""""""""""""""
+
+Request to update storage resource reservation
+
+.. http:post:: /reservation/storage/update
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /reservation/storage/update HTTP/1.1
+ Accept: application/json
+
+
+ {
+ "startTime": "2015-09-20T23:00:00Z",
+ "reservationId": "vvvv-wwww-xxxx"
+
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "reservationData": {
+ "startTime": "2015-09-20T23:00:00Z",
+ "reservationStatus": "active",
+ "reservationId": "vvvv-wwww-xxxx",
+ "storagePoolReserved": {
+ "storageSize": 10,
+ "numSnapshots": 3,
+ "numVolumes": 2
+ }
+ }
+ }
+
+Terminate Storage Resource Reservation
+""""""""""""""""""""""""""""""""""""""
+
+Request to terminate a storage resource reservation
+
+.. http:delete:: /reservation/storage/(reservation_id)
+ :noindex:
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200
+ Content-Type: application/json
+
+ {
+ "reservationId": "xxxx-yyyy-zzzz",
+ }
diff --git a/docs/development/requirements/annex1.rst b/docs/development/requirements/annex1.rst
new file mode 100644
index 0000000..65a5f22
--- /dev/null
+++ b/docs/development/requirements/annex1.rst
@@ -0,0 +1,37 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _uc-brahmaputra:
+
+ANNEX A: Use case for OPNFV Brahmaputra
+=======================================
+
+A basic resource reservation use case to be realized for OPNFV B-release may
+look as follows:
+
+* Step 0: Shim-layer is monitoring/querying available capacity at NFVI
+
+ * Step 0a: Cloud operator creates a new OpenStack tenant user and updates
+ quota values for this user
+
+ * Step 0b: The tenant user is creating and instantiating a simple VNF
+ (e.g. 1 network, 2 VMs)
+
+ * Step 0c: OpenStack is notifying shim-layer about capacity change for
+ this new tenant user
+
+ * Step 0d: Cloud operator can visualize the changes using the GUI
+
+* Step 1: Consumer(NFVO) is sending a reservation request for future use to
+ shim-layer
+
+* Step 2: Shim-layer is checking for available capacity at the given time
+ window
+
+* Step 3: Shim-layer is responding with reservation identifier
+
+* Step 4 (optional): Consumer(NFVO) is sending an update reservation request
+ to shim-layer (startTime set to now) -> continue with Steps 2 and 3.
+
+* Step 5: Consumer(VNFM) is requesting the allocation of virtualised resources
+ using the reservation identifier in Step 3
diff --git a/docs/development/requirements/architecture.rst b/docs/development/requirements/architecture.rst
new file mode 100644
index 0000000..3eb20d3
--- /dev/null
+++ b/docs/development/requirements/architecture.rst
@@ -0,0 +1,258 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+============================================
+High level architecture and general features
+============================================
+
+Architecture Overview
+=====================
+
+.. figure:: images/figure1.png
+ :name: figure1
+ :width: 90%
+
+ Resource Reservation Architecture
+
+:numref:`figure1` shows the high level architecture for the resource reservation
+use cases. Reserved resources are guaranteed for a given user/client for the
+period expressed by start and end time. User/client represents the requestor
+and the consequent consumer of the reserved resources and correspond to the
+NFVO or VNFM in ETSI NFV terminology.
+
+Note: in this document only reservation requests from NFVO are considered.
+
+General Features
+================
+
+This section provides a list of features that need to be developed in the
+Promise project.
+
+* Resource capacity management
+
+ * Discovery of available resource capacity in resource providers
+ * Monitoring of available resource capacity in resource providers
+ * Update available resource capacity as a result of new or expired
+ reservations, addition/removal of resources. Note: this is a VIM internal
+ function, not an operation in the VIM northbound interface.
+
+* Resource reservation
+
+ * Set start time and end time for allocation
+ * Increase/decrease reserved resource's capacity
+ * Update resource reservations, e.g. add/remove reserved resources
+ * Terminate an allocated resource due to the end time of a reservation
+
+* VIM northbound interfaces
+
+ * Receive/Reply resource reservation requests
+ * Receive/Reply resource capacity management requests
+ * Receive/Reply resource allocation requests for reserved resources when
+ start time arrives
+ * Subscribe/Notify resource reservation event
+
+ * Notify reservation error or process completion prior to reservation
+ start
+ * Notify remaining time until termination of a resource due to the end
+ time of a reservation
+ * Notify termination of a resource due to the end time of a reservation
+
+ * Receive/Reply queries on available resource capacity
+ * Subscribe/Notify changes in available resource capacity
+
+High level northbound interface specification
+=============================================
+
+Resource Capacity Management
+----------------------------
+
+.. figure:: images/figure2.png
+ :name: figure2
+ :width: 90%
+
+ Resource capacity management message flow: notification of capacity change
+
+:numref:`figure2` shows a high level flow for a use case of resource capacity
+management. In this example, the VIM notifies the NFVO of capacity change after
+having received an event regarding a change in capacity (e.g. a fault
+notification) from the NFVI. The NFVO can also retrieve detailed capacity
+information using the Query Capacity Request interface operation.
+
+.. figure:: images/figure3.png
+ :name: figure3
+ :width: 90%
+
+ Resource capacity management message flow: query of capacity density
+
+:numref:`figure3` shows a high level flow for another use case of resource
+capacity management. In this example, the NFVO queries the VIM about the actual
+capacity to instantiate a certain resource according to a certain template, for
+example a VM according to a certain flavor. In this case the VIM responds with
+the number of VMs that could be instantiated according to that flavor with the
+currently available capacity.
+
+Resource Reservation
+--------------------
+
+.. figure:: images/figure4.png
+ :name: figure4
+ :width: 90%
+
+ Resource reservation flow
+
+:numref:`figure4` shows a high level flow for a use case of resource
+reservation. The main steps are:
+
+* The NFVO sends a resource reservation request to the VIM using the Create
+ Resource Reservation Request interface operation.
+* The NFVO gets a reservation identifier reservation associated with this
+ request in the reply message
+* Using the reservation identifier reservation, the NFVO can
+ query/update/terminate a resource reservation using the corresponding
+ interface operations
+* The NFVO is notified that the resource reservation is terminated due to the
+ end time of the reservation
+
+
+Information elements
+====================
+
+Resource Capacity Management
+----------------------------
+
+Notify Capacity Change Event
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The notification change message shall include the following information elements:
+
+============================ ========== =====================================
+Name Type Description
+============================ ========== =====================================
+Notification Identifier Identifier issued by the VIM for the
+ capacity change event notification
+Zone Identifier Identifier of the zone where capacity
+ has changed
+Used/Reserved/Total Capacity List Used, reserved and total capacity
+ information regarding the resource
+ items subscribed for notification for
+ which capacity change event occurred
+============================ ========== =====================================
+
+Query Resource Capacity Request
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The capacity management query request message shall include the following
+information elements:
+
+========== ========== ======================================================
+Name Type Description
+========== ========== ======================================================
+Zone Identifier Identifier of the zone where capacity is requested
+Attributes List Attributes of resource items to be notified regarding
+ capacity change events
+Resources List Identifiers of existing resource items to be queried
+ regarding capacity info (such as images, flavors,
+ virtual containers, networks, physical machines, etc.)
+========== ========== ======================================================
+
+The capacity management query request message may also include the following
+information element:
+
+====== ========== ==========================================================
+Name Type Description
+====== ========== ==========================================================
+Flavor Identifier Identifier that is passed in the request to obtain
+ information of the number of virtual resources that can be
+ instantiated according to this flavor with the available
+ capacity
+====== ========== ==========================================================
+
+Query Resource Capacity Reply
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The capacity management query reply message shall include the following
+information elements:
+
+============================ ========== =====================================
+Name Type Description
+============================ ========== =====================================
+Zone Identifier Identifier of the zone where capacity
+ is requested
+Used/Reserved/Total Capacity List Used, reserved and total capacity
+ information regarding each of the
+ resource items requested to check for
+ capacity
+============================ ========== =====================================
+
+The detailed specification of the northbound interface for Capacity Management
+in provided in section 5.1.1.
+
+Resource Reservation
+--------------------
+
+Create Resource Reservation Request
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The create resource reservation request message shall include the following
+information elements:
+
+========== ========== =========================================================
+Name Type Description
+========== ========== =========================================================
+Start Timestamp Start time for consumption of the reserved resources
+End Timestamp End time for consumption of the reserved resources
+Expiry Timestamp If not all reserved resources are allocated between start
+ time and expiry, the VIM shall release the corresponding
+ resources [#expiry]_
+Amount Number Amount of the resources per resource item type (i.e.
+ compute/network/storage) that need to be reserved
+Zone Identifier The zone where the resources need(s) to be reserved
+Attributes List Attributes of the resources to be reserved such as DPDK
+ support, hypervisor, network link bandwidth, affinity
+ rules, etc.
+Resources List Identifiers of existing resource items to be reserved
+ (such as images, flavors, virtual containers, networks,
+ physical machines, etc.)
+========== ========== =========================================================
+
+.. [#expiry] Expiry is a period around start time within which, the allocation
+ process must take place. If allocation process does not start
+ within the expiry period, the reservation becomes invalid and VIM
+ should release the resources
+
+Create Resource Reservation Reply
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The create resource reservation reply message shall include the following
+information elements:
+
+=========== ========== =======================================================
+Name Type Description
+=========== ========== =======================================================
+Reservation Identifier Identification of the reservation instance. It can be
+ used by a consumer to modify the reservation later, and
+ to request the allocation of the reserved resources.
+Message Text Output message that provides additional information
+ about the create resource reservation request (e.g. may
+ be a simple ACK if the request is being background
+ processed by the VIM)
+=========== ========== =======================================================
+
+Notify Reservation Event
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The notification reservation event message shall include the following
+information elements:
+
+============ ========== =====================================================
+Name Type Description
+============ ========== =====================================================
+Reservation Identifier Identification of the reservation instance triggering
+ the event
+Notification Identifier Identification of the resource event notification
+ issued by the VIM
+Message Text Message describing the event
+============ ========== =====================================================
+
+The detailed specification of the northbound interface for Resource Reservation
+is provided in section 5.1.2.
diff --git a/docs/development/requirements/gap_analysis.rst b/docs/development/requirements/gap_analysis.rst
new file mode 100644
index 0000000..9e4ec5c
--- /dev/null
+++ b/docs/development/requirements/gap_analysis.rst
@@ -0,0 +1,99 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+=================================
+Gap analysis in upstream projects
+=================================
+
+This section provides a list of gaps in upstream projects for realizing
+resource reservation and management. The gap analysis work focuses on the
+current OpenStack Blazar project [BLAZAR]_ in this first release.
+
+OpenStack
+=========
+
+Resource reservation for future use
+-----------------------------------
+
+* Category: Blazar
+* Type: 'missing' (lack of functionality)
+* Description:
+
+ * To-be: To reserve a whole set of compute/storage/network resources in the
+ future
+ * As-is: Blazar currently can do only compute resource reservation by using
+ "Shelved VM"
+
+* Related blueprints:
+
+ * https://blueprints.launchpad.net/blazar/+spec/basic-volume-plugin
+ * https://blueprints.launchpad.net/blazar/+spec/basic-network-plugin
+ * It was planned in Blazar to implement volume and network/fixed ip
+ reservations
+
+Resource reservation update
+---------------------------
+
+* Category: Blazar
+* Type: 'missing' (lack of functionality)
+* Description:
+
+ * To-be: Have the possibility of adding/removing resources to an existing
+ reservation, e..g in case of NFVI failure
+ * As-is: Currently in Blazar, a reservation can only be modified in terms of
+ start/end time
+
+* Related blueprints: N/A
+
+Give me an offer
+----------------
+
+* Category: Blazar
+* Type: 'missing' (lack of functionality)
+* Description:
+
+ * To-be: To have the possibility of giving a quotation to a requesting user
+ and an expiration time. Reserved resources shall be released if they are
+ not claimed before this expiration time.
+ * As-is: Blazar can already send notification e.g. to inform a given user
+ that a reservation is about to expire
+
+* Related blueprints: N/A
+
+StormStack StormForge
+---------------------
+
+Stormify
+^^^^^^^^
+* Stormify enables rapid web applications construction
+* Based on Ember.js style Data stores
+* Developed on Node.js using coffeescript/javascript
+* Auto RESTful API generation based on Data Models
+* Development starts with defining Data Models
+* Code hosted at github : http://github.com/stormstack/stormify
+
+StormForge
+^^^^^^^^^^
+* Data Model driven management of Resource Providers
+* Based on Stormify Framework and implemented as per the OPNFV Promise
+ requirements
+* Data Models are auto generated and RESTful API code from YANG schema
+* Currently planned key services include Resource Capacity Management Service
+ and Resource Reservation Service
+* List of YANG schemas for Promise project is attached in the Appendix
+* Code hosted at github: http://github.com/stormstack/stormforge
+
+Resource Discovery
+^^^^^^^^^^^^^^^^^^
+* Category: StormForge
+* Type: 'planning' (lack of functionality)
+* Description
+
+ * To-be: To be able to discover resources in real time from OpenStack
+ components. Planning to add OpenStack Project to interface with Promise for
+ real time updates on capacity or any failures
+ * As-is: Currently, resource capacity is learnt using NB APIs related to
+ quota
+
+* Related Blueprints: N/A
+
diff --git a/docs/development/requirements/glossary.rst b/docs/development/requirements/glossary.rst
new file mode 100644
index 0000000..48fd75b
--- /dev/null
+++ b/docs/development/requirements/glossary.rst
@@ -0,0 +1,73 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+===================
+Definition of terms
+===================
+
+Different SDOs and communities use different terminology related to
+NFV/Cloud/SDN. This list tries to define an OPNFV terminology,
+mapping/translating the OPNFV terms to terminology used in other contexts.
+
+.. glossary::
+
+ Administrator
+ Administrator of the system, e.g. OAM in Telco context.
+
+ Consumer
+ User-side Manager; consumer of the interfaces produced by the VIM; VNFM,
+ NFVO, or Orchestrator in ETSI NFV [NFV003]_ terminology.
+
+ NFV
+ Network Function Virtualization
+
+ NFVI
+ Network Function Virtualization Infrastructure; totality of all hardware
+ and software components which build up the environment in which VNFs are
+ deployed.
+
+ NFVO
+ Network Functions Virtualization Orchestrator; functional block that
+ manages the Network Service (NS) lifecycle and coordinates the management
+ of NS lifecycle, VNF lifecycle (supported by the VNFM) and NFVI resources
+ (supported by the VIM) to ensure an optimized allocation of the necessary
+ resources and connectivity.
+
+ Physical resource
+ Actual resources in NFVI; not visible to Consumer.
+
+ Resource zone
+ A set of NFVI hardware and software resources logically grouped
+ according to physical isolation and redundancy capabilities or to
+ certain administrative policies for the NFVI [NFVIFA010]_
+
+ VIM
+ Virtualized Infrastructure Manager; functional block that is responsible
+ for controlling and managing the NFVI compute, storage and network
+ resources, usually within one operator's Infrastructure Domain, e.g. NFVI
+ Point of Presence (NFVI-PoP).
+
+ Virtual Machine (VM)
+ Virtualized computation environment that behaves very much like a physical
+ computer/server.
+
+ Virtual network
+ Virtual network routes information among the network interfaces of VM
+ instances and physical network interfaces, providing the necessary
+ connectivity.
+
+ Virtual resource
+ A Virtual Machine (VM), a virtual network, or virtualized storage; Offered
+ resources to "Consumer" as result of infrastructure virtualization;
+ visible to Consumer.
+
+ Virtual Storage
+ Virtualized non-volatile storage allocated to a VM.
+
+ VNF
+ Virtualized Network Function. Implementation of an Network Function that
+ can be deployed on a Network Function Virtualization Infrastructure (NFVI).
+
+ VNFM
+ Virtualized Network Function Manager; functional block that is responsible
+ for the lifecycle management of VNF.
diff --git a/docs/development/requirements/images/LICENSE b/docs/development/requirements/images/LICENSE
new file mode 100644
index 0000000..3b8719c
--- /dev/null
+++ b/docs/development/requirements/images/LICENSE
@@ -0,0 +1,14 @@
+Copyright 2015 Open Platform for NFV Project, Inc. and its contributors
+
+Open Platform for NFV Project Documentation Licence
+===================================================
+Any documentation developed by the "Open Platform for NFV Project"
+is licensed under a Creative Commons Attribution 4.0 International License.
+You should have received a copy of the license along with this. If not,
+see <http://creativecommons.org/licenses/by/4.0/>.
+
+Unless required by applicable law or agreed to in writing, documentation
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/docs/development/requirements/images/computeflavor.png b/docs/development/requirements/images/computeflavor.png
new file mode 100755
index 0000000..3ea3dba
Binary files /dev/null and b/docs/development/requirements/images/computeflavor.png differ
diff --git a/docs/development/requirements/images/figure1.png b/docs/development/requirements/images/figure1.png
new file mode 100644
index 0000000..065a995
Binary files /dev/null and b/docs/development/requirements/images/figure1.png differ
diff --git a/docs/development/requirements/images/figure2.png b/docs/development/requirements/images/figure2.png
new file mode 100755
index 0000000..dd002a2
Binary files /dev/null and b/docs/development/requirements/images/figure2.png differ
diff --git a/docs/development/requirements/images/figure3.png b/docs/development/requirements/images/figure3.png
new file mode 100755
index 0000000..20e51c7
Binary files /dev/null and b/docs/development/requirements/images/figure3.png differ
diff --git a/docs/development/requirements/images/figure4.png b/docs/development/requirements/images/figure4.png
new file mode 100755
index 0000000..e0c96a1
Binary files /dev/null and b/docs/development/requirements/images/figure4.png differ
diff --git a/docs/development/requirements/images/figure5.png b/docs/development/requirements/images/figure5.png
new file mode 100755
index 0000000..4e161f4
Binary files /dev/null and b/docs/development/requirements/images/figure5.png differ
diff --git a/docs/development/requirements/images/figure5_new.png b/docs/development/requirements/images/figure5_new.png
new file mode 100644
index 0000000..9307aa2
Binary files /dev/null and b/docs/development/requirements/images/figure5_new.png differ
diff --git a/docs/development/requirements/images/figure6.png b/docs/development/requirements/images/figure6.png
new file mode 100755
index 0000000..8aeec23
Binary files /dev/null and b/docs/development/requirements/images/figure6.png differ
diff --git a/docs/development/requirements/images/figure6_new.png b/docs/development/requirements/images/figure6_new.png
new file mode 100644
index 0000000..5ec4b43
Binary files /dev/null and b/docs/development/requirements/images/figure6_new.png differ
diff --git a/docs/development/requirements/images/figure7_new.png b/docs/development/requirements/images/figure7_new.png
new file mode 100644
index 0000000..6684949
Binary files /dev/null and b/docs/development/requirements/images/figure7_new.png differ
diff --git a/docs/development/requirements/impl_architecture.rst b/docs/development/requirements/impl_architecture.rst
new file mode 100644
index 0000000..d7375d5
--- /dev/null
+++ b/docs/development/requirements/impl_architecture.rst
@@ -0,0 +1,313 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Detailed architecture and message flows
+=======================================
+
+Within the Promise project we consider two different architectural options, i.e.
+a *shim-layer* based architecture and an architecture targeting at full
+OpenStack *integration*.
+
+Shim-layer architecture
+-----------------------
+
+The *shim-layer architecture* is using a layer on top of OpenStack to provide
+the capacity management, resource reservation, and resource allocation features.
+
+
+Detailed Message Flows
+^^^^^^^^^^^^^^^^^^^^^^
+
+Note, that only selected parameters for the messages are shown. Refer to
+:ref:`northbound_API` and Annex :ref:`yang_schema` for a full set of message
+parameters.
+
+Resource Capacity Management
+""""""""""""""""""""""""""""
+
+.. figure:: images/figure5_new.png
+ :name: figure5
+ :width: 90%
+
+ Capacity Management Scenario
+
+:numref:`figure5` shows a detailed message flow between the consumers and the
+capacity management functional blocks inside the shim-layer. It has the
+following steps:
+
+ * Step 1a: The Consumer sends a *query-capacity* request to Promise
+ using some filter like time-windows or resource type. The capacity is
+ looked up in the shim-layer capacity map.
+
+ * Step 1b: The shim-layer will respond with information about the
+ total, available, reserved, and used (allocated) capacities matching the
+ filter.
+
+ * Step 2a: The Consumer can send *increase/decrease-capacity* requests
+ to update the capacity available to the reservation system. It can be
+ 100% of available capacity in the given provider/source or only a subset,
+ i.e., it can allow for leaving some "buffer" in the actual NFVI to be
+ used outside the Promise shim-layer or for a different reservation
+ service instance. It can also be used to inform the reservation system
+ that from a certain time in the future, additional resources can be
+ reserved (e.g. due to a planned upgrade of the capacity), or the
+ available capacity will be reduced (e.g. due to a planned downtime of
+ some of the resources).
+
+ * Step 2b: The shim-layer will respond with an ACK/NACK message.
+
+ * Step 3a: Consumers can subscribe for capacity-change events using a
+ filter.
+
+ * Step 3b: Each successful subscription is responded with a
+ subscription_id.
+
+ * Step 4: The shim-layer monitors the capacity information for the
+ various types of resources by periodically querying the various
+ Controllers (e.g. Nova, Neutron, Cinder) or by creating event alarms in
+ the VIM (e.g. with Ceilometer for OpenStack) and updates capacity
+ information in its capacity map.
+
+ * Step 5: Capacity changes are notified to the Consumer.
+
+Resource Reservation
+""""""""""""""""""""
+
+.. figure:: images/figure6_new.png
+ :name: figure6
+ :width: 90%
+
+ Resource Reservation for Future Use Scenario
+
+:numref:`figure6` shows a detailed message flow between the Consumer and the
+resource reservation functional blocks inside the shim-layer. It has the
+following steps:
+
+ * Step 1a: The Consumer creates a resource reservation request for
+ future use by setting a start and end time for the reservation as well as
+ more detailed information about the resources to be reserved. The Promise
+ shim-layer will check the free capacity in the given time window and in
+ case sufficient capacity exists to meet the reservation request, will
+ mark those resources "reserved" in its reservation map.
+
+ * Step 1b: If the reservation was successful, a reservation_id and
+ status of the reservation will be returned to the Consumer. In case the
+ reservation cannot be met, the shim-layer may return information about
+ the maximum capacity that could be reserved during the requested time
+ window and/or a potential time window where the requested (amount of)
+ resources would be available.
+
+ * Step 2a: Reservations can be updated using an *update-reservation*,
+ providing the reservation_id and the new reservation_data. Promise
+ Reservation Manageer will check the feasibility to update the reservation
+ as requested.
+
+ * Step 2b: If the reservation was updated successfully, a
+ reservation_id and status of the reservation will be returned to the
+ Consumer. Otherwise, an appropriate error message will be returned.
+
+ * Step 3a: A *cancel-reservation* request can be used to withdraw an
+ existing reservation. Promise will update the reservation map by removing
+ the reservation as well as the capacity map by adding the freed capacity.
+
+ * Step 3b: The response message confirms the cancelation.
+
+ * Step 4a: Consumers can also issue *query-reservation* requests to
+ receive a list of reservation. An input filter can be used to narrow down
+ the query, e.g., only provide reservations in a given time window.
+ Promise will query its reservation map to identify reservations matching
+ the input filter.
+
+ * Step 4b: The response message contains information about all
+ reservations matching the input filter. It also provides information
+ about the utilization in the requested time window.
+
+ * Step 5a: Consumers can subscribe for reservation-change events using
+ a filter.
+
+ * Step 5b: Each successful subscription is responded with a
+ subscription_id.
+
+ * Step 6a: Promise synchronizes the available and used capacity with
+ the underlying VIM.
+
+ * Step 6b: In certain cases, e.g., due a failure in the underlying
+ hardware, some reservations cannot be kept up anymore and have to be
+ updated or canceled. The shim-layer will identify affected reservations
+ among its reservation records.
+
+ * Step 7: Subscribed Consumers will be informed about the updated
+ reservations. The notification contains the updated reservation_data and
+ new status of the reservation. It is then up to the Consumer to take
+ appropriate actions in order to ensure high priority reservations are
+ favored over lower priority reservations.
+
+Resource Allocation
+"""""""""""""""""""
+
+.. figure:: images/figure7_new.png
+ :name: figure7
+ :width: 90%
+
+ Resource Allocation
+
+:numref:`figure7` shows a detailed message flow between the Consumer, the
+functional blocks inside the shim-layer, and the VIM. It has the following
+steps:
+
+ * Step 1a: The Consumer sends a *create-instance* request providing
+ information about the resources to be reserved, i.e., provider_id
+ (optional in case of only one provider), name of the instance, the
+ requested flavour and image, etc. If the allocation is against an
+ existing reservation, the reservation_id has to be provided.
+
+ * Step 1b: If a reservation_id was provided, Promise checks if a
+ reservation with that ID exists, the reservation start time has arrived
+ (i.e. the reservation is active), and the required capacity for the
+ requested flavor is within the available capacity of the reservation. If
+ those conditions are met, Promise creates a record for the allocation
+ (VMState="INITIALIZED") and update its databases. If no reservation_id
+ was provided in the allocation request, Promise checks whether the
+ required capacity to meet the request can be provided from the available,
+ non-reserved capacity. If yes, Promise creates a record for the
+ allocation and update its databases. In any other case, Promise rejects
+ the *create-instance* request.
+
+ * Step 2: In the case the *create-instance* request was rejected,
+ Promise responds with a "status=rejected" providing the reason of the
+ rejection. This will help the Consumer to take appropriate actions, e.g.,
+ send an updated *create-instance* request. The allocation work flow will
+ terminate at this step and the below steps are not executed.
+
+ * Step 3a: If the *create-instance* request was accepted and a related
+ allocation record has been created, the shim-layer issues a
+ *createServer* request to the VIM Controller providing all information to
+ create the server instance.
+
+ * Step 3b: The VIM Controller sends an immediate reply with an
+ instance_id and starts the VIM-internal allocation process.
+
+ * Step 4: The Consumer gets an immediate response message with
+ allocation status "in progress" and the assigned instance_id.
+
+ * Step 5a+b: The consumer subscribes to receive notifications about
+ allocation events related to the requested instance. Promise responds
+ with an acknowledgment including a subscribe_id.
+
+ * Step 6: In parallel to the previous step, Promise shim-layer creates
+ an alarm in Aodh to receive notifications about all changes to the
+ VMState for instance_id.
+
+ * Step 7a: The VIM Controller notifies all instance related events to
+ Ceilometer. After the allocation has been completed or failed, it sends
+ an event to Ceilometer. This triggers the OpenStack alarming service Aodh
+ to notify the new VMState (e.g. ACTIVE and ERROR) to the shim-layer that
+ updates its internal allocation records.
+
+ * Step 7b: Promise sends a notification message to the subscribed
+ Consumer with information on the allocated resources including their new
+ VMState.
+
+ * Step 8a+b: Allocated instances can be terminated by the Consumer by
+ sending a *destroy-instance* request to the shim-layer. Promise responds
+ with an acknowledgment and the new status "DELETING" for the instance.
+
+ * Step 9a: Promise sends a *deleteServer* request for the instance_id
+ to the VIM Controller.
+
+ * Step 10a: After the instance has been deleted, an event alarm is
+ sent to the shim-layer that updates its internal allocation records and
+ capacity utilization.
+
+ * Step 10b: The shim-layer also notifies the subscribed Consumer about
+ the successfully destroyed instance.
+
+
+Internal operations
+^^^^^^^^^^^^^^^^^^^
+
+.. note:: This section is to be updated
+
+In the following, the internal logic and operations of the shim-layer will be
+explained in more detail, e.g. the "check request" (step 1b in
+:numref:`figure7` of the allocation work flow).
+
+
+
+Integrated architecture
+-----------------------
+
+The *integrated architecture* aims at full integration with OpenStack.
+This means that it is planned to use the already existing OpenStack APIs
+extended with the reservation capabilities.
+
+The advantage of this approach is that we don't need to re-model the
+complex resource structure we have for the virtual machines and the
+corresponding infrastructure.
+
+The atomic item is the virtual machine with the minimum set of resources
+it requires to be able to start it up. It is important to state that
+resource reservation is handled on VM instance level as opposed to standalone
+resources like CPU, memory and so forth. As the placement is an important
+aspect in order to be able to use the reserved resources it provides the
+constraint to handle resources in groups.
+
+The placement constraint also makes it impossible to use a quota management
+system to solve the base use case described earlier in this document.
+
+OpenStack had a project called Blazar, which was created in order to provide
+resource reservation functionality in cloud environments. It uses the Shelve
+API of Nova, which provides a sub-optimal solution. Due to the fact that this
+feature blocks the reserved resources this solution cannot be considered to
+be final. Further work is needed to reach a more optimal stage, where the
+Nova scheduler is intended to be used to schedule the resources for future
+use to make the reservations.
+
+Phases of the work
+^^^^^^^^^^^^^^^^^^
+
+The work has two main stages to reach the final solution. The following main work items
+are on the roadmap for this approach:
+
+#. Sub-optimal solution by using the shelve API of Nova through the Blazar project:
+
+ * Fix the code base of the Blazar project:
+
+ Due to integration difficulties the Blazar project got suspended. Since the last
+ activities in that repository the OpenStack code base and environment changed
+ significantly, which means that the project's code base needs to be updated to the
+ latest standards and has to be able to interact with the latest version of the
+ other OpenStack services.
+
+ * Update the Blazar API:
+
+ The REST API needs to be extended to contain the attributes for the reservation
+ defined in this document. This activity shall include testing towards the new API.
+
+#. Use Nova scheduler to avoid blocking the reserved resources:
+
+ * Analyze the Nova scheduler:
+
+ The status and the possible interface between the resource reservation system and
+ the Nova scheduler needs to be identified. It is crucial to achieve a much more
+ optimal solution than what the current version of Blazar can provide. The goal is
+ to be able to use the reserved resources before the reservation starts. In order to
+ be able to achieve this we need the scheduler to do scheduling for the future
+ considering the reservation intervals that are specified in the request.
+
+ * Define a new design based on the analysis and start the work on it:
+
+ The design for the more optimal solution can be defined only after analyzing the
+ structure and capabilities of the Nova scheduler.
+
+ * This phase can be started in parallel with the previous one.
+
+Detailed Message Flows
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. note:: to be done
+
+Resource Reservation
+""""""""""""""""""""
+
+.. note:: to be specified
diff --git a/docs/development/requirements/index.rst b/docs/development/requirements/index.rst
new file mode 100644
index 0000000..00edf0e
--- /dev/null
+++ b/docs/development/requirements/index.rst
@@ -0,0 +1,52 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+****************************
+Promise: Resource Management
+****************************
+
+:Project: Promise, https://wiki.opnfv.org/promise
+:Editors: Ashiq Khan (NTT DOCOMO), Bertrand Souville (NTT DOCOMO)
+:Authors: Ravi Chunduru (ClearPath Networks), Peter Lee (ClearPath Networks),
+ Gerald Kunzmann (NTT DOCOMO), Ryota Mibu (NEC),
+ Carlos Goncalves (NEC), Arturo Martin De Nicolas (Ericsson)
+
+:History:
+ ========== =====================================================
+ Date Description
+ ========== =====================================================
+ 04.12.2014 Project creation
+ 20.04.2015 Initial version of the deliverable uploaded to gerrit
+ 19.06.2015 Stable version of the Promise deliverable
+ ========== =====================================================
+
+:Abstract: Promise is an OPNFV requirement project. Its objective is to realize
+ ETSI NFV defined resource reservation and NFVI capacity features
+ within the scope of OPNFV. Promise provides the details of the
+ requirements on resource reservation, NFVI capacity management at
+ VIM, specification of the northbound interfaces from VIM relevant to
+ these features, and implementation plan to realize these features in
+ OPNFV.
+
+.. raw:: latex
+
+ \newpage
+
+.. toctree::
+ :maxdepth: 4
+ :numbered:
+
+ glossary.rst
+ intro.rst
+ usecase.rst
+ architecture.rst
+ gap_analysis.rst
+ impl_architecture.rst
+ NB_interface.rst
+ summary.rst
+
+ references.rst
+ annex1.rst
+ schemas.rst
+ supported_apis.rst
+ revision.rst
diff --git a/docs/development/requirements/intro.rst b/docs/development/requirements/intro.rst
new file mode 100644
index 0000000..654fdf9
--- /dev/null
+++ b/docs/development/requirements/intro.rst
@@ -0,0 +1,39 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+============
+Introduction
+============
+
+Resource reservation is a basic function for the operation of a virtualized
+telecom network. In resource reservation, VIM reserves resources for a certain
+period as requested by the NFVO. A resource reservation will have a start time
+which could be into the future. Therefore, the reserved resources shall be
+available for the NFVO requested purpose (e.g. for a VNF) at the start time for
+the duration asked by NFVO. Resources include all three resource types in an
+NFVI i.e. compute, storage and network.
+
+Besides, NFVO requires abstracted NFVI resource capacity information in order
+to take decisions on VNF placement and other operations related to the virtual
+resources. VIM is required to inform the NFVO of NFVI resource state
+information for this purpose. Promise project aims at delivering the detailed
+requirements on these two features defined in ETSI NFV MAN GS [NFVMAN]_,
+the list of gaps in upstream projects, potential implementation architecture
+and plan, and the VIM northbound interface specification for resource
+reservation and capacity management.
+
+Problem description
+===================
+
+OpenStack, a prominent candidate for the VIM, cannot reserve resources for
+future use. OpenStack requires immediate instantiation of Virtual Machines
+(VMs) in order to occupy resources intended to be reserved. Blazar can reserve
+compute resources for future by keeping the VMs in shelved mode. However, such
+reserved resources can also be used for scaling out rather than new VM
+instantiation. Blazar does not support network and storage resource reservation
+yet.
+
+Besides, OpenStack does not provide a northbound interface through which it can
+notify an upper layer management entity e.g. NFVO about capacity changes in its
+NFVI, periodically or in an event driven way. Capacity management is a feature
+defined in ETSI NFV MAN GS [NFVMAN]_ and is required in network operation.
diff --git a/docs/development/requirements/references.rst b/docs/development/requirements/references.rst
new file mode 100644
index 0000000..c498b66
--- /dev/null
+++ b/docs/development/requirements/references.rst
@@ -0,0 +1,25 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+References and bibliography
+===========================
+
+.. [PROMISE] OPNFV, "Promise" requirements project, [Online]. Available at
+ https://wiki.opnfv.org/promise
+.. [BLAZAR] OpenStack Blazar Project, [Online]. Available at
+ https://wiki.openstack.org/wiki/Blazar
+.. [PROMOSS] Promise reference implementation, [Online]. Available at
+ https://github.com/opnfv/promise
+.. [YANGFO] Yangforge Project, [Online]. Available at
+ https://github.com/opnfv/yangforge
+.. [NFVMAN] ETSI GS NFV MAN 001, "Network Function Virtualisation (NFV); Management and Orchestration"
+.. [NFV003] ETSI GS NFV 003, "Network Function Virtualisation (NFV); Terminology for Main Concepts in NFV"
+.. [NFVIFA010] ETSI GS NFV IFA 010, "Network Function Virtualisation (NFV); Management and Orchestration;
+ Functional Requirements Specification"
+.. [NFVIFA005] ETSI GS NFV IFA 005, "Network Function Virtualisation (NFV); Management and Orchestration;
+ Or-Vi reference point - Interface and Information Model Specification"
+.. [NFVIFA006] ETSI GS NFV IFA 006 "Network Function Virtualisation (NFV); Management and Orchestration;
+ Vi-Vnfm reference point - Interface and Information Model Specification"
+.. [ETSINFV] ETSI NFV, [Online]. Available at
+ http://www.etsi.org/technologies-clusters/technologies/nfv
+
diff --git a/docs/development/requirements/revision.rst b/docs/development/requirements/revision.rst
new file mode 100644
index 0000000..cd0b76b
--- /dev/null
+++ b/docs/development/requirements/revision.rst
@@ -0,0 +1,43 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+ANNEX D: Document revision
+==========================
+
++---------+-----------------------------------------+
+| Version | Description |
++---------+-----------------------------------------+
+| 1.0.1 | JIRA: PROMISE-23 |
+| | - Reference to YangForge Framework |
+| | - Corrections to figure 3.1 |
++---------+-----------------------------------------+
+| 1.0.2 | JIRA: PROMISE-11 |
+| | - OPNFV Logo Added |
+| | - Alignment to ETSI NFV Specs |
++---------+-----------------------------------------+
+| 1.0.3 | JIRA: PROMISE-54 |
+| | - Use case for Brahmaputra |
++---------+-----------------------------------------+
+| 1.0.4 | JIRA: PROMISE-60 |
+| | - Editorial fixes |
+| | |
+| | JIRA: PROMISE-57 |
+| | - Split shim-layer architecture and |
+| | integrated architecture sections |
++---------+-----------------------------------------+
+| 1.0.5 | JIRA: PROMISE-61 |
+| | - Updated Promise Yang Schema |
++---------+-----------------------------------------+
+| 1.0.6 | JIRA: PROMISE-62 |
+| | - Supported APIs for Brahmaputra |
++---------+-----------------------------------------+
+| 1.0.7 | JIRA: PROMISE-63 |
+| | - Update message flow for shim-layer |
+| | JIRA: PROMISE-58 |
+| | - Integrated approach description |
+| | JIRA: PROMISE-64 |
+| | - Promise userguide |
++---------+-----------------------------------------+
+| 1.0.8 | JIRA: PROMISE-11 |
+| | - Alignment to ETSI NVF Specs |
++---------+-----------------------------------------+
diff --git a/docs/development/requirements/schemas.rst b/docs/development/requirements/schemas.rst
new file mode 100644
index 0000000..c98b7da
--- /dev/null
+++ b/docs/development/requirements/schemas.rst
@@ -0,0 +1,658 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _yang_schema:
+
+ANNEX B: Promise YANG schema based on YangForge
+===============================================
+
+.. code::
+
+ module opnfv-promise {
+ namespace "urn:opnfv:promise";
+ prefix promise;
+
+ import complex-types { prefix ct; }
+ import ietf-yang-types { prefix yang; }
+ import ietf-inet-types { prefix inet; }
+ import access-control-models { prefix acm; }
+ import nfv-infrastructure { prefix nfvi; }
+ import nfv-mano { prefix mano; }
+
+ description
+ "OPNFV Promise Resource Reservation/Allocation controller module";
+
+ revision 2015-10-05 {
+ description "Complete coverage of reservation related intents";
+ }
+
+ revision 2015-08-06 {
+ description "Updated to incorporate YangForge framework";
+ }
+
+ revision 2015-04-16 {
+ description "Initial revision.";
+ }
+
+ feature reservation-service {
+ description "When enabled, provides resource reservation service";
+ }
+
+ feature multi-provider {
+ description "When enabled, provides resource management across multiple providers";
+ }
+
+ typedef reference-identifier {
+ description "defines valid formats for external reference id";
+ type union {
+ type yang:uuid;
+ type inet:uri;
+ type uint32;
+ }
+ }
+
+ grouping resource-utilization {
+ container capacity {
+ container total { description 'Conceptual container that should be extended'; }
+ container reserved { description 'Conceptual container that should be extended';
+ config false; }
+ container usage { description 'Conceptual container that should be extended';
+ config false; }
+ container available { description 'Conceptual container that should be extended';
+ config false; }
+ }
+ }
+
+ grouping temporal-resource-collection {
+ description
+ "Information model capturing resource-collection with start/end time window";
+
+ leaf start { type yang:date-and-time; }
+ leaf end { type yang:date-and-time; }
+
+ uses nfvi:resource-collection;
+ }
+
+ grouping resource-usage-request {
+ description
+ "Information model capturing available parameters to make a resource
+ usage request.";
+ reference "OPNFV-PROMISE, Section 3.4.1";
+
+ uses temporal-resource-collection {
+ refine elements {
+ description
+ "Reference to a list of 'pre-existing' resource elements that are
+ required for fulfillment of the resource-usage-request.
+
+ It can contain any instance derived from ResourceElement,
+ such as ServerInstances or even other
+ ResourceReservations. If the resource-usage-request is
+ accepted, the ResourceElement(s) listed here will be placed
+ into 'protected' mode as to prevent accidental removal.
+
+ If any of these resource elements become 'unavailable' due to
+ environmental or administrative activity, a notification will
+ be issued informing of the issue.";
+ }
+ }
+
+ leaf zone {
+ description "Optional identifier to an Availability Zone";
+ type instance-identifier { ct:instance-type nfvi:AvailabilityZone; }
+ }
+ }
+
+ grouping query-start-end-window {
+ container window {
+ description "Matches entries that are within the specified start/end time window";
+ leaf start { type yang:date-and-time; }
+ leaf end { type yang:date-and-time; }
+ leaf scope {
+ type enumeration {
+ enum "exclusive" {
+ description "Matches entries that start AND end within the window";
+ }
+ enum "inclusive" {
+ description "Matches entries that start OR end within the window";
+ }
+ }
+ default "inclusive";
+ }
+ }
+ }
+
+ grouping query-resource-collection {
+ uses query-start-end-window {
+ description "Match for ResourceCollection(s) that are within the specified
+ start/end time window";
+ }
+ leaf-list without {
+ description "Excludes specified collection identifiers from the result";
+ type instance-identifier { ct:instance-type ResourceCollection; }
+ }
+ leaf show-utilization { type boolean; default true; }
+ container elements {
+ leaf-list some {
+ description "Query for ResourceCollection(s) that contain some or more of
+ these element(s)";
+ type instance-identifier { ct:instance-type nfvi:ResourceElement; }
+ }
+ leaf-list every {
+ description "Query for ResourceCollection(s) that contain all of
+ these element(s)";
+ type instance-identifier { ct:instance-type nfvi:ResourceElement; }
+ }
+ }
+ }
+
+ grouping common-intent-output {
+ leaf result {
+ type enumeration {
+ enum "ok";
+ enum "conflict";
+ enum "error";
+ }
+ }
+ leaf message { type string; }
+ }
+
+ grouping utilization-output {
+ list utilization {
+ key 'timestamp';
+ leaf timestamp { type yang:date-and-time; }
+ leaf count { type int16; }
+ container capacity { uses nfvi:resource-capacity; }
+ }
+ }
+
+ ct:complex-type ResourceCollection {
+ ct:extends nfvi:ResourceContainer;
+ ct:abstract true;
+
+ description
+ "Describes an abstract ResourceCollection data model, which represents
+ a grouping of capacity and elements available during a given
+ window in time which must be extended by other resource
+ collection related models";
+
+ leaf start { type yang:date-and-time; }
+ leaf end { type yang:date-and-time; }
+
+ leaf active {
+ config false;
+ description
+ "Provides current state of this record whether it is enabled and within
+ specified start/end time";
+ type boolean;
+ }
+ }
+
+ ct:complex-type ResourcePool {
+ ct:extends ResourceCollection;
+
+ description
+ "Describes an instance of an active ResourcePool record, which
+ represents total available capacity and elements from a given
+ source.";
+
+ leaf source {
+ type instance-identifier {
+ ct:instance-type nfvi:ResourceContainer;
+ require-instance true;
+ }
+ mandatory true;
+ }
+
+ refine elements {
+ // following 'must' statement applies to each element
+ // NOTE: just a non-working example for now...
+ must "boolean(/source/elements/*[@id=id])" {
+ error-message "One or more of the ResourceElement(s) does not exist in
+ the provider to be reserved";
+ }
+ }
+ }
+
+ ct:complex-type ResourceReservation {
+ ct:extends ResourceCollection;
+
+ description
+ "Describes an instance of an accepted resource reservation request,
+ created usually as a result of 'create-reservation' request.
+
+ A ResourceReservation is a derived instance of a generic
+ ResourceCollection which has additional parameters to map the
+ pool(s) that were referenced to accept this reservation as well
+ as to track allocations made referencing this reservation.
+
+ Contains the capacities of various resource attributes being
+ reserved along with any resource elements that are needed to be
+ available at the time of allocation(s).";
+
+ reference "OPNFV-PROMISE, Section 3.4.1";
+
+ leaf created-on { type yang:date-and-time; config false; }
+ leaf modified-on { type yang:date-and-time; config false; }
+
+ leaf-list pools {
+ config false;
+ description
+ "Provides list of one or more pools that were referenced for providing
+ the requested resources for this reservation. This is an
+ important parameter for informing how/where allocation
+ requests can be issued using this reservation since it is
+ likely that the total reserved resource capacity/elements are
+ made availble from multiple sources.";
+ type instance-identifier {
+ ct:instance-type ResourcePool;
+ require-instance true;
+ }
+ }
+
+ container remaining {
+ config false;
+ description
+ "Provides visibility into total remaining capacity for this
+ reservation based on allocations that took effect utilizing
+ this reservation ID as a reference.";
+
+ uses nfvi:resource-capacity;
+ }
+
+ leaf-list allocations {
+ config false;
+ description
+ "Reference to a collection of consumed allocations referencing
+ this reservation.";
+ type instance-identifier {
+ ct:instance-type ResourceAllocation;
+ require-instance true;
+ }
+ }
+ }
+
+ ct:complex-type ResourceAllocation {
+ ct:extends ResourceCollection;
+
+ description
+ "A ResourceAllocation record denotes consumption of resources from a
+ referenced ResourcePool.
+
+ It does not reflect an accepted request but is created to
+ represent the actual state about the ResourcePool. It is
+ created once the allocation(s) have successfully taken effect
+ on the 'source' of the ResourcePool.
+
+ The 'priority' state indicates the classification for dealing
+ with resource starvation scenarios. Lower priority allocations
+ will be forcefully terminated to allow for higher priority
+ allocations to be fulfilled.
+
+ Allocations without reference to an existing reservation will
+ receive the lowest priority.";
+
+ reference "OPNFV-PROMISE, Section 3.4.3";
+
+ leaf reservation {
+ description "Reference to an existing reservation identifier (optional)";
+
+ type instance-identifier {
+ ct:instance-type ResourceReservation;
+ require-instance true;
+ }
+ }
+
+ leaf pool {
+ description "Reference to an existing resource pool from which allocation is drawn";
+
+ type instance-identifier {
+ ct:instance-type ResourcePool;
+ require-instance true;
+ }
+ }
+
+ container instance-ref {
+ config false;
+ description
+ "Reference to actual instance identifier of the provider/server
+ for this allocation";
+ leaf provider {
+ type instance-identifier { ct:instance-type ResourceProvider; }
+ }
+ leaf server { type yang:uuid; }
+ }
+
+ leaf priority {
+ config false;
+ description
+ "Reflects current priority level of the allocation according to
+ classification rules";
+ type enumeration {
+ enum "high" { value 1; }
+ enum "normal" { value 2; }
+ enum "low" { value 3; }
+ }
+ default "normal";
+ }
+ }
+
+ ct:complex-type ResourceProvider {
+ ct:extends nfvi:ResourceContainer;
+
+ key "name";
+ leaf token { type string; mandatory true; }
+
+ container services { // read-only
+ config false;
+ container compute {
+ leaf endpoint { type inet:uri; }
+ ct:instance-list flavors { ct:instance-type nfvi:ComputeFlavor; }
+ }
+ }
+
+ leaf-list pools {
+ config false;
+ description
+ "Provides list of one or more pools that are referencing this provider.";
+
+ type instance-identifier {
+ ct:instance-type ResourcePool;
+ require-instance true;
+ }
+ }
+ }
+
+ // MAIN CONTAINER
+ container promise {
+
+ uses resource-utilization {
+ description "Describes current state info about capacity utilization info";
+
+ augment "capacity/total" { uses nfvi:resource-capacity; }
+ augment "capacity/reserved" { uses nfvi:resource-capacity; }
+ augment "capacity/usage" { uses nfvi:resource-capacity; }
+ augment "capacity/available" { uses nfvi:resource-capacity; }
+ }
+
+ ct:instance-list providers {
+ if-feature multi-provider;
+ description "Aggregate collection of all registered ResourceProvider instances
+ for Promise resource management service";
+ ct:instance-type ResourceProvider;
+ }
+
+ ct:instance-list pools {
+ if-feature reservation-service;
+ description "Aggregate collection of all ResourcePool instances";
+ ct:instance-type ResourcePool;
+ }
+
+ ct:instance-list reservations {
+ if-feature reservation-service;
+ description "Aggregate collection of all ResourceReservation instances";
+ ct:instance-type ResourceReservation;
+ }
+
+ ct:instance-list allocations {
+ description "Aggregate collection of all ResourceAllocation instances";
+ ct:instance-type ResourceAllocation;
+ }
+
+ container policy {
+ container reservation {
+ leaf max-future-start-range {
+ description
+ "Enforce reservation request 'start' time is within allowed range from now";
+ type uint16 { range 0..365; }
+ units "days";
+ }
+ leaf max-future-end-range {
+ description
+ "Enforce reservation request 'end' time is within allowed range from now";
+ type uint16 { range 0..365; }
+ units "days";
+ }
+ leaf max-duration {
+ description
+ "Enforce reservation duration (end-start) does not exceed specified threshold";
+ type uint16;
+ units "hours";
+ default 8760; // for now cap it at max one year as default
+ }
+ leaf expiry {
+ description
+ "Duration in minutes from start when unallocated reserved resources
+ will be released back into the pool";
+ type uint32;
+ units "minutes";
+ }
+ }
+ }
+ }
+
+ //-------------------
+ // INTENT INTERFACE
+ //-------------------
+
+ // RESERVATION INTENTS
+ rpc create-reservation {
+ if-feature reservation-service;
+ description "Make a request to the reservation system to reserve resources";
+ input {
+ uses resource-usage-request;
+ }
+ output {
+ uses common-intent-output;
+ leaf reservation-id {
+ type instance-identifier { ct:instance-type ResourceReservation; }
+ }
+ }
+ }
+
+ rpc update-reservation {
+ description "Update reservation details for an existing reservation";
+ input {
+ leaf reservation-id {
+ type instance-identifier {
+ ct:instance-type ResourceReservation;
+ require-instance true;
+ }
+ mandatory true;
+ }
+ uses resource-usage-request;
+ }
+ output {
+ uses common-intent-output;
+ }
+ }
+
+ rpc cancel-reservation {
+ description "Cancel the reservation and be a good steward";
+ input {
+ leaf reservation-id {
+ type instance-identifier { ct:instance-type ResourceReservation; }
+ mandatory true;
+ }
+ }
+ output {
+ uses common-intent-output;
+ }
+ }
+
+ rpc query-reservation {
+ if-feature reservation-service;
+ description "Query the reservation system to return matching reservation(s)";
+ input {
+ leaf zone { type instance-identifier { ct:instance-type nfvi:AvailabilityZone; } }
+ uses query-resource-collection;
+ }
+ output {
+ leaf-list reservations { type instance-identifier
+ { ct:instance-type ResourceReservation; } }
+ uses utilization-output;
+ }
+ }
+
+ // CAPACITY INTENTS
+ rpc increase-capacity {
+ description "Increase total capacity for the reservation system
+ between a window in time";
+ input {
+ uses temporal-resource-collection;
+ leaf source {
+ type instance-identifier {
+ ct:instance-type nfvi:ResourceContainer;
+ }
+ }
+ }
+ output {
+ uses common-intent-output;
+ leaf pool-id {
+ type instance-identifier { ct:instance-type ResourcePool; }
+ }
+ }
+ }
+
+ rpc decrease-capacity {
+ description "Decrease total capacity for the reservation system
+ between a window in time";
+ input {
+ uses temporal-resource-collection;
+ leaf source {
+ type instance-identifier {
+ ct:instance-type nfvi:ResourceContainer;
+ }
+ }
+ }
+ output {
+ uses common-intent-output;
+ leaf pool-id {
+ type instance-identifier { ct:instance-type ResourcePool; }
+ }
+ }
+ }
+
+ rpc query-capacity {
+ description "Check available capacity information about a specified
+ resource collection";
+ input {
+ leaf capacity {
+ type enumeration {
+ enum 'total';
+ enum 'reserved';
+ enum 'usage';
+ enum 'available';
+ }
+ default 'available';
+ }
+ leaf zone { type instance-identifier { ct:instance-type nfvi:AvailabilityZone; } }
+ uses query-resource-collection;
+ // TBD: additional parameters for query-capacity
+ }
+ output {
+ leaf-list collections { type instance-identifier
+ { ct:instance-type ResourceCollection; } }
+ uses utilization-output;
+ }
+ }
+
+ // ALLOCATION INTENTS (should go into VIM module in the future)
+ rpc create-instance {
+ description "Create an instance of specified resource(s) utilizing capacity
+ from the pool";
+ input {
+ leaf provider-id {
+ if-feature multi-provider;
+ type instance-identifier { ct:instance-type ResourceProvider;
+ require-instance true; }
+ }
+ leaf name { type string; mandatory true; }
+ leaf image {
+ type reference-identifier;
+ mandatory true;
+ }
+ leaf flavor {
+ type reference-identifier;
+ mandatory true;
+ }
+ leaf-list networks {
+ type reference-identifier;
+ description "optional, will assign default network if not provided";
+ }
+
+ // TODO: consider supporting a template-id (such as HEAT) for more complex instantiation
+
+ leaf reservation-id {
+ type instance-identifier { ct:instance-type ResourceReservation;
+ require-instance true; }
+ }
+ }
+ output {
+ uses common-intent-output;
+ leaf instance-id {
+ type instance-identifier { ct:instance-type ResourceAllocation; }
+ }
+ }
+ }
+
+ rpc destroy-instance {
+ description "Destroy an instance of resource utilization and release it
+ back to the pool";
+ input {
+ leaf instance-id {
+ type instance-identifier { ct:instance-type ResourceAllocation;
+ require-instance true; }
+ }
+ }
+ output {
+ uses common-intent-output;
+ }
+ }
+
+ // PROVIDER INTENTS (should go into VIM module in the future)
+ rpc add-provider {
+ description "Register a new resource provider into reservation system";
+ input {
+ leaf provider-type {
+ description "Select a specific resource provider type";
+ mandatory true;
+ type enumeration {
+ enum openstack;
+ enum hp;
+ enum rackspace;
+ enum amazon {
+ status planned;
+ }
+ enum joyent {
+ status planned;
+ }
+ enum azure {
+ status planned;
+ }
+ }
+ default openstack;
+ }
+ uses mano:provider-credentials {
+ refine endpoint {
+ default "http://localhost:5000/v2.0/tokens";
+ }
+ }
+ container tenant {
+ leaf id { type string; }
+ leaf name { type string; }
+ }
+ }
+ output {
+ uses common-intent-output;
+ leaf provider-id {
+ type instance-identifier { ct:instance-type ResourceProvider; }
+ }
+ }
+ }
+
+ // TODO...
+ notification reservation-event;
+ notification capacity-event;
+ notification allocation-event;
+ }
diff --git a/docs/development/requirements/summary.rst b/docs/development/requirements/summary.rst
new file mode 100644
index 0000000..fcf10d1
--- /dev/null
+++ b/docs/development/requirements/summary.rst
@@ -0,0 +1,27 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+======================
+Summary and conclusion
+======================
+
+Resource Reservation and Resource Capacity Management are features to be
+supported by the VIM and exposed to the consumer via the VIM NBI. These
+features have been specified by ETSI NFV.
+
+This document has described several use cases and corresponding high level
+flows where Resource Reservation and Capacity Management are of great benefit
+for the consumer of the virtualised resource management interface: the NFVO or
+the VNFM. The use cases include:
+
+* Notification of changes in capacity in the NFVI
+* Query of available resource capacity
+* Reservation of a resource or set of resources for immediate use
+* Reservation of a resource or set of resources for future use
+
+The Promise project has performed a gap analysis in order to fulfill the
+required functionality. Based on the gap analysis an implementation plan and
+way forward has been proposed, including a possible design architecture and
+high level information model. Immediate next steps of this project is to
+deliver a working Proof-of-Concepts (PoC) and engage upstream communities to
+fill out the gaps identified by Promise.
diff --git a/docs/development/requirements/supported_apis.rst b/docs/development/requirements/supported_apis.rst
new file mode 100644
index 0000000..40cba8d
--- /dev/null
+++ b/docs/development/requirements/supported_apis.rst
@@ -0,0 +1,608 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+ANNEX C: Supported APIS
+=======================
+
+Add Provider
+------------
+
+Register a new resource provider (e.g. OpenStack) into reservation system.
+
+Request parameters
+
+============================ =========== ==============================================
+Name Type Description
+============================ =========== ==============================================
+provider-type Enumeration Name of the resource provider
+endpoint URI Targer URL end point for the resource provider
+username String User name
+password String Password
+region String Specified region for the provider
+tenant.id String Id of the tenant
+tenant.name String Name of the tenant
+============================ =========== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name Type Description
+============================ =========== ==============================================
+provider-id String Id of the new resource provider
+result Enumeration Result info
+============================ =========== ==============================================
+
+.. http:post:: /add-provider
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /add-provider HTTP/1.1
+ Accept: application/json
+
+ {
+ "provider-type": "openstack",
+ "endpoint": "http://10.0.2.15:5000/v2.0/tokens",
+ "username": "promise_user",
+ "password": "******",
+ "tenant": {
+ "name": "promise"
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
+ "result": "ok"
+ }
+
+Create Reservation
+------------------
+
+Make a request to the reservation system to reserve resources.
+
+Request parameters
+
+============================ =============== ==============================================
+Name Type Description
+============================ =============== ==============================================
+zone String Id to an availability zone
+start DateTime Timestamp when the consumption of reserved
+ resources can begin
+end DateTime Timestamp when the consumption of reserved
+ resources should end
+capacity.cores int16 Amount of cores to be reserved
+capacity.ram int32 Amount of RAM to be reserved
+capacity.instances int16 Amount of instances to be reserved
+capacity.addresses int32 Amount of public IP addresses to be reserved
+elements ResourceElement List of pre-existing resource elements
+ to be reserved
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name Type Description
+============================ =========== ==============================================
+reservation-id String Id of the reservation
+result Enumeration Result info
+message String Output message
+============================ =========== ==============================================
+
+.. http:post:: /create-reservation
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /create-reservation HTTP/1.1
+ Accept: application/json
+
+ {
+ "capacity": {
+ "cores": "5",
+ "ram": "25600",
+ "addresses": "3",
+ "instances": "3"
+ },
+ "start": "2016-02-02T00:00:00Z",
+ "end": "2016-02-03T00:00:00Z"
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "reservation-id": "269b2944-9efc-41e0-b067-6898221e8619",
+ "result": "ok",
+ "message": "reservation request accepted"
+ }
+
+Update Reservation
+------------------
+
+Update reservation details for an existing reservation.
+
+Request parameters
+
+============================ =============== ==============================================
+Name Type Description
+============================ =============== ==============================================
+reservation-id String Id of the reservation to be updated
+zone String Id to an availability zone
+start DateTime Updated timestamp when the consumption of
+ reserved resources can begin
+end DateTime Updated timestamp when the consumption of
+ reserved resources should end
+capacity.cores int16 Updated amount of cores to be reserved
+capacity.ram int32 Updated amount of RAM to be reserved
+capacity.instances int16 Updated amount of instances to be reserved
+capacity.addresses int32 Updated amount of public IP addresses
+ to be reserved
+elements ResourceElement Updated list of pre-existing resource elements
+ to be reserved
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name Type Description
+============================ =========== ==============================================
+result Enumeration Result info
+message String Output message
+============================ =========== ==============================================
+
+.. http:post:: /update-reservation
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /update-reservation HTTP/1.1
+ Accept: application/json
+
+ {
+ "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619",
+ "capacity": {
+ "cores": "1",
+ "ram": "5120",
+ "addresses": "1",
+ "instances": "1"
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "result": "ok",
+ "message": "reservation update successful"
+ }
+
+Cancel Reservation
+------------------
+
+Cancel the reservation.
+
+Request parameters
+
+============================ =============== ==============================================
+Name Type Description
+============================ =============== ==============================================
+reservation-id String Id of the reservation to be canceled
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name Type Description
+============================ =========== ==============================================
+result Enumeration Result info
+message String Output message
+============================ =========== ==============================================
+
+.. http:post:: /cancel-reservation
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /cancel-reservation HTTP/1.1
+ Accept: application/json
+
+ {
+ "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619"
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "result": "ok",
+ "message": "reservation canceled"
+ }
+
+Query Reservation
+-----------------
+
+Query the reservation system to return matching reservation(s).
+
+Request parameters
+
+============================ ================== ==============================================
+Name Type Description
+============================ ================== ==============================================
+zone String Id to an availability zone
+show-utilization Boolean Show capacity utilization
+without ResourceCollection Excludes specified collection identifiers
+ from the result
+elements.some ResourceElement Query for ResourceCollection(s) that contain
+ some or more of these element(s)
+elements.every ResourceElement Query for ResourceCollection(s) that contain
+ all of these element(s)
+window.start DateTime Matches entries that are within the specified
+ start/end window
+window.end DateTime
+wndow.scope Enumeration Matches entries that start {and/or} end
+ within the time window
+============================ ================== ==============================================
+
+Response parameters
+
+============================ =================== ================================
+Name Type Description
+============================ =================== ================================
+reservations ResourceReservation List of matching reservations
+utilization CapacityUtilization Capacity utilization over time
+============================ =================== ================================
+
+.. http:post:: /query-reservation
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /query-reservation HTTP/1.1
+ Accept: application/json
+
+ {
+ "show-utilization": false,
+ "window": {
+ "start": "2016-02-01T00:00:00Z",
+ "end": "2016-02-04T00:00:00Z"
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "reservations": [
+ "269b2944-9efv-41e0-b067-6898221e8619"
+ ],
+ "utilization": []
+ }
+
+Create Instance
+---------------
+
+Create an instance of specified resource(s) utilizing capacity from the pool.
+
+Request parameters
+
+============================ =============== ==============================================
+Name Type Description
+============================ =============== ==============================================
+provider-id String Id of the resource provider
+reservation-id String Id of the resource reservation
+name String Name of the instance
+image String Id of the image
+flavor String Id of the flavor
+networks Uuid List of network uuids
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name Type Description
+============================ =========== ==============================================
+instance-id String Id of the instance
+result Enumeration Result info
+message String Output message
+============================ =========== ==============================================
+
+.. http:post:: /create-instance
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /create-instance HTTP/1.1
+ Accept: application/json
+
+ {
+ "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
+ "name": "vm1",
+ "image": "ddffc6f5-5c86-4126-b0fb-2c71678633f8",
+ "flavor": "91bfdf57-863b-4b73-9d93-fc311894b902"
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "instance-id": "82572779-896b-493f-92f6-a63008868250",
+ "result": "ok",
+ "message": "created-instance request accepted"
+ }
+
+Destroy Instance
+----------------
+
+Destroy an instance of resource utilization and release it back to the pool.
+
+Request parameters
+
+============================ =============== ==============================================
+Name Type Description
+============================ =============== ==============================================
+instance-id String Id of the instance to be destroyed
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name Type Description
+============================ =========== ==============================================
+result Enumeration Result info
+message String Output message
+============================ =========== ==============================================
+
+.. http:post:: /destroy-instance
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /destroy-instance HTTP/1.1
+ Accept: application/json
+
+ {
+ "instance-id": "82572779-896b-493f-92f6-a63008868250"
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "result": "ok",
+ "message": "instance destroyed and resource released back to pool"
+ }
+
+Decrease Capacity
+-----------------
+
+Decrease total capacity for the reservation system for a given time window.
+
+Request parameters
+
+============================ =============== ==============================================
+Name Type Description
+============================ =============== ==============================================
+source String Id of the resource container
+start DateTime Start/end defines the time window when total
+ capacity is decreased
+end DateTime
+capacity.cores int16 Decreased amount of cores
+capacity.ram int32 Decreased amount of RAM
+capacity.instances int16 Decreased amount of instances
+capacity.addresses int32 Decreased amount of public IP addresses
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name Type Description
+============================ =========== ==============================================
+pool-id String Id of the resource pool
+result Enumeration Result info
+message String Output message
+============================ =========== ==============================================
+
+.. http:post:: /decrease-capacity
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /decrease-capacity HTTP/1.1
+ Accept: application/json
+
+ {
+ "source": "ResourcePool:4085f0da-8030-4252-a0ff-c6f93870eb5f",
+ "capacity": {
+ "cores": "3",
+ "ram": "5120",
+ "addresses": "1"
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "pool-id": "c63b2a41-bcc6-42f6-8254-89d633e1bd0b",
+ "result": "ok",
+ "message": "capacity decrease successful"
+ }
+
+Increase Capacity
+-----------------
+
+Increase total capacity for the reservation system for a given time window.
+
+Request parameters
+
+============================ =============== ==============================================
+Name Type Description
+============================ =============== ==============================================
+source String Id of the resource container
+start DateTime Start/end defines the time window when total
+ capacity is increased
+end DateTime
+capacity.cores int16 Increased amount of cores
+capacity.ram int32 Increased amount of RAM
+capacity.instances int16 Increased amount of instances
+capacity.addresses int32 Increased amount of public IP addresses
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name Type Description
+============================ =========== ==============================================
+pool-id String Id of the resource pool
+result Enumeration Result info
+message String Output message
+============================ =========== ==============================================
+
+.. http:post:: /increase-capacity
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /increase-capacity HTTP/1.1
+ Accept: application/json
+
+ {
+ "source": "ResourceProvider:f6f13fe3-0126-4c6d-a84f-15f1ab685c4f",
+ "capacity": {
+ "cores": "20",
+ "ram": "51200",
+ "instances": "10",
+ "addresses": "10"
+ }
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "pool-id": "279217a4-7461-4176-bf9d-66770574ca6a",
+ "result": "ok",
+ "message": "capacity increase successful"
+ }
+
+Query Capacity
+--------------
+
+Query for capacity information about a specified resource collection.
+
+Request parameters
+
+============================ ================== ==============================================
+Name Type Description
+============================ ================== ==============================================
+capacity Enumeration Return total or reserved or available or
+ usage capacity information
+zone String Id to an availability zone
+show-utilization Boolean Show capacity utilization
+without ResourceCollection Excludes specified collection identifiers
+ from the result
+elements.some ResourceElement Query for ResourceCollection(s) that contain
+ some or more of these element(s)
+elements.every ResourceElement Query for ResourceCollection(s) that contain
+ all of these element(s)
+window.start DateTime Matches entries that are within the specified
+ start/end window
+window.end DateTime
+window.scope Enumeration Matches entries that start {and/or} end
+ within the time window
+============================ ================== ==============================================
+
+Response parameters
+
+============================ =================== ================================
+Name Type Description
+============================ =================== ================================
+collections ResourceCollection List of matching collections
+utilization CapacityUtilization Capacity utilization over time
+============================ =================== ================================
+
+.. http:post:: /query-capacity
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /query-capacity HTTP/1.1
+ Accept: application/json
+
+ {
+ "show-utilization": false
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "collections": [
+ "ResourcePool:279217a4-7461-4176-bf9d-66770574ca6a"
+ ],
+ "utilization": []
+ }
+
diff --git a/docs/development/requirements/usecase.rst b/docs/development/requirements/usecase.rst
new file mode 100644
index 0000000..bdf8888
--- /dev/null
+++ b/docs/development/requirements/usecase.rst
@@ -0,0 +1,121 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+=======================
+Use cases and scenarios
+=======================
+
+Use cases
+=========
+
+Resource reservation is a basic feature in any virtualization-based network
+operation. In order to perform such resource reservation from NFVO to VIM, NFVI
+capacity information is also necessary at the NFVO side. Below, four use cases
+to show typical requirements and solutions for capacity management and resource
+reservation is presented. A typical use case as considered for the Brahmaputra
+release is described in :ref:`uc-brahmaputra`.
+
+#. Resource capacity management
+#. Resource reservation for immediate use
+#. Resource reservation for future use
+#. Co-existence of reservations and allocation requests without reservation
+
+Resource capacity management
+----------------------------
+
+NFVO takes the first decision on in which NFVI it would instantiate a VNF. Along
+with NFVIs resource attributes (e.g. availability of hardware accelerators,
+particular CPU architectures etc.), NFVO needs to know available capacity of an
+NFVI in order to make an informed decision on selecting a particular NFVI. Such
+capacity information shall be in a coarser granularity than the respective VIM,
+as VIM maintains capacity information of its NFVI in fine details. However a
+very coarse granularity, like simply the number of available virtual CPU cores,
+may not be sufficient. In order to allow the NFVO to make well founded
+allocation decisions, an appropriate level to expose the available capacity may
+be per flavor. Capacity information may be required for the complete NFVI, or
+per partition or availability zone, or other granularities. Therefore, VIM
+requires to inform the NFVO about available capacity information regarding its
+NFVI at a pre-determined abstraction, either by a query-response, or in an
+event-based, or in a periodical way.
+
+Resource reservation for immediate use
+--------------------------------------
+
+Reservation is inherently for the future. Even if some reserved resources are to
+be consumed instantly, there is a network latency between the issuance of a
+resource reservation request from the NFVO, a response from the VIM, and actual
+allocation of the requested resources to a VNF/VNFM. Within such latency,
+resource capacity in the NFVI in question could change, e.g., due to failure,
+allocation to a different request. Therefore, the response from a VIM to the
+NFVO to a resource reservation request for immediate use should have a validity
+period which shows until when this VIM can hold the requested resources. During
+this time, the NFVO should proceed to allocation if it wishes to consume the
+reserved requested. If allocation is not performed within the validity period,
+the response from VIM for a particular resource reservation request becomes
+invalid and VIM is not liable to provide those resources to NFVO/VNFM anymore.
+Reservations requests for immediate use do not have a start time but may have
+an end time.
+
+Resource reservation for future use
+-----------------------------------
+
+Network operators may want to reserve extra resources for future use. Such
+necessity could arise from predicted congestion in telecom nodes e.g. due to
+local traffic spikes for concerts, natural disasters etc. In such a case, the
+NFVO, while sending a resource reservation request to the VIM, shall include a
+start time (and an end time if necessary). The start time indicates at what
+time the reserved resource shall be available to a designated consumer e.g. a
+VNF/VNFM. Here, the requirement is that the reserved resources shall be
+available when the start time arrives. After the start time has arrived, the
+reserved resources are allocated to the designated consumer(s). An explicit
+allocation request is needed. How actually these requested resources are held
+by the VIM for the period in between the arrival of the resource reservation
+request and the actual allocation is outside the scope of this requirement
+project.
+
+Co-existence of reservations and allocation requests without reservation
+------------------------------------------------------------------------
+
+In a real environment VIM will have to handle allocation requests without any
+time reference, i.e. time-unbound, together with time-bound reservations and
+allocation requests with an explicitly indicated end-time. A granted
+reservation for the future will effectively reduce the available capacity for
+any new time-unbound allocation request. The consequence is that reservations,
+even those far in the future, may result in denial of service for new
+allocation requests.
+
+To alleviate this problem several approaches can be taken. They imply an
+implicit or explicit priority scheme:
+
+* Allocation requests without reservation and which are time-unbound will be
+ granted resources in a best-effort way: if there is instant capacity, but the
+ resources may be later withdrawn due to the start time of a previously
+ granted reservation
+* Both allocation requests and reservation requests contain a priority which
+ may be related to SLAs and contractual conditions between the tenant and the
+ NFVI provider. Interactions may look like:
+
+ * A reservation request for future use may cancel another, not yet
+ started, reservation with lower priority
+ * An allocation request without reservations and time-unbound [#unbound]_
+ may be granted resources and prevent a future reservation with lower
+ priority from getting resources at start time
+ * A reservation request may result in terminating resources allocated to a
+ request with no reservation, if the latter has lower priority
+
+.. [#unbound] In this case, the consumer (VNFM or NFVO) requests to immediately
+ instantiate and assign virtualized resources without having
+ reserved the resources beforehand
+
+Scenarios
+=========
+
+This section describes the expected behavior of the system in different
+scenarios.
+
+As we are targeting a cloud platform with the above use cases, it is crucial to
+keep the flexibility in the system. By this means it is hard to explicitely
+block hardware resources for the future and ensure their availablility for
+allocation therefore it can happen that the reservation plan cannot be fulfilled
+due to certain changes in the underlying environment. We need to ensure that we
+are prepared for error and edge cases during the design period.
diff --git a/docs/installationprocedure/feature.configuration.rst b/docs/installationprocedure/feature.configuration.rst
deleted file mode 100644
index 10696e0..0000000
--- a/docs/installationprocedure/feature.configuration.rst
+++ /dev/null
@@ -1,63 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-Manual testing
-==============
-
-Promise installation
---------------------
-
-Install nodejs, npm and promise
-
-.. code-block:: bash
-
- curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
- sudo apt-get install -y nodejs
- sudo npm -g install npm@latest
- git clone https://gerrit.opnfv.org/gerrit/promise
- cd promise/source
- npm install
-
-Please note that the last command 'npm install' will install all needed dependencies
-for promise (including yangforge and mocha)
-
-.. figure:: images/screenshot_promise_install.png
- :name: figure1
- :width: 90%
-
-
-Validation
-----------
-Please perform the following preparation steps:
-
-1. Set OpenStack environment parameters properly (e.g. source openrc admin demo
- in DevStack)
-2. Create OpenStack tenant (e.g. promise) and tenant user (e.g. promiser)
-3. Create a flavor in Nova with 1 vCPU and 512 MB RAM
-4. Create a private network, subnet and router in Neutron
-5. Create an image in Glance
-
-Once done, the promise test script can be invoked as follows (as a single line
-command):
-
-.. code-block:: bash
-
- NODE_ENV=mytest \
- OS_TENANT_NAME=promise \
- OS_USERNAME=promiser \
- OS_PASSWORD=<user password from Step 2> \
- OS_TEST_FLAVOR=<flavor ID from Step 3> \
- OS_TEST_NETWORK=<network ID from Step 4> \
- OS_TEST_IMAGE=<image ID from Step 5> \
- npm run -s test -- --reporter json > promise-results.json
-
-The results of the tests will be stored in the promise-results.json file.
-
-The results can also be seen in the console ("npm run -s test")
-
-.. figure:: images/screenshot_promise.png
- :name: figure2
- :width: 90%
-
-All 33 tests passing?!
-Congratulations, promise has been successfully installed and configured.
diff --git a/docs/installationprocedure/images/LICENSE b/docs/installationprocedure/images/LICENSE
deleted file mode 100644
index 6a84dd4..0000000
--- a/docs/installationprocedure/images/LICENSE
+++ /dev/null
@@ -1,14 +0,0 @@
-Copyright 2016 Open Platform for NFV Project, Inc. and its contributors
-
-Open Platform for NFV Project Documentation Licence
-===================================================
-Any documentation developed by the "Open Platform for NFV Project"
-is licensed under a Creative Commons Attribution 4.0 International License.
-You should have received a copy of the license along with this. If not,
-see <http://creativecommons.org/licenses/by/4.0/>.
-
-Unless required by applicable law or agreed to in writing, documentation
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
diff --git a/docs/installationprocedure/images/screenshot_promise.png b/docs/installationprocedure/images/screenshot_promise.png
deleted file mode 100755
index 4a0cbe3..0000000
Binary files a/docs/installationprocedure/images/screenshot_promise.png and /dev/null differ
diff --git a/docs/installationprocedure/images/screenshot_promise_install.png b/docs/installationprocedure/images/screenshot_promise_install.png
deleted file mode 100644
index 2cb27d9..0000000
Binary files a/docs/installationprocedure/images/screenshot_promise_install.png and /dev/null differ
diff --git a/docs/installationprocedure/index.rst b/docs/installationprocedure/index.rst
deleted file mode 100644
index 41bc079..0000000
--- a/docs/installationprocedure/index.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
- .. (c) <optionally add copywriters name>
-
-**************************************
-Promise installation and configuration
-**************************************
-
-.. toctree::
- :numbered:
- :maxdepth: 2
-
- feature.configuration.rst
diff --git a/docs/release/configguide/feature.configuration.rst b/docs/release/configguide/feature.configuration.rst
new file mode 100644
index 0000000..10696e0
--- /dev/null
+++ b/docs/release/configguide/feature.configuration.rst
@@ -0,0 +1,63 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Manual testing
+==============
+
+Promise installation
+--------------------
+
+Install nodejs, npm and promise
+
+.. code-block:: bash
+
+ curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
+ sudo apt-get install -y nodejs
+ sudo npm -g install npm@latest
+ git clone https://gerrit.opnfv.org/gerrit/promise
+ cd promise/source
+ npm install
+
+Please note that the last command 'npm install' will install all needed dependencies
+for promise (including yangforge and mocha)
+
+.. figure:: images/screenshot_promise_install.png
+ :name: figure1
+ :width: 90%
+
+
+Validation
+----------
+Please perform the following preparation steps:
+
+1. Set OpenStack environment parameters properly (e.g. source openrc admin demo
+ in DevStack)
+2. Create OpenStack tenant (e.g. promise) and tenant user (e.g. promiser)
+3. Create a flavor in Nova with 1 vCPU and 512 MB RAM
+4. Create a private network, subnet and router in Neutron
+5. Create an image in Glance
+
+Once done, the promise test script can be invoked as follows (as a single line
+command):
+
+.. code-block:: bash
+
+ NODE_ENV=mytest \
+ OS_TENANT_NAME=promise \
+ OS_USERNAME=promiser \
+ OS_PASSWORD=<user password from Step 2> \
+ OS_TEST_FLAVOR=<flavor ID from Step 3> \
+ OS_TEST_NETWORK=<network ID from Step 4> \
+ OS_TEST_IMAGE=<image ID from Step 5> \
+ npm run -s test -- --reporter json > promise-results.json
+
+The results of the tests will be stored in the promise-results.json file.
+
+The results can also be seen in the console ("npm run -s test")
+
+.. figure:: images/screenshot_promise.png
+ :name: figure2
+ :width: 90%
+
+All 33 tests passing?!
+Congratulations, promise has been successfully installed and configured.
diff --git a/docs/release/configguide/images/LICENSE b/docs/release/configguide/images/LICENSE
new file mode 100644
index 0000000..6a84dd4
--- /dev/null
+++ b/docs/release/configguide/images/LICENSE
@@ -0,0 +1,14 @@
+Copyright 2016 Open Platform for NFV Project, Inc. and its contributors
+
+Open Platform for NFV Project Documentation Licence
+===================================================
+Any documentation developed by the "Open Platform for NFV Project"
+is licensed under a Creative Commons Attribution 4.0 International License.
+You should have received a copy of the license along with this. If not,
+see <http://creativecommons.org/licenses/by/4.0/>.
+
+Unless required by applicable law or agreed to in writing, documentation
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/docs/release/configguide/images/screenshot_promise.png b/docs/release/configguide/images/screenshot_promise.png
new file mode 100755
index 0000000..4a0cbe3
Binary files /dev/null and b/docs/release/configguide/images/screenshot_promise.png differ
diff --git a/docs/release/configguide/images/screenshot_promise_install.png b/docs/release/configguide/images/screenshot_promise_install.png
new file mode 100644
index 0000000..2cb27d9
Binary files /dev/null and b/docs/release/configguide/images/screenshot_promise_install.png differ
diff --git a/docs/release/configguide/index.rst b/docs/release/configguide/index.rst
new file mode 100644
index 0000000..41bc079
--- /dev/null
+++ b/docs/release/configguide/index.rst
@@ -0,0 +1,13 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+ .. (c) <optionally add copywriters name>
+
+**************************************
+Promise installation and configuration
+**************************************
+
+.. toctree::
+ :numbered:
+ :maxdepth: 2
+
+ feature.configuration.rst
diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst
new file mode 100644
index 0000000..0a32270
--- /dev/null
+++ b/docs/release/userguide/feature.userguide.rst
@@ -0,0 +1,294 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Abstract
+========
+This user guide document provides the users with:
+
+1. Short description of Promise project and key features implemented in
+Danube.
+
+Promise description
+===================
+Promise is a resource reservation and management project to identify NFV related
+requirements and realize resource reservation for future usage by capacity
+management of resource pools regarding compute, network and storage.
+
+The following are the key features provided by this module:
+
+* Capacity Management
+* Reservation Management
+* Allocation Management
+
+Promise capabilities and usage
+==============================
+The Danube implementation of Promise is built with the YangForge data modeling
+framework [#f2]_ , using a shim-layer on top of OpenStack to provide
+the Promise features. This approach requires communication between
+Consumers/Administrators and OpenStack to pass through the shim-layer. The
+shim-layer intercepts the message flow to manage the allocation requests based
+on existing reservations and available capacities in the providers. It also
+extracts information from the intercepted messages in order to update its
+internal databases. Furthermore, Promise provides additional intent-based APIs
+to allow a Consumer or Administrator to perform capacity management (i.e. add
+providers, update the capacity, and query the current capacity and utilization
+of a provider), reservation management (i.e. create, update, cancel, query
+reservations), and allocation management (i.e. create, destroy instances).
+
+Detailed information about Promise use cases, features, interface
+specifications, work flows, and the underlying Promise YANG schema can be found
+in the Promise requirement document [#f1]_ .
+
+Promise features and API usage guidelines and examples
+------------------------------------------------------
+This section lists the Promise features and API implemented in OPNFV Danube.
+
+Note: The listed parameters are optional unless explicitly marked as "mandatory".
+
+Reservation management
+^^^^^^^^^^^^^^^^^^^^^^
+The reservation management allows a Consumer to request reservations for
+resource capacity. Reservations can be for now or a later time window.
+After the start time of a reservation has arrived, the Consumer can issue
+create server instance requests against the reserved capacity. Note, a
+reservation will expire after a predefined *expiry* time in case no
+allocation referring to the reservation is requested.
+
+The implemented workflow is well aligned with the described workflow in the
+Promise requirement document [#f1]_ (Section 6.1) except for the
+"multi-provider" scenario as described in :ref:`multi-provider` .
+
+.. _create-reservation:
+
+*create-reservation*
+""""""""""""""""""""
+
+This operation allows making a request to the reservation system to reserve
+resources.
+
+The operation takes the following input parameters:
+
+* start: start time of the requested reservation
+* end: end time of the requested reservation
+* capacity.instances: amount of instances to be reserved
+* capacity.cores: amount of cores to be reserved
+* capacity.ram: amount of ram in MB to be reserved
+
+Promise will check the available capacity in the given time window and in case
+sufficient capacity exists to meet the reservation request, will mark those
+resources "reserved" in its reservation map.
+
+*update-reservation*
+""""""""""""""""""""
+
+This operation allows to update the reservation details for an existing
+reservation.
+
+It can take the same input parameters as in *create-reservation*
+but in addition requires a mandatory reference to the *reservation-id* of the
+reservation that shall be updated.
+
+*cancel-reservation*
+""""""""""""""""""""
+
+This operation is used to cancel an existing reservation.
+
+The operation takes the following input parameter:
+
+* reservation-id (mandatory): identifier of the reservation to be canceled.
+
+*query-reservation*
+"""""""""""""""""""
+
+The operation queries the reservation system to return reservation(s) matching
+the specified query filter, e.g., reservations that are within a specified
+start/end time window.
+
+The operation takes the following input parameters to narrow down the query
+results:
+
+* without: excludes specified collection identifiers from the result
+* elements.some: query for ResourceCollection(s) that contain some or more of these element(s)
+* elements.every: query for ResourceCollection(s) that contain all of these element(s)
+* window.start: matches entries that are within the specified start/
+* window.end: end time window
+* window.scope: if set to 'exclusive', only reservations with start AND end time
+ within the time window are returned. Otherwise ('inclusive'), all
+ reservation starting OR ending in the time windows are returned.
+* show-utilization: boolean value that specifies whether to also return the
+ resource utilization in the queried time window or not
+
+Allocation management
+^^^^^^^^^^^^^^^^^^^^^
+
+*create-instance*
+"""""""""""""""""
+
+This operation is used to create an instance of specified resource(s) for
+immediate use utilizing capacity from the pool. *Create-instance* requests can
+be issued against an existing reservation, but also allocations without a
+reference to an existing reservation are allowed. In case the allocation
+request specifies a reservation identifier, Promise checks if a reservation
+with that ID exists, the reservation start time has arrived (i.e. the
+reservation is 'active'), and the required capacity for the requested flavor is
+within the available capacity of the reservation. If those conditions are met,
+Promise creates a record for the allocation (VMState="INITIALIZED") and update
+its databases. If no *reservation_id* was provided in the allocation request,
+Promise checks whether the required capacity to meet the request can be
+provided from the available, non-reserved capacity. If yes, Promise creates a
+record for the allocation with an unique *instance-id* and update its
+databases. In any other case, Promise rejects the *create-instance* request.
+
+In case the *create-instance* request is rejected, Promise responds with a
+"status=rejected" providing the reason of the rejection. This will help the
+Consumer to take appropriate actions, e.g., send an updated *create-instance*
+request. In case the *create-instance* request was accepted and a related
+allocation record has been created, the shim-layer issues a *createServer*
+request to the VIM Controller (i.e. Nova) providing all information to create
+the server instance.
+
+The operation takes the following input parameters:
+
+* name (mandatory): Assigned name for the instance to be created
+* image (mandatory): the image to be booted in the new instance
+* flavor (mandatory): the flavor of the requested server instance
+* networks: the list of network uuids of the requested server instance
+* provider-id: identifier of the provider where the instance shall be created
+* reservation-id: identifier of a resource reservation the *create-instance*
+
+The Danube implementation of Promise has the following limitations:
+
+* All create server instance requests shall pass through the Promise
+ shim-layer such that Promise can keep track of all allocation requests. This
+ is necessary as in the current release the sychronization between the VIM
+ Controller and Promise on the available capacity is not yet implemented.
+* *Create-allocation* requests are limited to "simple" allocations, i.e., the
+ current workflow only supports the Nova compute service and
+ *create-allocation* requests are limited to creating one server instance at a
+ time
+* Prioritization of reservations and allocations is yet not implemented.
+ Future version may allow certain policy-based conflict resolution where,
+ e.g., new allocation request with high priority can "forcefully" terminate
+ lower priority allocations.
+
+
+*destroy-instance*
+""""""""""""""""""
+
+This operation request to destroy an existing server instance and release it
+back to the pool.
+
+The operation takes the following input parameter:
+
+* instance-id: identifier of the server instance to be destroyed
+
+Capacity management
+^^^^^^^^^^^^^^^^^^^
+The capacity management feature allows the Consumer or Administrator to do
+capacity planning, i.e. the capacity available to the reservation management
+can differ from the actual capacity in the registered provider(s). This feature
+can, e.g., be used to limit the available capacity for a given time window due
+to a planned downtime of some of the resources, or increase the capacity
+available to the reservation system in case of a planned upgrade of the
+available capacity.
+
+*increase/decrease-capacity*
+""""""""""""""""""""""""""""
+
+This operations allows to increase/decrease the total capacity that is made
+available to the Promise reservation service between a specified window in
+time. It does NOT increase the actual capacity of a given resource provider,
+but is used for capacity management inside Promise.
+
+This feature can be used in different ways, like
+
+* Limit the capacity available to the reservation system to a value below 100%
+ of the available capacity in the VIM, e.g., in order to leave "buffer" in the
+ actual NFVI to be used outside the Promise reservation service.
+
+* Inform the reservation system that, from a given time in the future,
+ additional resources can be reserved, e.g., due to a planned upgrade of the
+ available capacity of the provider.
+
+* Similarily, the "decrease-capacity" can be used to reduce the consumable
+ resources in a given time window, e.g., to prepare for a planned downtime of
+ some of the resources.
+
+* Expose multiple reservation service instances to different consumers sharing
+ the same resource provider.
+
+The operation takes the following input parameters:
+
+* start: start time for the increased/decreased capacity
+* end: end time for the increased/decreased capacity
+* capacity.cores: Increased/decreased amount of cores
+* capacity.ram: Increased/decreased amount of RAM
+* capacity.instances: Increased/decreased amount of instances
+
+Note, increase/decreasing the capacity in Promise is completely transparent to
+the VIM. As such, when increasing the virtual capacity in Promise (e.g. for a
+planned upgrade of the capacity), it is in the responsibility of the
+Consumer/Administrator to ensure sufficient resources in the VIM are available
+at the appropriate time, in order to prevent allocations against reservations
+to fail due to a lack of resources. Therefore, this operations should only be
+used carefully.
+
+
+*query-capacity*
+""""""""""""""""
+
+This operation is used to query the available capacity information of the
+specified resource collection. A filter attribute can be specified to narrow
+down the query results.
+
+The current implementation supports the following filter criteria:
+
+* time window: returns reservations matching the specified window
+
+* window scope: if set to 'exclusive', only reservations with start AND end time
+ within the time window are returned. Otherwise, all reservation starting OR
+ ending in the time windows are returned.
+
+* metric: query for one of the following capacity metrics:
+
+ * 'total': resource pools
+ * 'reserved': reserved resources
+ * 'usage': resource allocations
+ * 'available': remaining capacity, i.e. neither reserved nor allocated
+
+.. _multi-provider:
+
+(Multi-)provider management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This API towards OpenStack allows a Consumer/Administrator to add and remove
+resource providers to Promise. Note, Promise supports a multi-provider
+configuration, however, for Danube, multi-provider support is not yet
+fully supported.
+
+*add-provider*
+""""""""""""""
+
+This operation is used to register a new resource provider into the Promise
+reservation system.
+
+Note, for Danube, the add-provider operation should only be used to
+register one provider with the Promise shim-layer. Further note that currently
+only OpenStack is supported as a provider.
+
+The operation takes the following input parameters:
+
+* provider-type (mandatory) = 'openstack': select a specific resource provider
+ type.
+* endpoint (mandatory): target URL endpoint for the resource provider.
+* username (mandatory)
+* password (mandatory)
+* region: specified region for the provider
+* tenant.id: id of the OpenStack tenant/project
+* tenant.name: name of the OpenStack tenant/project
+
+.. [#f1] Promise requirement document,
+ http://artifacts.opnfv.org/promise/docs/requirements/index.html
+
+.. [#f2] YangForge framework, http://github.com/opnfv/yangforge
+
diff --git a/docs/release/userguide/index.rst b/docs/release/userguide/index.rst
new file mode 100644
index 0000000..f6cb21c
--- /dev/null
+++ b/docs/release/userguide/index.rst
@@ -0,0 +1,12 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+==================
+Promise user guide
+==================
+
+
+.. toctree::
+ :maxdepth: 3
+
+ feature.userguide.rst
diff --git a/docs/requirements/NB_interface.rst b/docs/requirements/NB_interface.rst
deleted file mode 100644
index 8dba601..0000000
--- a/docs/requirements/NB_interface.rst
+++ /dev/null
@@ -1,1061 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-.. _northbound_API:
-
-Detailed northbound interface specification
-===========================================
-
-.. Note::
- This is Work in Progress.
-
-ETSI NFV IFA Information Models
--------------------------------
-
-Compute Flavor
-^^^^^^^^^^^^^^
-
-A compute flavor includes information about number of virtual CPUs, size of
-virtual memory, size of virtual storage, and virtual network interfaces
-[NFVIFA005]_.
-
-.. figure:: images/computeflavor.png
- :name: computeflavor
- :width: 90%
-
-Virtualised Compute Resources
------------------------------
-
-Compute Capacity Management
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Subscribe Compute Capacity Change Event
-"""""""""""""""""""""""""""""""""""""""
-
-Subscription from Consumer to VIM to be notified about compute capacity changes
-
-.. http:post:: /capacity/compute/subscribe
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /capacity/compute/subscribe HTTP/1.1
- Accept: application/json
-
- {
- "zoneId": "12345",
- "computeResourceTypeId": "vcInstances",
- "threshold": {
- "thresholdType" : "absoluteValue",
- "threshold": {
- "capacity_info": "available",
- "condition": "lt",
- "value": 5
- }
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 201 CREATED
- Content-Type: application/json
-
- {
- "created": "2015-09-21T00:00:00Z",
- "capacityChangeSubscriptionId": "abcdef-ghijkl-123456789"
- }
-
- :statuscode 400: computeResourceTypeId is missing
-
-Query Compute Capacity for a defined resource type
-""""""""""""""""""""""""""""""""""""""""""""""""""
-
-Request to find out about available, reserved, total and allocated compute
-capacity.
-
-.. http:get:: /capacity/compute/query
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- GET /capacity/compute/query HTTP/1.1
- Accept: application/json
-
- {
- "zoneId": "12345",
- "computeResourceTypeId": "vcInstances",
- "timePeriod": {
- "startTime": "2015-09-21T00:00:00Z",
- "stopTime": "2015-09-21T00:05:30Z"
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "zoneId": "12345",
- "lastUpdate": "2015-09-21T00:03:20Z",
- "capacityInformation": {
- "available": 4,
- "reserved": 17,
- "total": 50,
- "allocated": 29
- }
- }
-
- :query limit: Default is 10.
- :statuscode 404: resource zone unknown
-
-
-Query Compute Capacity with required attributes
-"""""""""""""""""""""""""""""""""""""""""""""""
-Request to find out available compute capacity with given characteristics
-
-.. http:get:: /capacity/compute/query
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- GET /capacity/compute/query HTTP/1.1
- Accept: application/json
-
- {
- "zoneId": "12345",
- "resourceCriteria": {
- "virtualCPU": {
- "cpuArchitecture": "x86",
- "numVirtualCpu": 8
- }
- },
- "attributeSelector": "available",
- "timePeriod": {
- "startTime": "2015-09-21T00:00:00Z",
- "stopTime": "2015-09-21T00:05:30Z"
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "zoneId": "12345",
- "lastUpdate": "2015-09-21T00:03:20Z",
- "capacityInformation": {
- "available": 50
- }
- }
-
- :query limit: Default is 10.
- :statuscode 404: resource zone unknown
-
-Notify Compute Capacity Change Event
-""""""""""""""""""""""""""""""""""""
-
-Notification about compute capacity changes
-
-.. http:post:: /capacity/compute/notification
- :noindex:
-
- **Example notification**:
-
- .. sourcecode:: http
-
- Content-Type: application/json
-
- {
- "zoneId": "12345",
- "notificationId": "zyxwvu-tsrqpo-987654321",
- "capacityChangeTime": "2015-09-21T00:03:20Z",
- "resourceDescriptor": {
- "computeResourceTypeId": "vcInstances"
- },
- "capacityInformation": {
- "available": 4,
- "reserved": 17,
- "total": 50,
- "allocated": 29
- }
- }
-
-Compute Resource Reservation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Create Compute Resource Reservation
-"""""""""""""""""""""""""""""""""""
-
-Request the reservation of compute resource capacity
-
-.. http:post:: /reservation/compute/create
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /reservation/compute/create HTTP/1.1
- Accept: application/json
-
- {
- "startTime": "2015-09-21T01:00:00Z",
- "computePoolReservation": {
- "numCpuCores": 20,
- "numVcInstances": 5,
- "virtualMemSize": 10
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 201 CREATED
- Content-Type: application/json
-
- {
- "reservationData": {
- "startTime": "2015-09-21T01:00:00Z",
- "reservationStatus": "initialized",
- "reservationId": "xxxx-yyyy-zzzz",
- "computePoolReserved": {
- "numCpuCores": 20,
- "numVcInstances": 5,
- "virtualMemSize": 10,
- "zoneId": "23456"
- }
- }
- }
-
-or virtualization containers
-
-.. http:post:: reservation/compute/create
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /reservation/compute/create HTTP/1.1
- Accept: application/json
-
- {
- "startTime": "2015-10-05T15:00:00Z",
- "virtualizationContainerReservation": [
- {
- "containerId": "myContainer",
- "containerFlavor": {
- "flavorId": "myFlavor",
- "virtualCpu": {
- "numVirtualCpu": 2,
- "cpuArchitecture": "x86"
- },
- "virtualMemory": {
- "numaEnabled": "False",
- "virtualMemSize": 16
- },
- "storageAttributes": {
- "typeOfStorage": "volume",
- "sizeOfStorage": 16
- }
- }
- }
- ]
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 201 CREATED
- Content-Type: application/json
-
- {
- "reservationData": {
- "startTime": "2015-10-05T15:00:00Z",
- "reservationId": "aaaa-bbbb-cccc",
- "reservationStatus": "initialized",
- "virtualizationContainerReserved": [
- {
- "containerId": "myContainer",
- "flavorId": "myFlavor",
- "virtualCpu": {
- "numVirtualCpu": 2,
- "cpuArchitecture": "x86"
- },
- "virtualMemory": {
- "numaEnabled": "False",
- "virtualMemSize": 16
- },
- "virtualDisks": {
- "storageId": "myStorage",
- "flavourId": "myStorageFlavour",
- "typeOfStorage": "volume",
- "sizeOfStorage": 16,
- "operationalState": "enabled"
- }
- }
- ]
- }
- }
-
-
-
-Query Compute Resource Reservation
-""""""""""""""""""""""""""""""""""
-
-Request to find out about reserved compute resources that the consumer has
-access to.
-
-.. http:get:: /reservation/compute/query
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- GET /reservation/compute/query HTTP/1.1
- Accept: application/json
-
- {
- "queryReservationFilter": [
- {
- "reservationId": "xxxx-yyyy-zzzz"
- }
- ]
-
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "queryResult":
- {
- "startTime": "2015-09-21T01:00:00Z",
- "reservationStatus": "active",
- "reservationId": "xxxx-yyyy-zzzz",
- "computePoolReserved":
- {
- "numCpuCores": 20,
- "numVcInstances": 5,
- "virtualMemSize": 10,
- "zoneId": "23456"
- }
- }
- }
-
- :statuscode 404: reservation id unknown
-
-Update Compute Resource Reservation
-"""""""""""""""""""""""""""""""""""
-
-Request to update compute resource reservation
-
-.. http:post:: /reservation/compute/update
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /reservation/compute/update HTTP/1.1
- Accept: application/json
-
- {
- "startTime": "2015-09-14T16:00:00Z",
- "reservationId": "xxxx-yyyy-zzzz"
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 201 CREATED
- Content-Type: application/json
-
- {
- "reservationData": {
- "startTime": "2015-09-14TT16:00:00Z",
- "reservationStatus": "active",
- "reservationId": "xxxx-yyyy-zzzz",
- "computePoolReserved": {
- "numCpuCores": 20,
- "numVcInstances": 5,
- "virtualMemSize": 10,
- "zoneId": "23456"
- }
- }
- }
-
-Terminate Compute Resource Reservation
-""""""""""""""""""""""""""""""""""""""
-
-Request to terminate a compute resource reservation
-
-.. http:delete:: /reservation/compute/(reservation_id)
- :noindex:
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200
- Content-Type: application/json
-
- {
- "reservationId": "xxxx-yyyy-zzzz",
- }
-
-
-Subscribe Resource Reservation Change Event
-"""""""""""""""""""""""""""""""""""""""""""
-
-Subscription from Consumer to VIM to be notified about changes
-related to a reservation or to the resources associated to it.
-
-.. http:post:: /reservation/subscribe
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /reservation/subscribe HTTP/1.1
- Accept: application/json
-
- {
- "inputFilter": [
- {
- "reservationId": "xxxx-yyyy-zzzz",
- }
- ]
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 201 CREATED
- Content-Type: application/json
-
- {
- "created": "2015-09-21T00:00:00Z",
- "reservationChangeSubscriptionId": "abcdef-ghijkl-123456789"
- }
-
- :statuscode 400: inputFilter is missing
-
-
-Notify Resource Reservation Change Event
-""""""""""""""""""""""""""""""""""""""""
-
-Notification about changes in a compute resource reservation
-
-.. http:post:: /capacity/compute/notification
- :noindex:
-
- **Example notification**:
-
- .. sourcecode:: http
-
- Content-Type: application/json
-
- {
- "changeId": "aaaaaa-btgxxx-987654321",
- "reservationId": "xxxx-yyyy-zzzz",
- "vimId": "vim-CX-03"
- "changeType": "Reservation time change"
- "changedReservationData": {
- "endTime": "2015-10-14TT16:00:00Z",
- }
- }
-
-
-
-Virtualised Network Resources
------------------------------
-
-Network Capacity Management
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Subscribe Network Capacity Change Event
-"""""""""""""""""""""""""""""""""""""""
-
-Susbcription from Consumer to VIM to be notified about network capacity changes
-
-.. http:post:: /capacity/network/subscribe
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /capacity/network/subscribe HTTP/1.1
- Accept: application/json
-
- {
- "networkResourceTypeId": "publicIps",
- "threshold": {
- "thresholdType": "absoluteValue",
- "threshold": {
- "capacity_info": "available",
- "condition": "lt",
- "value": 5
- }
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 201 CREATED
- Content-Type: application/json
-
- {
- "created": "2015-09-28T00:00:00Z",
- "capacityChangeSubscriptionId": "bcdefg-hijklm-234567890"
- }
-
-Query Network Capacity
-""""""""""""""""""""""
-
-Request to find out about available, reserved, total and allocated network
-capacity.
-
-.. http:get:: /capacity/network/query
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- GET /capacity/network/query HTTP/1.1
- Accept: application/json
-
- {
- "networkResourceTypeId": "publicIps",
- "timePeriod": {
- "startTime": "2015-09-28T00:00:00Z",
- "stopTime": "2015-09-28T00:05:30Z"
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "lastUpdate": "2015-09-28T00:02:10Z",
- "capacityInformation": {
- "available": 4,
- "reserved": 10,
- "total": 64,
- "allocated": 50
- }
- }
-
-Notify Network Capacity Change Event
-""""""""""""""""""""""""""""""""""""
-
-Notification about network capacity changes
-
-.. http:post:: /capacity/network/notification
- :noindex:
-
- **Example notification**:
-
- .. sourcecode:: http
-
- Content-Type: application/json
-
- {
- "notificationId": "yxwvut-srqpon-876543210",
- "capacityChangeTime": "2015-09-28T00:02:10Z",
- "resourceDescriptor": {
- "networkResourceTypeId": "publicIps"
- },
- "capacityInformation": {
- "available": 4,
- "reserved": 10,
- "total": 64,
- "allocated": 50
- }
- }
-
-Network Resource Reservation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Create Network Resource Reservation
-"""""""""""""""""""""""""""""""""""
-
-Request the reservation of network resource capacity and/or virtual networks,
-network ports
-
-.. http:post:: /reservation/network/create
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /reservation/network/create HTTP/1.1
- Accept: application/json
-
- {
- "startTime": "2015-09-28T01:00:00Z",
- "networkReservation": {
- "numPublicIps": 2
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 201 CREATED
- Content-Type: application/json
-
- {
- "reservationData": {
- "startTime": "2015-09-28T01:00:00Z",
- "reservationStatus": "initialized",
- "reservationId": "wwww-xxxx-yyyy",
- "publicIps": [
- "10.2.91.60",
- "10.2.91.61"
- ]
- }
- }
-
-Query Network Resource Reservation
-""""""""""""""""""""""""""""""""""
-
-Request to find out about reserved network resources that the consumer has
-access to.
-
-.. http:get:: /reservation/network/query
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- GET /reservation/network/query HTTP/1.1
- Accept: application/json
-
- {
- "queryReservationFilter": [
- {
- "reservationId": "wwww-xxxx-yyyy"
- }
- ]
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "queryResult": {
- "startTime": "2015-09-28T01:00:00Z",
- "reservationStatus": "active",
- "reservationId": "wwww-xxxx-yyyy",
- "publicIps": [
- "10.2.91.60",
- "10.2.91.61"
- ]
- }
- }
-
-Update Network Resource Reservation
-"""""""""""""""""""""""""""""""""""
-
-Request to update network resource reservation
-
-.. http:post:: /reservation/network/update
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /reservation/network/update HTTP/1.1
- Accept: application/json
-
- {
- "startTime": "2015-09-21T16:00:00Z",
- "reservationId": "wwww-xxxx-yyyy"
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 201 CREATED
- Content-Type: application/json
-
- {
- "reservationData": {
- "startTime": "2015-09-21T16:00:00Z",
- "reservationStatus": "active",
- "reservationId": "wwww-xxxx-yyyy",
- "publicIps": [
- "10.2.91.60",
- "10.2.91.61"
- ]
- }
- }
-
-Terminate Network Resource Reservation
-""""""""""""""""""""""""""""""""""""""
-
-Request to terminate a network resource reservation
-
-.. http:delete:: /reservation/network/(reservation_id)
- :noindex:
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200
- Content-Type: application/json
-
- {
- "reservationId": "xxxx-yyyy-zzzz",
- }
-
-Virtualised Storage Resources
------------------------------
-
-Storage Capacity Management
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Subscribe Storage Capacity Change Event
-"""""""""""""""""""""""""""""""""""""""
-
-Subscription from Consumer to VIM to be notified about storage capacity changes
-
-.. http:post:: /capacity/storage/subscribe
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /capacity/storage/subscribe HTTP/1.1
- Accept: application/json
-
- {
- "storageResourceTypeId": "volumes",
- "threshold": {
- "thresholdType": "absoluteValue",
- "threshold": {
- "capacity_info": "available",
- "condition": "lt",
- "value": 3
- }
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 201 CREATED
- Content-Type: application/json
-
- {
- "created": "2015-09-28T12:00:00Z",
- "capacityChangeSubscriptionId": "cdefgh-ijklmn-345678901"
- }
-
-Query Storage Capacity for a defined resource type
-""""""""""""""""""""""""""""""""""""""""""""""""""
-
-Request to find out about available, reserved, total and allocated storage
-capacity.
-
-.. http:get:: /capacity/storage/query
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- GET /capacity/storage/query HTTP/1.1
- Accept: application/json
-
- {
- "storageResourceTypeId": "volumes",
- "timePeriod": {
- "startTime": "2015-09-28T12:00:00Z",
- "stopTime": "2015-09-28T12:04:45Z"
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "lastUpdate": "2015-09-28T12:01:35Z",
- "capacityInformation": {
- "available": 2,
- "reserved": 4,
- "total": 10,
- "allocated": 4
- }
- }
-
-Query Storage Capacity with required attributes
-"""""""""""""""""""""""""""""""""""""""""""""""
-
-Request to find out available capacity.
-
-.. http:get:: /capacity/storage/query
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- GET /capacity/storage/query HTTP/1.1
- Accept: application/json
-
- {
- "resourceCriteria": {
- "typeOfStorage" : "volume",
- "sizeOfStorage" : 200,
- "rdmaSupported" : "True",
- },
- "attributeSelector": "available",
- "timePeriod": {
- "startTime": "2015-09-28T12:00:00Z",
- "stopTime": "2015-09-28T12:04:45Z"
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "lastUpdate": "2015-09-28T12:01:35Z",
- "capacityInformation": {
- "available": 2
- }
- }
-
-Notify Storage Capacity Change Event
-""""""""""""""""""""""""""""""""""""
-
-Notification about storage capacity changes
-
-.. http:post:: /capacity/storage/notification
- :noindex:
-
- **Example notification**:
-
- .. sourcecode:: http
-
- Content-Type: application/json
-
- {
- "notificationId": "xwvuts-rqponm-765432109",
- "capacityChangeTime": "2015-09-28T12:01:35Z",
- "resourceDescriptor": {
- "storageResourceTypeId": "volumes"
- },
- "capacityInformation": {
- "available": 2,
- "reserved": 4,
- "total": 10,
- "allocated": 4
- }
- }
-
-Storage Resource Reservation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Create Storage Resource Reservation
-"""""""""""""""""""""""""""""""""""
-
-Request the reservation of storage resource capacity
-
-.. http:post:: /reservation/storage/create
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /reservation/storage/create HTTP/1.1
- Accept: application/json
-
- {
- "startTime": "2015-09-28T13:00:00Z",
- "storagePoolReservation": {
- "storageSize": 10,
- "numSnapshots": 3,
- "numVolumes": 2
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 201 CREATED
- Content-Type: application/json
-
- {
- "reservationData": {
- "startTime": "2015-09-28T13:00:00Z",
- "reservationStatus": "initialized",
- "reservationId": "vvvv-wwww-xxxx",
- "storagePoolReserved": {
- "storageSize": 10,
- "numSnapshots": 3,
- "numVolumes": 2
- }
- }
- }
-
-Query Storage Resource Reservation
-""""""""""""""""""""""""""""""""""
-
-Request to find out about reserved storage resources that the consumer has
-access to.
-
-.. http:get:: /reservation/storage/query
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- GET /reservation/storage/query HTTP/1.1
- Accept: application/json
-
- {
- "queryReservationFilter": [
- {
- "reservationId": "vvvv-wwww-xxxx"
- }
- ]
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "queryResult": {
- "startTime": "2015-09-28T13:00:00Z",
- "reservationStatus": "active",
- "reservationId": "vvvv-wwww-xxxx",
- "storagePoolReserved": {
- "storageSize": 10,
- "numSnapshots": 3,
- "numVolumes": 2
- }
- }
- }
-
-Update Storage Resource Reservation
-"""""""""""""""""""""""""""""""""""
-
-Request to update storage resource reservation
-
-.. http:post:: /reservation/storage/update
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /reservation/storage/update HTTP/1.1
- Accept: application/json
-
-
- {
- "startTime": "2015-09-20T23:00:00Z",
- "reservationId": "vvvv-wwww-xxxx"
-
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 201 CREATED
- Content-Type: application/json
-
- {
- "reservationData": {
- "startTime": "2015-09-20T23:00:00Z",
- "reservationStatus": "active",
- "reservationId": "vvvv-wwww-xxxx",
- "storagePoolReserved": {
- "storageSize": 10,
- "numSnapshots": 3,
- "numVolumes": 2
- }
- }
- }
-
-Terminate Storage Resource Reservation
-""""""""""""""""""""""""""""""""""""""
-
-Request to terminate a storage resource reservation
-
-.. http:delete:: /reservation/storage/(reservation_id)
- :noindex:
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200
- Content-Type: application/json
-
- {
- "reservationId": "xxxx-yyyy-zzzz",
- }
diff --git a/docs/requirements/annex1.rst b/docs/requirements/annex1.rst
deleted file mode 100644
index 65a5f22..0000000
--- a/docs/requirements/annex1.rst
+++ /dev/null
@@ -1,37 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-.. _uc-brahmaputra:
-
-ANNEX A: Use case for OPNFV Brahmaputra
-=======================================
-
-A basic resource reservation use case to be realized for OPNFV B-release may
-look as follows:
-
-* Step 0: Shim-layer is monitoring/querying available capacity at NFVI
-
- * Step 0a: Cloud operator creates a new OpenStack tenant user and updates
- quota values for this user
-
- * Step 0b: The tenant user is creating and instantiating a simple VNF
- (e.g. 1 network, 2 VMs)
-
- * Step 0c: OpenStack is notifying shim-layer about capacity change for
- this new tenant user
-
- * Step 0d: Cloud operator can visualize the changes using the GUI
-
-* Step 1: Consumer(NFVO) is sending a reservation request for future use to
- shim-layer
-
-* Step 2: Shim-layer is checking for available capacity at the given time
- window
-
-* Step 3: Shim-layer is responding with reservation identifier
-
-* Step 4 (optional): Consumer(NFVO) is sending an update reservation request
- to shim-layer (startTime set to now) -> continue with Steps 2 and 3.
-
-* Step 5: Consumer(VNFM) is requesting the allocation of virtualised resources
- using the reservation identifier in Step 3
diff --git a/docs/requirements/architecture.rst b/docs/requirements/architecture.rst
deleted file mode 100644
index 3eb20d3..0000000
--- a/docs/requirements/architecture.rst
+++ /dev/null
@@ -1,258 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-============================================
-High level architecture and general features
-============================================
-
-Architecture Overview
-=====================
-
-.. figure:: images/figure1.png
- :name: figure1
- :width: 90%
-
- Resource Reservation Architecture
-
-:numref:`figure1` shows the high level architecture for the resource reservation
-use cases. Reserved resources are guaranteed for a given user/client for the
-period expressed by start and end time. User/client represents the requestor
-and the consequent consumer of the reserved resources and correspond to the
-NFVO or VNFM in ETSI NFV terminology.
-
-Note: in this document only reservation requests from NFVO are considered.
-
-General Features
-================
-
-This section provides a list of features that need to be developed in the
-Promise project.
-
-* Resource capacity management
-
- * Discovery of available resource capacity in resource providers
- * Monitoring of available resource capacity in resource providers
- * Update available resource capacity as a result of new or expired
- reservations, addition/removal of resources. Note: this is a VIM internal
- function, not an operation in the VIM northbound interface.
-
-* Resource reservation
-
- * Set start time and end time for allocation
- * Increase/decrease reserved resource's capacity
- * Update resource reservations, e.g. add/remove reserved resources
- * Terminate an allocated resource due to the end time of a reservation
-
-* VIM northbound interfaces
-
- * Receive/Reply resource reservation requests
- * Receive/Reply resource capacity management requests
- * Receive/Reply resource allocation requests for reserved resources when
- start time arrives
- * Subscribe/Notify resource reservation event
-
- * Notify reservation error or process completion prior to reservation
- start
- * Notify remaining time until termination of a resource due to the end
- time of a reservation
- * Notify termination of a resource due to the end time of a reservation
-
- * Receive/Reply queries on available resource capacity
- * Subscribe/Notify changes in available resource capacity
-
-High level northbound interface specification
-=============================================
-
-Resource Capacity Management
-----------------------------
-
-.. figure:: images/figure2.png
- :name: figure2
- :width: 90%
-
- Resource capacity management message flow: notification of capacity change
-
-:numref:`figure2` shows a high level flow for a use case of resource capacity
-management. In this example, the VIM notifies the NFVO of capacity change after
-having received an event regarding a change in capacity (e.g. a fault
-notification) from the NFVI. The NFVO can also retrieve detailed capacity
-information using the Query Capacity Request interface operation.
-
-.. figure:: images/figure3.png
- :name: figure3
- :width: 90%
-
- Resource capacity management message flow: query of capacity density
-
-:numref:`figure3` shows a high level flow for another use case of resource
-capacity management. In this example, the NFVO queries the VIM about the actual
-capacity to instantiate a certain resource according to a certain template, for
-example a VM according to a certain flavor. In this case the VIM responds with
-the number of VMs that could be instantiated according to that flavor with the
-currently available capacity.
-
-Resource Reservation
---------------------
-
-.. figure:: images/figure4.png
- :name: figure4
- :width: 90%
-
- Resource reservation flow
-
-:numref:`figure4` shows a high level flow for a use case of resource
-reservation. The main steps are:
-
-* The NFVO sends a resource reservation request to the VIM using the Create
- Resource Reservation Request interface operation.
-* The NFVO gets a reservation identifier reservation associated with this
- request in the reply message
-* Using the reservation identifier reservation, the NFVO can
- query/update/terminate a resource reservation using the corresponding
- interface operations
-* The NFVO is notified that the resource reservation is terminated due to the
- end time of the reservation
-
-
-Information elements
-====================
-
-Resource Capacity Management
-----------------------------
-
-Notify Capacity Change Event
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The notification change message shall include the following information elements:
-
-============================ ========== =====================================
-Name Type Description
-============================ ========== =====================================
-Notification Identifier Identifier issued by the VIM for the
- capacity change event notification
-Zone Identifier Identifier of the zone where capacity
- has changed
-Used/Reserved/Total Capacity List Used, reserved and total capacity
- information regarding the resource
- items subscribed for notification for
- which capacity change event occurred
-============================ ========== =====================================
-
-Query Resource Capacity Request
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The capacity management query request message shall include the following
-information elements:
-
-========== ========== ======================================================
-Name Type Description
-========== ========== ======================================================
-Zone Identifier Identifier of the zone where capacity is requested
-Attributes List Attributes of resource items to be notified regarding
- capacity change events
-Resources List Identifiers of existing resource items to be queried
- regarding capacity info (such as images, flavors,
- virtual containers, networks, physical machines, etc.)
-========== ========== ======================================================
-
-The capacity management query request message may also include the following
-information element:
-
-====== ========== ==========================================================
-Name Type Description
-====== ========== ==========================================================
-Flavor Identifier Identifier that is passed in the request to obtain
- information of the number of virtual resources that can be
- instantiated according to this flavor with the available
- capacity
-====== ========== ==========================================================
-
-Query Resource Capacity Reply
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The capacity management query reply message shall include the following
-information elements:
-
-============================ ========== =====================================
-Name Type Description
-============================ ========== =====================================
-Zone Identifier Identifier of the zone where capacity
- is requested
-Used/Reserved/Total Capacity List Used, reserved and total capacity
- information regarding each of the
- resource items requested to check for
- capacity
-============================ ========== =====================================
-
-The detailed specification of the northbound interface for Capacity Management
-in provided in section 5.1.1.
-
-Resource Reservation
---------------------
-
-Create Resource Reservation Request
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The create resource reservation request message shall include the following
-information elements:
-
-========== ========== =========================================================
-Name Type Description
-========== ========== =========================================================
-Start Timestamp Start time for consumption of the reserved resources
-End Timestamp End time for consumption of the reserved resources
-Expiry Timestamp If not all reserved resources are allocated between start
- time and expiry, the VIM shall release the corresponding
- resources [#expiry]_
-Amount Number Amount of the resources per resource item type (i.e.
- compute/network/storage) that need to be reserved
-Zone Identifier The zone where the resources need(s) to be reserved
-Attributes List Attributes of the resources to be reserved such as DPDK
- support, hypervisor, network link bandwidth, affinity
- rules, etc.
-Resources List Identifiers of existing resource items to be reserved
- (such as images, flavors, virtual containers, networks,
- physical machines, etc.)
-========== ========== =========================================================
-
-.. [#expiry] Expiry is a period around start time within which, the allocation
- process must take place. If allocation process does not start
- within the expiry period, the reservation becomes invalid and VIM
- should release the resources
-
-Create Resource Reservation Reply
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The create resource reservation reply message shall include the following
-information elements:
-
-=========== ========== =======================================================
-Name Type Description
-=========== ========== =======================================================
-Reservation Identifier Identification of the reservation instance. It can be
- used by a consumer to modify the reservation later, and
- to request the allocation of the reserved resources.
-Message Text Output message that provides additional information
- about the create resource reservation request (e.g. may
- be a simple ACK if the request is being background
- processed by the VIM)
-=========== ========== =======================================================
-
-Notify Reservation Event
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-The notification reservation event message shall include the following
-information elements:
-
-============ ========== =====================================================
-Name Type Description
-============ ========== =====================================================
-Reservation Identifier Identification of the reservation instance triggering
- the event
-Notification Identifier Identification of the resource event notification
- issued by the VIM
-Message Text Message describing the event
-============ ========== =====================================================
-
-The detailed specification of the northbound interface for Resource Reservation
-is provided in section 5.1.2.
diff --git a/docs/requirements/gap_analysis.rst b/docs/requirements/gap_analysis.rst
deleted file mode 100644
index 9e4ec5c..0000000
--- a/docs/requirements/gap_analysis.rst
+++ /dev/null
@@ -1,99 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-=================================
-Gap analysis in upstream projects
-=================================
-
-This section provides a list of gaps in upstream projects for realizing
-resource reservation and management. The gap analysis work focuses on the
-current OpenStack Blazar project [BLAZAR]_ in this first release.
-
-OpenStack
-=========
-
-Resource reservation for future use
------------------------------------
-
-* Category: Blazar
-* Type: 'missing' (lack of functionality)
-* Description:
-
- * To-be: To reserve a whole set of compute/storage/network resources in the
- future
- * As-is: Blazar currently can do only compute resource reservation by using
- "Shelved VM"
-
-* Related blueprints:
-
- * https://blueprints.launchpad.net/blazar/+spec/basic-volume-plugin
- * https://blueprints.launchpad.net/blazar/+spec/basic-network-plugin
- * It was planned in Blazar to implement volume and network/fixed ip
- reservations
-
-Resource reservation update
----------------------------
-
-* Category: Blazar
-* Type: 'missing' (lack of functionality)
-* Description:
-
- * To-be: Have the possibility of adding/removing resources to an existing
- reservation, e..g in case of NFVI failure
- * As-is: Currently in Blazar, a reservation can only be modified in terms of
- start/end time
-
-* Related blueprints: N/A
-
-Give me an offer
-----------------
-
-* Category: Blazar
-* Type: 'missing' (lack of functionality)
-* Description:
-
- * To-be: To have the possibility of giving a quotation to a requesting user
- and an expiration time. Reserved resources shall be released if they are
- not claimed before this expiration time.
- * As-is: Blazar can already send notification e.g. to inform a given user
- that a reservation is about to expire
-
-* Related blueprints: N/A
-
-StormStack StormForge
----------------------
-
-Stormify
-^^^^^^^^
-* Stormify enables rapid web applications construction
-* Based on Ember.js style Data stores
-* Developed on Node.js using coffeescript/javascript
-* Auto RESTful API generation based on Data Models
-* Development starts with defining Data Models
-* Code hosted at github : http://github.com/stormstack/stormify
-
-StormForge
-^^^^^^^^^^
-* Data Model driven management of Resource Providers
-* Based on Stormify Framework and implemented as per the OPNFV Promise
- requirements
-* Data Models are auto generated and RESTful API code from YANG schema
-* Currently planned key services include Resource Capacity Management Service
- and Resource Reservation Service
-* List of YANG schemas for Promise project is attached in the Appendix
-* Code hosted at github: http://github.com/stormstack/stormforge
-
-Resource Discovery
-^^^^^^^^^^^^^^^^^^
-* Category: StormForge
-* Type: 'planning' (lack of functionality)
-* Description
-
- * To-be: To be able to discover resources in real time from OpenStack
- components. Planning to add OpenStack Project to interface with Promise for
- real time updates on capacity or any failures
- * As-is: Currently, resource capacity is learnt using NB APIs related to
- quota
-
-* Related Blueprints: N/A
-
diff --git a/docs/requirements/glossary.rst b/docs/requirements/glossary.rst
deleted file mode 100644
index 48fd75b..0000000
--- a/docs/requirements/glossary.rst
+++ /dev/null
@@ -1,73 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-===================
-Definition of terms
-===================
-
-Different SDOs and communities use different terminology related to
-NFV/Cloud/SDN. This list tries to define an OPNFV terminology,
-mapping/translating the OPNFV terms to terminology used in other contexts.
-
-.. glossary::
-
- Administrator
- Administrator of the system, e.g. OAM in Telco context.
-
- Consumer
- User-side Manager; consumer of the interfaces produced by the VIM; VNFM,
- NFVO, or Orchestrator in ETSI NFV [NFV003]_ terminology.
-
- NFV
- Network Function Virtualization
-
- NFVI
- Network Function Virtualization Infrastructure; totality of all hardware
- and software components which build up the environment in which VNFs are
- deployed.
-
- NFVO
- Network Functions Virtualization Orchestrator; functional block that
- manages the Network Service (NS) lifecycle and coordinates the management
- of NS lifecycle, VNF lifecycle (supported by the VNFM) and NFVI resources
- (supported by the VIM) to ensure an optimized allocation of the necessary
- resources and connectivity.
-
- Physical resource
- Actual resources in NFVI; not visible to Consumer.
-
- Resource zone
- A set of NFVI hardware and software resources logically grouped
- according to physical isolation and redundancy capabilities or to
- certain administrative policies for the NFVI [NFVIFA010]_
-
- VIM
- Virtualized Infrastructure Manager; functional block that is responsible
- for controlling and managing the NFVI compute, storage and network
- resources, usually within one operator's Infrastructure Domain, e.g. NFVI
- Point of Presence (NFVI-PoP).
-
- Virtual Machine (VM)
- Virtualized computation environment that behaves very much like a physical
- computer/server.
-
- Virtual network
- Virtual network routes information among the network interfaces of VM
- instances and physical network interfaces, providing the necessary
- connectivity.
-
- Virtual resource
- A Virtual Machine (VM), a virtual network, or virtualized storage; Offered
- resources to "Consumer" as result of infrastructure virtualization;
- visible to Consumer.
-
- Virtual Storage
- Virtualized non-volatile storage allocated to a VM.
-
- VNF
- Virtualized Network Function. Implementation of an Network Function that
- can be deployed on a Network Function Virtualization Infrastructure (NFVI).
-
- VNFM
- Virtualized Network Function Manager; functional block that is responsible
- for the lifecycle management of VNF.
diff --git a/docs/requirements/images/LICENSE b/docs/requirements/images/LICENSE
deleted file mode 100644
index 3b8719c..0000000
--- a/docs/requirements/images/LICENSE
+++ /dev/null
@@ -1,14 +0,0 @@
-Copyright 2015 Open Platform for NFV Project, Inc. and its contributors
-
-Open Platform for NFV Project Documentation Licence
-===================================================
-Any documentation developed by the "Open Platform for NFV Project"
-is licensed under a Creative Commons Attribution 4.0 International License.
-You should have received a copy of the license along with this. If not,
-see <http://creativecommons.org/licenses/by/4.0/>.
-
-Unless required by applicable law or agreed to in writing, documentation
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
diff --git a/docs/requirements/images/computeflavor.png b/docs/requirements/images/computeflavor.png
deleted file mode 100755
index 3ea3dba..0000000
Binary files a/docs/requirements/images/computeflavor.png and /dev/null differ
diff --git a/docs/requirements/images/figure1.png b/docs/requirements/images/figure1.png
deleted file mode 100644
index 065a995..0000000
Binary files a/docs/requirements/images/figure1.png and /dev/null differ
diff --git a/docs/requirements/images/figure2.png b/docs/requirements/images/figure2.png
deleted file mode 100755
index dd002a2..0000000
Binary files a/docs/requirements/images/figure2.png and /dev/null differ
diff --git a/docs/requirements/images/figure3.png b/docs/requirements/images/figure3.png
deleted file mode 100755
index 20e51c7..0000000
Binary files a/docs/requirements/images/figure3.png and /dev/null differ
diff --git a/docs/requirements/images/figure4.png b/docs/requirements/images/figure4.png
deleted file mode 100755
index e0c96a1..0000000
Binary files a/docs/requirements/images/figure4.png and /dev/null differ
diff --git a/docs/requirements/images/figure5.png b/docs/requirements/images/figure5.png
deleted file mode 100755
index 4e161f4..0000000
Binary files a/docs/requirements/images/figure5.png and /dev/null differ
diff --git a/docs/requirements/images/figure5_new.png b/docs/requirements/images/figure5_new.png
deleted file mode 100644
index 9307aa2..0000000
Binary files a/docs/requirements/images/figure5_new.png and /dev/null differ
diff --git a/docs/requirements/images/figure6.png b/docs/requirements/images/figure6.png
deleted file mode 100755
index 8aeec23..0000000
Binary files a/docs/requirements/images/figure6.png and /dev/null differ
diff --git a/docs/requirements/images/figure6_new.png b/docs/requirements/images/figure6_new.png
deleted file mode 100644
index 5ec4b43..0000000
Binary files a/docs/requirements/images/figure6_new.png and /dev/null differ
diff --git a/docs/requirements/images/figure7_new.png b/docs/requirements/images/figure7_new.png
deleted file mode 100644
index 6684949..0000000
Binary files a/docs/requirements/images/figure7_new.png and /dev/null differ
diff --git a/docs/requirements/impl_architecture.rst b/docs/requirements/impl_architecture.rst
deleted file mode 100644
index d7375d5..0000000
--- a/docs/requirements/impl_architecture.rst
+++ /dev/null
@@ -1,313 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-Detailed architecture and message flows
-=======================================
-
-Within the Promise project we consider two different architectural options, i.e.
-a *shim-layer* based architecture and an architecture targeting at full
-OpenStack *integration*.
-
-Shim-layer architecture
------------------------
-
-The *shim-layer architecture* is using a layer on top of OpenStack to provide
-the capacity management, resource reservation, and resource allocation features.
-
-
-Detailed Message Flows
-^^^^^^^^^^^^^^^^^^^^^^
-
-Note, that only selected parameters for the messages are shown. Refer to
-:ref:`northbound_API` and Annex :ref:`yang_schema` for a full set of message
-parameters.
-
-Resource Capacity Management
-""""""""""""""""""""""""""""
-
-.. figure:: images/figure5_new.png
- :name: figure5
- :width: 90%
-
- Capacity Management Scenario
-
-:numref:`figure5` shows a detailed message flow between the consumers and the
-capacity management functional blocks inside the shim-layer. It has the
-following steps:
-
- * Step 1a: The Consumer sends a *query-capacity* request to Promise
- using some filter like time-windows or resource type. The capacity is
- looked up in the shim-layer capacity map.
-
- * Step 1b: The shim-layer will respond with information about the
- total, available, reserved, and used (allocated) capacities matching the
- filter.
-
- * Step 2a: The Consumer can send *increase/decrease-capacity* requests
- to update the capacity available to the reservation system. It can be
- 100% of available capacity in the given provider/source or only a subset,
- i.e., it can allow for leaving some "buffer" in the actual NFVI to be
- used outside the Promise shim-layer or for a different reservation
- service instance. It can also be used to inform the reservation system
- that from a certain time in the future, additional resources can be
- reserved (e.g. due to a planned upgrade of the capacity), or the
- available capacity will be reduced (e.g. due to a planned downtime of
- some of the resources).
-
- * Step 2b: The shim-layer will respond with an ACK/NACK message.
-
- * Step 3a: Consumers can subscribe for capacity-change events using a
- filter.
-
- * Step 3b: Each successful subscription is responded with a
- subscription_id.
-
- * Step 4: The shim-layer monitors the capacity information for the
- various types of resources by periodically querying the various
- Controllers (e.g. Nova, Neutron, Cinder) or by creating event alarms in
- the VIM (e.g. with Ceilometer for OpenStack) and updates capacity
- information in its capacity map.
-
- * Step 5: Capacity changes are notified to the Consumer.
-
-Resource Reservation
-""""""""""""""""""""
-
-.. figure:: images/figure6_new.png
- :name: figure6
- :width: 90%
-
- Resource Reservation for Future Use Scenario
-
-:numref:`figure6` shows a detailed message flow between the Consumer and the
-resource reservation functional blocks inside the shim-layer. It has the
-following steps:
-
- * Step 1a: The Consumer creates a resource reservation request for
- future use by setting a start and end time for the reservation as well as
- more detailed information about the resources to be reserved. The Promise
- shim-layer will check the free capacity in the given time window and in
- case sufficient capacity exists to meet the reservation request, will
- mark those resources "reserved" in its reservation map.
-
- * Step 1b: If the reservation was successful, a reservation_id and
- status of the reservation will be returned to the Consumer. In case the
- reservation cannot be met, the shim-layer may return information about
- the maximum capacity that could be reserved during the requested time
- window and/or a potential time window where the requested (amount of)
- resources would be available.
-
- * Step 2a: Reservations can be updated using an *update-reservation*,
- providing the reservation_id and the new reservation_data. Promise
- Reservation Manageer will check the feasibility to update the reservation
- as requested.
-
- * Step 2b: If the reservation was updated successfully, a
- reservation_id and status of the reservation will be returned to the
- Consumer. Otherwise, an appropriate error message will be returned.
-
- * Step 3a: A *cancel-reservation* request can be used to withdraw an
- existing reservation. Promise will update the reservation map by removing
- the reservation as well as the capacity map by adding the freed capacity.
-
- * Step 3b: The response message confirms the cancelation.
-
- * Step 4a: Consumers can also issue *query-reservation* requests to
- receive a list of reservation. An input filter can be used to narrow down
- the query, e.g., only provide reservations in a given time window.
- Promise will query its reservation map to identify reservations matching
- the input filter.
-
- * Step 4b: The response message contains information about all
- reservations matching the input filter. It also provides information
- about the utilization in the requested time window.
-
- * Step 5a: Consumers can subscribe for reservation-change events using
- a filter.
-
- * Step 5b: Each successful subscription is responded with a
- subscription_id.
-
- * Step 6a: Promise synchronizes the available and used capacity with
- the underlying VIM.
-
- * Step 6b: In certain cases, e.g., due a failure in the underlying
- hardware, some reservations cannot be kept up anymore and have to be
- updated or canceled. The shim-layer will identify affected reservations
- among its reservation records.
-
- * Step 7: Subscribed Consumers will be informed about the updated
- reservations. The notification contains the updated reservation_data and
- new status of the reservation. It is then up to the Consumer to take
- appropriate actions in order to ensure high priority reservations are
- favored over lower priority reservations.
-
-Resource Allocation
-"""""""""""""""""""
-
-.. figure:: images/figure7_new.png
- :name: figure7
- :width: 90%
-
- Resource Allocation
-
-:numref:`figure7` shows a detailed message flow between the Consumer, the
-functional blocks inside the shim-layer, and the VIM. It has the following
-steps:
-
- * Step 1a: The Consumer sends a *create-instance* request providing
- information about the resources to be reserved, i.e., provider_id
- (optional in case of only one provider), name of the instance, the
- requested flavour and image, etc. If the allocation is against an
- existing reservation, the reservation_id has to be provided.
-
- * Step 1b: If a reservation_id was provided, Promise checks if a
- reservation with that ID exists, the reservation start time has arrived
- (i.e. the reservation is active), and the required capacity for the
- requested flavor is within the available capacity of the reservation. If
- those conditions are met, Promise creates a record for the allocation
- (VMState="INITIALIZED") and update its databases. If no reservation_id
- was provided in the allocation request, Promise checks whether the
- required capacity to meet the request can be provided from the available,
- non-reserved capacity. If yes, Promise creates a record for the
- allocation and update its databases. In any other case, Promise rejects
- the *create-instance* request.
-
- * Step 2: In the case the *create-instance* request was rejected,
- Promise responds with a "status=rejected" providing the reason of the
- rejection. This will help the Consumer to take appropriate actions, e.g.,
- send an updated *create-instance* request. The allocation work flow will
- terminate at this step and the below steps are not executed.
-
- * Step 3a: If the *create-instance* request was accepted and a related
- allocation record has been created, the shim-layer issues a
- *createServer* request to the VIM Controller providing all information to
- create the server instance.
-
- * Step 3b: The VIM Controller sends an immediate reply with an
- instance_id and starts the VIM-internal allocation process.
-
- * Step 4: The Consumer gets an immediate response message with
- allocation status "in progress" and the assigned instance_id.
-
- * Step 5a+b: The consumer subscribes to receive notifications about
- allocation events related to the requested instance. Promise responds
- with an acknowledgment including a subscribe_id.
-
- * Step 6: In parallel to the previous step, Promise shim-layer creates
- an alarm in Aodh to receive notifications about all changes to the
- VMState for instance_id.
-
- * Step 7a: The VIM Controller notifies all instance related events to
- Ceilometer. After the allocation has been completed or failed, it sends
- an event to Ceilometer. This triggers the OpenStack alarming service Aodh
- to notify the new VMState (e.g. ACTIVE and ERROR) to the shim-layer that
- updates its internal allocation records.
-
- * Step 7b: Promise sends a notification message to the subscribed
- Consumer with information on the allocated resources including their new
- VMState.
-
- * Step 8a+b: Allocated instances can be terminated by the Consumer by
- sending a *destroy-instance* request to the shim-layer. Promise responds
- with an acknowledgment and the new status "DELETING" for the instance.
-
- * Step 9a: Promise sends a *deleteServer* request for the instance_id
- to the VIM Controller.
-
- * Step 10a: After the instance has been deleted, an event alarm is
- sent to the shim-layer that updates its internal allocation records and
- capacity utilization.
-
- * Step 10b: The shim-layer also notifies the subscribed Consumer about
- the successfully destroyed instance.
-
-
-Internal operations
-^^^^^^^^^^^^^^^^^^^
-
-.. note:: This section is to be updated
-
-In the following, the internal logic and operations of the shim-layer will be
-explained in more detail, e.g. the "check request" (step 1b in
-:numref:`figure7` of the allocation work flow).
-
-
-
-Integrated architecture
------------------------
-
-The *integrated architecture* aims at full integration with OpenStack.
-This means that it is planned to use the already existing OpenStack APIs
-extended with the reservation capabilities.
-
-The advantage of this approach is that we don't need to re-model the
-complex resource structure we have for the virtual machines and the
-corresponding infrastructure.
-
-The atomic item is the virtual machine with the minimum set of resources
-it requires to be able to start it up. It is important to state that
-resource reservation is handled on VM instance level as opposed to standalone
-resources like CPU, memory and so forth. As the placement is an important
-aspect in order to be able to use the reserved resources it provides the
-constraint to handle resources in groups.
-
-The placement constraint also makes it impossible to use a quota management
-system to solve the base use case described earlier in this document.
-
-OpenStack had a project called Blazar, which was created in order to provide
-resource reservation functionality in cloud environments. It uses the Shelve
-API of Nova, which provides a sub-optimal solution. Due to the fact that this
-feature blocks the reserved resources this solution cannot be considered to
-be final. Further work is needed to reach a more optimal stage, where the
-Nova scheduler is intended to be used to schedule the resources for future
-use to make the reservations.
-
-Phases of the work
-^^^^^^^^^^^^^^^^^^
-
-The work has two main stages to reach the final solution. The following main work items
-are on the roadmap for this approach:
-
-#. Sub-optimal solution by using the shelve API of Nova through the Blazar project:
-
- * Fix the code base of the Blazar project:
-
- Due to integration difficulties the Blazar project got suspended. Since the last
- activities in that repository the OpenStack code base and environment changed
- significantly, which means that the project's code base needs to be updated to the
- latest standards and has to be able to interact with the latest version of the
- other OpenStack services.
-
- * Update the Blazar API:
-
- The REST API needs to be extended to contain the attributes for the reservation
- defined in this document. This activity shall include testing towards the new API.
-
-#. Use Nova scheduler to avoid blocking the reserved resources:
-
- * Analyze the Nova scheduler:
-
- The status and the possible interface between the resource reservation system and
- the Nova scheduler needs to be identified. It is crucial to achieve a much more
- optimal solution than what the current version of Blazar can provide. The goal is
- to be able to use the reserved resources before the reservation starts. In order to
- be able to achieve this we need the scheduler to do scheduling for the future
- considering the reservation intervals that are specified in the request.
-
- * Define a new design based on the analysis and start the work on it:
-
- The design for the more optimal solution can be defined only after analyzing the
- structure and capabilities of the Nova scheduler.
-
- * This phase can be started in parallel with the previous one.
-
-Detailed Message Flows
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. note:: to be done
-
-Resource Reservation
-""""""""""""""""""""
-
-.. note:: to be specified
diff --git a/docs/requirements/index.rst b/docs/requirements/index.rst
deleted file mode 100644
index 00edf0e..0000000
--- a/docs/requirements/index.rst
+++ /dev/null
@@ -1,52 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-****************************
-Promise: Resource Management
-****************************
-
-:Project: Promise, https://wiki.opnfv.org/promise
-:Editors: Ashiq Khan (NTT DOCOMO), Bertrand Souville (NTT DOCOMO)
-:Authors: Ravi Chunduru (ClearPath Networks), Peter Lee (ClearPath Networks),
- Gerald Kunzmann (NTT DOCOMO), Ryota Mibu (NEC),
- Carlos Goncalves (NEC), Arturo Martin De Nicolas (Ericsson)
-
-:History:
- ========== =====================================================
- Date Description
- ========== =====================================================
- 04.12.2014 Project creation
- 20.04.2015 Initial version of the deliverable uploaded to gerrit
- 19.06.2015 Stable version of the Promise deliverable
- ========== =====================================================
-
-:Abstract: Promise is an OPNFV requirement project. Its objective is to realize
- ETSI NFV defined resource reservation and NFVI capacity features
- within the scope of OPNFV. Promise provides the details of the
- requirements on resource reservation, NFVI capacity management at
- VIM, specification of the northbound interfaces from VIM relevant to
- these features, and implementation plan to realize these features in
- OPNFV.
-
-.. raw:: latex
-
- \newpage
-
-.. toctree::
- :maxdepth: 4
- :numbered:
-
- glossary.rst
- intro.rst
- usecase.rst
- architecture.rst
- gap_analysis.rst
- impl_architecture.rst
- NB_interface.rst
- summary.rst
-
- references.rst
- annex1.rst
- schemas.rst
- supported_apis.rst
- revision.rst
diff --git a/docs/requirements/intro.rst b/docs/requirements/intro.rst
deleted file mode 100644
index 654fdf9..0000000
--- a/docs/requirements/intro.rst
+++ /dev/null
@@ -1,39 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-============
-Introduction
-============
-
-Resource reservation is a basic function for the operation of a virtualized
-telecom network. In resource reservation, VIM reserves resources for a certain
-period as requested by the NFVO. A resource reservation will have a start time
-which could be into the future. Therefore, the reserved resources shall be
-available for the NFVO requested purpose (e.g. for a VNF) at the start time for
-the duration asked by NFVO. Resources include all three resource types in an
-NFVI i.e. compute, storage and network.
-
-Besides, NFVO requires abstracted NFVI resource capacity information in order
-to take decisions on VNF placement and other operations related to the virtual
-resources. VIM is required to inform the NFVO of NFVI resource state
-information for this purpose. Promise project aims at delivering the detailed
-requirements on these two features defined in ETSI NFV MAN GS [NFVMAN]_,
-the list of gaps in upstream projects, potential implementation architecture
-and plan, and the VIM northbound interface specification for resource
-reservation and capacity management.
-
-Problem description
-===================
-
-OpenStack, a prominent candidate for the VIM, cannot reserve resources for
-future use. OpenStack requires immediate instantiation of Virtual Machines
-(VMs) in order to occupy resources intended to be reserved. Blazar can reserve
-compute resources for future by keeping the VMs in shelved mode. However, such
-reserved resources can also be used for scaling out rather than new VM
-instantiation. Blazar does not support network and storage resource reservation
-yet.
-
-Besides, OpenStack does not provide a northbound interface through which it can
-notify an upper layer management entity e.g. NFVO about capacity changes in its
-NFVI, periodically or in an event driven way. Capacity management is a feature
-defined in ETSI NFV MAN GS [NFVMAN]_ and is required in network operation.
diff --git a/docs/requirements/references.rst b/docs/requirements/references.rst
deleted file mode 100644
index c498b66..0000000
--- a/docs/requirements/references.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-References and bibliography
-===========================
-
-.. [PROMISE] OPNFV, "Promise" requirements project, [Online]. Available at
- https://wiki.opnfv.org/promise
-.. [BLAZAR] OpenStack Blazar Project, [Online]. Available at
- https://wiki.openstack.org/wiki/Blazar
-.. [PROMOSS] Promise reference implementation, [Online]. Available at
- https://github.com/opnfv/promise
-.. [YANGFO] Yangforge Project, [Online]. Available at
- https://github.com/opnfv/yangforge
-.. [NFVMAN] ETSI GS NFV MAN 001, "Network Function Virtualisation (NFV); Management and Orchestration"
-.. [NFV003] ETSI GS NFV 003, "Network Function Virtualisation (NFV); Terminology for Main Concepts in NFV"
-.. [NFVIFA010] ETSI GS NFV IFA 010, "Network Function Virtualisation (NFV); Management and Orchestration;
- Functional Requirements Specification"
-.. [NFVIFA005] ETSI GS NFV IFA 005, "Network Function Virtualisation (NFV); Management and Orchestration;
- Or-Vi reference point - Interface and Information Model Specification"
-.. [NFVIFA006] ETSI GS NFV IFA 006 "Network Function Virtualisation (NFV); Management and Orchestration;
- Vi-Vnfm reference point - Interface and Information Model Specification"
-.. [ETSINFV] ETSI NFV, [Online]. Available at
- http://www.etsi.org/technologies-clusters/technologies/nfv
-
diff --git a/docs/requirements/revision.rst b/docs/requirements/revision.rst
deleted file mode 100644
index cd0b76b..0000000
--- a/docs/requirements/revision.rst
+++ /dev/null
@@ -1,43 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-ANNEX D: Document revision
-==========================
-
-+---------+-----------------------------------------+
-| Version | Description |
-+---------+-----------------------------------------+
-| 1.0.1 | JIRA: PROMISE-23 |
-| | - Reference to YangForge Framework |
-| | - Corrections to figure 3.1 |
-+---------+-----------------------------------------+
-| 1.0.2 | JIRA: PROMISE-11 |
-| | - OPNFV Logo Added |
-| | - Alignment to ETSI NFV Specs |
-+---------+-----------------------------------------+
-| 1.0.3 | JIRA: PROMISE-54 |
-| | - Use case for Brahmaputra |
-+---------+-----------------------------------------+
-| 1.0.4 | JIRA: PROMISE-60 |
-| | - Editorial fixes |
-| | |
-| | JIRA: PROMISE-57 |
-| | - Split shim-layer architecture and |
-| | integrated architecture sections |
-+---------+-----------------------------------------+
-| 1.0.5 | JIRA: PROMISE-61 |
-| | - Updated Promise Yang Schema |
-+---------+-----------------------------------------+
-| 1.0.6 | JIRA: PROMISE-62 |
-| | - Supported APIs for Brahmaputra |
-+---------+-----------------------------------------+
-| 1.0.7 | JIRA: PROMISE-63 |
-| | - Update message flow for shim-layer |
-| | JIRA: PROMISE-58 |
-| | - Integrated approach description |
-| | JIRA: PROMISE-64 |
-| | - Promise userguide |
-+---------+-----------------------------------------+
-| 1.0.8 | JIRA: PROMISE-11 |
-| | - Alignment to ETSI NVF Specs |
-+---------+-----------------------------------------+
diff --git a/docs/requirements/schemas.rst b/docs/requirements/schemas.rst
deleted file mode 100644
index c98b7da..0000000
--- a/docs/requirements/schemas.rst
+++ /dev/null
@@ -1,658 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-.. _yang_schema:
-
-ANNEX B: Promise YANG schema based on YangForge
-===============================================
-
-.. code::
-
- module opnfv-promise {
- namespace "urn:opnfv:promise";
- prefix promise;
-
- import complex-types { prefix ct; }
- import ietf-yang-types { prefix yang; }
- import ietf-inet-types { prefix inet; }
- import access-control-models { prefix acm; }
- import nfv-infrastructure { prefix nfvi; }
- import nfv-mano { prefix mano; }
-
- description
- "OPNFV Promise Resource Reservation/Allocation controller module";
-
- revision 2015-10-05 {
- description "Complete coverage of reservation related intents";
- }
-
- revision 2015-08-06 {
- description "Updated to incorporate YangForge framework";
- }
-
- revision 2015-04-16 {
- description "Initial revision.";
- }
-
- feature reservation-service {
- description "When enabled, provides resource reservation service";
- }
-
- feature multi-provider {
- description "When enabled, provides resource management across multiple providers";
- }
-
- typedef reference-identifier {
- description "defines valid formats for external reference id";
- type union {
- type yang:uuid;
- type inet:uri;
- type uint32;
- }
- }
-
- grouping resource-utilization {
- container capacity {
- container total { description 'Conceptual container that should be extended'; }
- container reserved { description 'Conceptual container that should be extended';
- config false; }
- container usage { description 'Conceptual container that should be extended';
- config false; }
- container available { description 'Conceptual container that should be extended';
- config false; }
- }
- }
-
- grouping temporal-resource-collection {
- description
- "Information model capturing resource-collection with start/end time window";
-
- leaf start { type yang:date-and-time; }
- leaf end { type yang:date-and-time; }
-
- uses nfvi:resource-collection;
- }
-
- grouping resource-usage-request {
- description
- "Information model capturing available parameters to make a resource
- usage request.";
- reference "OPNFV-PROMISE, Section 3.4.1";
-
- uses temporal-resource-collection {
- refine elements {
- description
- "Reference to a list of 'pre-existing' resource elements that are
- required for fulfillment of the resource-usage-request.
-
- It can contain any instance derived from ResourceElement,
- such as ServerInstances or even other
- ResourceReservations. If the resource-usage-request is
- accepted, the ResourceElement(s) listed here will be placed
- into 'protected' mode as to prevent accidental removal.
-
- If any of these resource elements become 'unavailable' due to
- environmental or administrative activity, a notification will
- be issued informing of the issue.";
- }
- }
-
- leaf zone {
- description "Optional identifier to an Availability Zone";
- type instance-identifier { ct:instance-type nfvi:AvailabilityZone; }
- }
- }
-
- grouping query-start-end-window {
- container window {
- description "Matches entries that are within the specified start/end time window";
- leaf start { type yang:date-and-time; }
- leaf end { type yang:date-and-time; }
- leaf scope {
- type enumeration {
- enum "exclusive" {
- description "Matches entries that start AND end within the window";
- }
- enum "inclusive" {
- description "Matches entries that start OR end within the window";
- }
- }
- default "inclusive";
- }
- }
- }
-
- grouping query-resource-collection {
- uses query-start-end-window {
- description "Match for ResourceCollection(s) that are within the specified
- start/end time window";
- }
- leaf-list without {
- description "Excludes specified collection identifiers from the result";
- type instance-identifier { ct:instance-type ResourceCollection; }
- }
- leaf show-utilization { type boolean; default true; }
- container elements {
- leaf-list some {
- description "Query for ResourceCollection(s) that contain some or more of
- these element(s)";
- type instance-identifier { ct:instance-type nfvi:ResourceElement; }
- }
- leaf-list every {
- description "Query for ResourceCollection(s) that contain all of
- these element(s)";
- type instance-identifier { ct:instance-type nfvi:ResourceElement; }
- }
- }
- }
-
- grouping common-intent-output {
- leaf result {
- type enumeration {
- enum "ok";
- enum "conflict";
- enum "error";
- }
- }
- leaf message { type string; }
- }
-
- grouping utilization-output {
- list utilization {
- key 'timestamp';
- leaf timestamp { type yang:date-and-time; }
- leaf count { type int16; }
- container capacity { uses nfvi:resource-capacity; }
- }
- }
-
- ct:complex-type ResourceCollection {
- ct:extends nfvi:ResourceContainer;
- ct:abstract true;
-
- description
- "Describes an abstract ResourceCollection data model, which represents
- a grouping of capacity and elements available during a given
- window in time which must be extended by other resource
- collection related models";
-
- leaf start { type yang:date-and-time; }
- leaf end { type yang:date-and-time; }
-
- leaf active {
- config false;
- description
- "Provides current state of this record whether it is enabled and within
- specified start/end time";
- type boolean;
- }
- }
-
- ct:complex-type ResourcePool {
- ct:extends ResourceCollection;
-
- description
- "Describes an instance of an active ResourcePool record, which
- represents total available capacity and elements from a given
- source.";
-
- leaf source {
- type instance-identifier {
- ct:instance-type nfvi:ResourceContainer;
- require-instance true;
- }
- mandatory true;
- }
-
- refine elements {
- // following 'must' statement applies to each element
- // NOTE: just a non-working example for now...
- must "boolean(/source/elements/*[@id=id])" {
- error-message "One or more of the ResourceElement(s) does not exist in
- the provider to be reserved";
- }
- }
- }
-
- ct:complex-type ResourceReservation {
- ct:extends ResourceCollection;
-
- description
- "Describes an instance of an accepted resource reservation request,
- created usually as a result of 'create-reservation' request.
-
- A ResourceReservation is a derived instance of a generic
- ResourceCollection which has additional parameters to map the
- pool(s) that were referenced to accept this reservation as well
- as to track allocations made referencing this reservation.
-
- Contains the capacities of various resource attributes being
- reserved along with any resource elements that are needed to be
- available at the time of allocation(s).";
-
- reference "OPNFV-PROMISE, Section 3.4.1";
-
- leaf created-on { type yang:date-and-time; config false; }
- leaf modified-on { type yang:date-and-time; config false; }
-
- leaf-list pools {
- config false;
- description
- "Provides list of one or more pools that were referenced for providing
- the requested resources for this reservation. This is an
- important parameter for informing how/where allocation
- requests can be issued using this reservation since it is
- likely that the total reserved resource capacity/elements are
- made availble from multiple sources.";
- type instance-identifier {
- ct:instance-type ResourcePool;
- require-instance true;
- }
- }
-
- container remaining {
- config false;
- description
- "Provides visibility into total remaining capacity for this
- reservation based on allocations that took effect utilizing
- this reservation ID as a reference.";
-
- uses nfvi:resource-capacity;
- }
-
- leaf-list allocations {
- config false;
- description
- "Reference to a collection of consumed allocations referencing
- this reservation.";
- type instance-identifier {
- ct:instance-type ResourceAllocation;
- require-instance true;
- }
- }
- }
-
- ct:complex-type ResourceAllocation {
- ct:extends ResourceCollection;
-
- description
- "A ResourceAllocation record denotes consumption of resources from a
- referenced ResourcePool.
-
- It does not reflect an accepted request but is created to
- represent the actual state about the ResourcePool. It is
- created once the allocation(s) have successfully taken effect
- on the 'source' of the ResourcePool.
-
- The 'priority' state indicates the classification for dealing
- with resource starvation scenarios. Lower priority allocations
- will be forcefully terminated to allow for higher priority
- allocations to be fulfilled.
-
- Allocations without reference to an existing reservation will
- receive the lowest priority.";
-
- reference "OPNFV-PROMISE, Section 3.4.3";
-
- leaf reservation {
- description "Reference to an existing reservation identifier (optional)";
-
- type instance-identifier {
- ct:instance-type ResourceReservation;
- require-instance true;
- }
- }
-
- leaf pool {
- description "Reference to an existing resource pool from which allocation is drawn";
-
- type instance-identifier {
- ct:instance-type ResourcePool;
- require-instance true;
- }
- }
-
- container instance-ref {
- config false;
- description
- "Reference to actual instance identifier of the provider/server
- for this allocation";
- leaf provider {
- type instance-identifier { ct:instance-type ResourceProvider; }
- }
- leaf server { type yang:uuid; }
- }
-
- leaf priority {
- config false;
- description
- "Reflects current priority level of the allocation according to
- classification rules";
- type enumeration {
- enum "high" { value 1; }
- enum "normal" { value 2; }
- enum "low" { value 3; }
- }
- default "normal";
- }
- }
-
- ct:complex-type ResourceProvider {
- ct:extends nfvi:ResourceContainer;
-
- key "name";
- leaf token { type string; mandatory true; }
-
- container services { // read-only
- config false;
- container compute {
- leaf endpoint { type inet:uri; }
- ct:instance-list flavors { ct:instance-type nfvi:ComputeFlavor; }
- }
- }
-
- leaf-list pools {
- config false;
- description
- "Provides list of one or more pools that are referencing this provider.";
-
- type instance-identifier {
- ct:instance-type ResourcePool;
- require-instance true;
- }
- }
- }
-
- // MAIN CONTAINER
- container promise {
-
- uses resource-utilization {
- description "Describes current state info about capacity utilization info";
-
- augment "capacity/total" { uses nfvi:resource-capacity; }
- augment "capacity/reserved" { uses nfvi:resource-capacity; }
- augment "capacity/usage" { uses nfvi:resource-capacity; }
- augment "capacity/available" { uses nfvi:resource-capacity; }
- }
-
- ct:instance-list providers {
- if-feature multi-provider;
- description "Aggregate collection of all registered ResourceProvider instances
- for Promise resource management service";
- ct:instance-type ResourceProvider;
- }
-
- ct:instance-list pools {
- if-feature reservation-service;
- description "Aggregate collection of all ResourcePool instances";
- ct:instance-type ResourcePool;
- }
-
- ct:instance-list reservations {
- if-feature reservation-service;
- description "Aggregate collection of all ResourceReservation instances";
- ct:instance-type ResourceReservation;
- }
-
- ct:instance-list allocations {
- description "Aggregate collection of all ResourceAllocation instances";
- ct:instance-type ResourceAllocation;
- }
-
- container policy {
- container reservation {
- leaf max-future-start-range {
- description
- "Enforce reservation request 'start' time is within allowed range from now";
- type uint16 { range 0..365; }
- units "days";
- }
- leaf max-future-end-range {
- description
- "Enforce reservation request 'end' time is within allowed range from now";
- type uint16 { range 0..365; }
- units "days";
- }
- leaf max-duration {
- description
- "Enforce reservation duration (end-start) does not exceed specified threshold";
- type uint16;
- units "hours";
- default 8760; // for now cap it at max one year as default
- }
- leaf expiry {
- description
- "Duration in minutes from start when unallocated reserved resources
- will be released back into the pool";
- type uint32;
- units "minutes";
- }
- }
- }
- }
-
- //-------------------
- // INTENT INTERFACE
- //-------------------
-
- // RESERVATION INTENTS
- rpc create-reservation {
- if-feature reservation-service;
- description "Make a request to the reservation system to reserve resources";
- input {
- uses resource-usage-request;
- }
- output {
- uses common-intent-output;
- leaf reservation-id {
- type instance-identifier { ct:instance-type ResourceReservation; }
- }
- }
- }
-
- rpc update-reservation {
- description "Update reservation details for an existing reservation";
- input {
- leaf reservation-id {
- type instance-identifier {
- ct:instance-type ResourceReservation;
- require-instance true;
- }
- mandatory true;
- }
- uses resource-usage-request;
- }
- output {
- uses common-intent-output;
- }
- }
-
- rpc cancel-reservation {
- description "Cancel the reservation and be a good steward";
- input {
- leaf reservation-id {
- type instance-identifier { ct:instance-type ResourceReservation; }
- mandatory true;
- }
- }
- output {
- uses common-intent-output;
- }
- }
-
- rpc query-reservation {
- if-feature reservation-service;
- description "Query the reservation system to return matching reservation(s)";
- input {
- leaf zone { type instance-identifier { ct:instance-type nfvi:AvailabilityZone; } }
- uses query-resource-collection;
- }
- output {
- leaf-list reservations { type instance-identifier
- { ct:instance-type ResourceReservation; } }
- uses utilization-output;
- }
- }
-
- // CAPACITY INTENTS
- rpc increase-capacity {
- description "Increase total capacity for the reservation system
- between a window in time";
- input {
- uses temporal-resource-collection;
- leaf source {
- type instance-identifier {
- ct:instance-type nfvi:ResourceContainer;
- }
- }
- }
- output {
- uses common-intent-output;
- leaf pool-id {
- type instance-identifier { ct:instance-type ResourcePool; }
- }
- }
- }
-
- rpc decrease-capacity {
- description "Decrease total capacity for the reservation system
- between a window in time";
- input {
- uses temporal-resource-collection;
- leaf source {
- type instance-identifier {
- ct:instance-type nfvi:ResourceContainer;
- }
- }
- }
- output {
- uses common-intent-output;
- leaf pool-id {
- type instance-identifier { ct:instance-type ResourcePool; }
- }
- }
- }
-
- rpc query-capacity {
- description "Check available capacity information about a specified
- resource collection";
- input {
- leaf capacity {
- type enumeration {
- enum 'total';
- enum 'reserved';
- enum 'usage';
- enum 'available';
- }
- default 'available';
- }
- leaf zone { type instance-identifier { ct:instance-type nfvi:AvailabilityZone; } }
- uses query-resource-collection;
- // TBD: additional parameters for query-capacity
- }
- output {
- leaf-list collections { type instance-identifier
- { ct:instance-type ResourceCollection; } }
- uses utilization-output;
- }
- }
-
- // ALLOCATION INTENTS (should go into VIM module in the future)
- rpc create-instance {
- description "Create an instance of specified resource(s) utilizing capacity
- from the pool";
- input {
- leaf provider-id {
- if-feature multi-provider;
- type instance-identifier { ct:instance-type ResourceProvider;
- require-instance true; }
- }
- leaf name { type string; mandatory true; }
- leaf image {
- type reference-identifier;
- mandatory true;
- }
- leaf flavor {
- type reference-identifier;
- mandatory true;
- }
- leaf-list networks {
- type reference-identifier;
- description "optional, will assign default network if not provided";
- }
-
- // TODO: consider supporting a template-id (such as HEAT) for more complex instantiation
-
- leaf reservation-id {
- type instance-identifier { ct:instance-type ResourceReservation;
- require-instance true; }
- }
- }
- output {
- uses common-intent-output;
- leaf instance-id {
- type instance-identifier { ct:instance-type ResourceAllocation; }
- }
- }
- }
-
- rpc destroy-instance {
- description "Destroy an instance of resource utilization and release it
- back to the pool";
- input {
- leaf instance-id {
- type instance-identifier { ct:instance-type ResourceAllocation;
- require-instance true; }
- }
- }
- output {
- uses common-intent-output;
- }
- }
-
- // PROVIDER INTENTS (should go into VIM module in the future)
- rpc add-provider {
- description "Register a new resource provider into reservation system";
- input {
- leaf provider-type {
- description "Select a specific resource provider type";
- mandatory true;
- type enumeration {
- enum openstack;
- enum hp;
- enum rackspace;
- enum amazon {
- status planned;
- }
- enum joyent {
- status planned;
- }
- enum azure {
- status planned;
- }
- }
- default openstack;
- }
- uses mano:provider-credentials {
- refine endpoint {
- default "http://localhost:5000/v2.0/tokens";
- }
- }
- container tenant {
- leaf id { type string; }
- leaf name { type string; }
- }
- }
- output {
- uses common-intent-output;
- leaf provider-id {
- type instance-identifier { ct:instance-type ResourceProvider; }
- }
- }
- }
-
- // TODO...
- notification reservation-event;
- notification capacity-event;
- notification allocation-event;
- }
diff --git a/docs/requirements/summary.rst b/docs/requirements/summary.rst
deleted file mode 100644
index fcf10d1..0000000
--- a/docs/requirements/summary.rst
+++ /dev/null
@@ -1,27 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-======================
-Summary and conclusion
-======================
-
-Resource Reservation and Resource Capacity Management are features to be
-supported by the VIM and exposed to the consumer via the VIM NBI. These
-features have been specified by ETSI NFV.
-
-This document has described several use cases and corresponding high level
-flows where Resource Reservation and Capacity Management are of great benefit
-for the consumer of the virtualised resource management interface: the NFVO or
-the VNFM. The use cases include:
-
-* Notification of changes in capacity in the NFVI
-* Query of available resource capacity
-* Reservation of a resource or set of resources for immediate use
-* Reservation of a resource or set of resources for future use
-
-The Promise project has performed a gap analysis in order to fulfill the
-required functionality. Based on the gap analysis an implementation plan and
-way forward has been proposed, including a possible design architecture and
-high level information model. Immediate next steps of this project is to
-deliver a working Proof-of-Concepts (PoC) and engage upstream communities to
-fill out the gaps identified by Promise.
diff --git a/docs/requirements/supported_apis.rst b/docs/requirements/supported_apis.rst
deleted file mode 100644
index 40cba8d..0000000
--- a/docs/requirements/supported_apis.rst
+++ /dev/null
@@ -1,608 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-ANNEX C: Supported APIS
-=======================
-
-Add Provider
-------------
-
-Register a new resource provider (e.g. OpenStack) into reservation system.
-
-Request parameters
-
-============================ =========== ==============================================
-Name Type Description
-============================ =========== ==============================================
-provider-type Enumeration Name of the resource provider
-endpoint URI Targer URL end point for the resource provider
-username String User name
-password String Password
-region String Specified region for the provider
-tenant.id String Id of the tenant
-tenant.name String Name of the tenant
-============================ =========== ==============================================
-
-Response parameters
-
-============================ =========== ==============================================
-Name Type Description
-============================ =========== ==============================================
-provider-id String Id of the new resource provider
-result Enumeration Result info
-============================ =========== ==============================================
-
-.. http:post:: /add-provider
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /add-provider HTTP/1.1
- Accept: application/json
-
- {
- "provider-type": "openstack",
- "endpoint": "http://10.0.2.15:5000/v2.0/tokens",
- "username": "promise_user",
- "password": "******",
- "tenant": {
- "name": "promise"
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
- "result": "ok"
- }
-
-Create Reservation
-------------------
-
-Make a request to the reservation system to reserve resources.
-
-Request parameters
-
-============================ =============== ==============================================
-Name Type Description
-============================ =============== ==============================================
-zone String Id to an availability zone
-start DateTime Timestamp when the consumption of reserved
- resources can begin
-end DateTime Timestamp when the consumption of reserved
- resources should end
-capacity.cores int16 Amount of cores to be reserved
-capacity.ram int32 Amount of RAM to be reserved
-capacity.instances int16 Amount of instances to be reserved
-capacity.addresses int32 Amount of public IP addresses to be reserved
-elements ResourceElement List of pre-existing resource elements
- to be reserved
-============================ =============== ==============================================
-
-Response parameters
-
-============================ =========== ==============================================
-Name Type Description
-============================ =========== ==============================================
-reservation-id String Id of the reservation
-result Enumeration Result info
-message String Output message
-============================ =========== ==============================================
-
-.. http:post:: /create-reservation
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /create-reservation HTTP/1.1
- Accept: application/json
-
- {
- "capacity": {
- "cores": "5",
- "ram": "25600",
- "addresses": "3",
- "instances": "3"
- },
- "start": "2016-02-02T00:00:00Z",
- "end": "2016-02-03T00:00:00Z"
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "reservation-id": "269b2944-9efc-41e0-b067-6898221e8619",
- "result": "ok",
- "message": "reservation request accepted"
- }
-
-Update Reservation
-------------------
-
-Update reservation details for an existing reservation.
-
-Request parameters
-
-============================ =============== ==============================================
-Name Type Description
-============================ =============== ==============================================
-reservation-id String Id of the reservation to be updated
-zone String Id to an availability zone
-start DateTime Updated timestamp when the consumption of
- reserved resources can begin
-end DateTime Updated timestamp when the consumption of
- reserved resources should end
-capacity.cores int16 Updated amount of cores to be reserved
-capacity.ram int32 Updated amount of RAM to be reserved
-capacity.instances int16 Updated amount of instances to be reserved
-capacity.addresses int32 Updated amount of public IP addresses
- to be reserved
-elements ResourceElement Updated list of pre-existing resource elements
- to be reserved
-============================ =============== ==============================================
-
-Response parameters
-
-============================ =========== ==============================================
-Name Type Description
-============================ =========== ==============================================
-result Enumeration Result info
-message String Output message
-============================ =========== ==============================================
-
-.. http:post:: /update-reservation
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /update-reservation HTTP/1.1
- Accept: application/json
-
- {
- "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619",
- "capacity": {
- "cores": "1",
- "ram": "5120",
- "addresses": "1",
- "instances": "1"
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "result": "ok",
- "message": "reservation update successful"
- }
-
-Cancel Reservation
-------------------
-
-Cancel the reservation.
-
-Request parameters
-
-============================ =============== ==============================================
-Name Type Description
-============================ =============== ==============================================
-reservation-id String Id of the reservation to be canceled
-============================ =============== ==============================================
-
-Response parameters
-
-============================ =========== ==============================================
-Name Type Description
-============================ =========== ==============================================
-result Enumeration Result info
-message String Output message
-============================ =========== ==============================================
-
-.. http:post:: /cancel-reservation
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /cancel-reservation HTTP/1.1
- Accept: application/json
-
- {
- "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619"
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "result": "ok",
- "message": "reservation canceled"
- }
-
-Query Reservation
------------------
-
-Query the reservation system to return matching reservation(s).
-
-Request parameters
-
-============================ ================== ==============================================
-Name Type Description
-============================ ================== ==============================================
-zone String Id to an availability zone
-show-utilization Boolean Show capacity utilization
-without ResourceCollection Excludes specified collection identifiers
- from the result
-elements.some ResourceElement Query for ResourceCollection(s) that contain
- some or more of these element(s)
-elements.every ResourceElement Query for ResourceCollection(s) that contain
- all of these element(s)
-window.start DateTime Matches entries that are within the specified
- start/end window
-window.end DateTime
-wndow.scope Enumeration Matches entries that start {and/or} end
- within the time window
-============================ ================== ==============================================
-
-Response parameters
-
-============================ =================== ================================
-Name Type Description
-============================ =================== ================================
-reservations ResourceReservation List of matching reservations
-utilization CapacityUtilization Capacity utilization over time
-============================ =================== ================================
-
-.. http:post:: /query-reservation
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /query-reservation HTTP/1.1
- Accept: application/json
-
- {
- "show-utilization": false,
- "window": {
- "start": "2016-02-01T00:00:00Z",
- "end": "2016-02-04T00:00:00Z"
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "reservations": [
- "269b2944-9efv-41e0-b067-6898221e8619"
- ],
- "utilization": []
- }
-
-Create Instance
----------------
-
-Create an instance of specified resource(s) utilizing capacity from the pool.
-
-Request parameters
-
-============================ =============== ==============================================
-Name Type Description
-============================ =============== ==============================================
-provider-id String Id of the resource provider
-reservation-id String Id of the resource reservation
-name String Name of the instance
-image String Id of the image
-flavor String Id of the flavor
-networks Uuid List of network uuids
-============================ =============== ==============================================
-
-Response parameters
-
-============================ =========== ==============================================
-Name Type Description
-============================ =========== ==============================================
-instance-id String Id of the instance
-result Enumeration Result info
-message String Output message
-============================ =========== ==============================================
-
-.. http:post:: /create-instance
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /create-instance HTTP/1.1
- Accept: application/json
-
- {
- "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
- "name": "vm1",
- "image": "ddffc6f5-5c86-4126-b0fb-2c71678633f8",
- "flavor": "91bfdf57-863b-4b73-9d93-fc311894b902"
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "instance-id": "82572779-896b-493f-92f6-a63008868250",
- "result": "ok",
- "message": "created-instance request accepted"
- }
-
-Destroy Instance
-----------------
-
-Destroy an instance of resource utilization and release it back to the pool.
-
-Request parameters
-
-============================ =============== ==============================================
-Name Type Description
-============================ =============== ==============================================
-instance-id String Id of the instance to be destroyed
-============================ =============== ==============================================
-
-Response parameters
-
-============================ =========== ==============================================
-Name Type Description
-============================ =========== ==============================================
-result Enumeration Result info
-message String Output message
-============================ =========== ==============================================
-
-.. http:post:: /destroy-instance
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /destroy-instance HTTP/1.1
- Accept: application/json
-
- {
- "instance-id": "82572779-896b-493f-92f6-a63008868250"
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "result": "ok",
- "message": "instance destroyed and resource released back to pool"
- }
-
-Decrease Capacity
------------------
-
-Decrease total capacity for the reservation system for a given time window.
-
-Request parameters
-
-============================ =============== ==============================================
-Name Type Description
-============================ =============== ==============================================
-source String Id of the resource container
-start DateTime Start/end defines the time window when total
- capacity is decreased
-end DateTime
-capacity.cores int16 Decreased amount of cores
-capacity.ram int32 Decreased amount of RAM
-capacity.instances int16 Decreased amount of instances
-capacity.addresses int32 Decreased amount of public IP addresses
-============================ =============== ==============================================
-
-Response parameters
-
-============================ =========== ==============================================
-Name Type Description
-============================ =========== ==============================================
-pool-id String Id of the resource pool
-result Enumeration Result info
-message String Output message
-============================ =========== ==============================================
-
-.. http:post:: /decrease-capacity
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /decrease-capacity HTTP/1.1
- Accept: application/json
-
- {
- "source": "ResourcePool:4085f0da-8030-4252-a0ff-c6f93870eb5f",
- "capacity": {
- "cores": "3",
- "ram": "5120",
- "addresses": "1"
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "pool-id": "c63b2a41-bcc6-42f6-8254-89d633e1bd0b",
- "result": "ok",
- "message": "capacity decrease successful"
- }
-
-Increase Capacity
------------------
-
-Increase total capacity for the reservation system for a given time window.
-
-Request parameters
-
-============================ =============== ==============================================
-Name Type Description
-============================ =============== ==============================================
-source String Id of the resource container
-start DateTime Start/end defines the time window when total
- capacity is increased
-end DateTime
-capacity.cores int16 Increased amount of cores
-capacity.ram int32 Increased amount of RAM
-capacity.instances int16 Increased amount of instances
-capacity.addresses int32 Increased amount of public IP addresses
-============================ =============== ==============================================
-
-Response parameters
-
-============================ =========== ==============================================
-Name Type Description
-============================ =========== ==============================================
-pool-id String Id of the resource pool
-result Enumeration Result info
-message String Output message
-============================ =========== ==============================================
-
-.. http:post:: /increase-capacity
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /increase-capacity HTTP/1.1
- Accept: application/json
-
- {
- "source": "ResourceProvider:f6f13fe3-0126-4c6d-a84f-15f1ab685c4f",
- "capacity": {
- "cores": "20",
- "ram": "51200",
- "instances": "10",
- "addresses": "10"
- }
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 200 OK
- Content-Type: application/json
-
- {
- "pool-id": "279217a4-7461-4176-bf9d-66770574ca6a",
- "result": "ok",
- "message": "capacity increase successful"
- }
-
-Query Capacity
---------------
-
-Query for capacity information about a specified resource collection.
-
-Request parameters
-
-============================ ================== ==============================================
-Name Type Description
-============================ ================== ==============================================
-capacity Enumeration Return total or reserved or available or
- usage capacity information
-zone String Id to an availability zone
-show-utilization Boolean Show capacity utilization
-without ResourceCollection Excludes specified collection identifiers
- from the result
-elements.some ResourceElement Query for ResourceCollection(s) that contain
- some or more of these element(s)
-elements.every ResourceElement Query for ResourceCollection(s) that contain
- all of these element(s)
-window.start DateTime Matches entries that are within the specified
- start/end window
-window.end DateTime
-window.scope Enumeration Matches entries that start {and/or} end
- within the time window
-============================ ================== ==============================================
-
-Response parameters
-
-============================ =================== ================================
-Name Type Description
-============================ =================== ================================
-collections ResourceCollection List of matching collections
-utilization CapacityUtilization Capacity utilization over time
-============================ =================== ================================
-
-.. http:post:: /query-capacity
- :noindex:
-
- **Example request**:
-
- .. sourcecode:: http
-
- POST /query-capacity HTTP/1.1
- Accept: application/json
-
- {
- "show-utilization": false
- }
-
- **Example response**:
-
- .. sourcecode:: http
-
- HTTP/1.1 201 CREATED
- Content-Type: application/json
-
- {
- "collections": [
- "ResourcePool:279217a4-7461-4176-bf9d-66770574ca6a"
- ],
- "utilization": []
- }
-
diff --git a/docs/requirements/usecase.rst b/docs/requirements/usecase.rst
deleted file mode 100644
index bdf8888..0000000
--- a/docs/requirements/usecase.rst
+++ /dev/null
@@ -1,121 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-=======================
-Use cases and scenarios
-=======================
-
-Use cases
-=========
-
-Resource reservation is a basic feature in any virtualization-based network
-operation. In order to perform such resource reservation from NFVO to VIM, NFVI
-capacity information is also necessary at the NFVO side. Below, four use cases
-to show typical requirements and solutions for capacity management and resource
-reservation is presented. A typical use case as considered for the Brahmaputra
-release is described in :ref:`uc-brahmaputra`.
-
-#. Resource capacity management
-#. Resource reservation for immediate use
-#. Resource reservation for future use
-#. Co-existence of reservations and allocation requests without reservation
-
-Resource capacity management
-----------------------------
-
-NFVO takes the first decision on in which NFVI it would instantiate a VNF. Along
-with NFVIs resource attributes (e.g. availability of hardware accelerators,
-particular CPU architectures etc.), NFVO needs to know available capacity of an
-NFVI in order to make an informed decision on selecting a particular NFVI. Such
-capacity information shall be in a coarser granularity than the respective VIM,
-as VIM maintains capacity information of its NFVI in fine details. However a
-very coarse granularity, like simply the number of available virtual CPU cores,
-may not be sufficient. In order to allow the NFVO to make well founded
-allocation decisions, an appropriate level to expose the available capacity may
-be per flavor. Capacity information may be required for the complete NFVI, or
-per partition or availability zone, or other granularities. Therefore, VIM
-requires to inform the NFVO about available capacity information regarding its
-NFVI at a pre-determined abstraction, either by a query-response, or in an
-event-based, or in a periodical way.
-
-Resource reservation for immediate use
---------------------------------------
-
-Reservation is inherently for the future. Even if some reserved resources are to
-be consumed instantly, there is a network latency between the issuance of a
-resource reservation request from the NFVO, a response from the VIM, and actual
-allocation of the requested resources to a VNF/VNFM. Within such latency,
-resource capacity in the NFVI in question could change, e.g., due to failure,
-allocation to a different request. Therefore, the response from a VIM to the
-NFVO to a resource reservation request for immediate use should have a validity
-period which shows until when this VIM can hold the requested resources. During
-this time, the NFVO should proceed to allocation if it wishes to consume the
-reserved requested. If allocation is not performed within the validity period,
-the response from VIM for a particular resource reservation request becomes
-invalid and VIM is not liable to provide those resources to NFVO/VNFM anymore.
-Reservations requests for immediate use do not have a start time but may have
-an end time.
-
-Resource reservation for future use
------------------------------------
-
-Network operators may want to reserve extra resources for future use. Such
-necessity could arise from predicted congestion in telecom nodes e.g. due to
-local traffic spikes for concerts, natural disasters etc. In such a case, the
-NFVO, while sending a resource reservation request to the VIM, shall include a
-start time (and an end time if necessary). The start time indicates at what
-time the reserved resource shall be available to a designated consumer e.g. a
-VNF/VNFM. Here, the requirement is that the reserved resources shall be
-available when the start time arrives. After the start time has arrived, the
-reserved resources are allocated to the designated consumer(s). An explicit
-allocation request is needed. How actually these requested resources are held
-by the VIM for the period in between the arrival of the resource reservation
-request and the actual allocation is outside the scope of this requirement
-project.
-
-Co-existence of reservations and allocation requests without reservation
-------------------------------------------------------------------------
-
-In a real environment VIM will have to handle allocation requests without any
-time reference, i.e. time-unbound, together with time-bound reservations and
-allocation requests with an explicitly indicated end-time. A granted
-reservation for the future will effectively reduce the available capacity for
-any new time-unbound allocation request. The consequence is that reservations,
-even those far in the future, may result in denial of service for new
-allocation requests.
-
-To alleviate this problem several approaches can be taken. They imply an
-implicit or explicit priority scheme:
-
-* Allocation requests without reservation and which are time-unbound will be
- granted resources in a best-effort way: if there is instant capacity, but the
- resources may be later withdrawn due to the start time of a previously
- granted reservation
-* Both allocation requests and reservation requests contain a priority which
- may be related to SLAs and contractual conditions between the tenant and the
- NFVI provider. Interactions may look like:
-
- * A reservation request for future use may cancel another, not yet
- started, reservation with lower priority
- * An allocation request without reservations and time-unbound [#unbound]_
- may be granted resources and prevent a future reservation with lower
- priority from getting resources at start time
- * A reservation request may result in terminating resources allocated to a
- request with no reservation, if the latter has lower priority
-
-.. [#unbound] In this case, the consumer (VNFM or NFVO) requests to immediately
- instantiate and assign virtualized resources without having
- reserved the resources beforehand
-
-Scenarios
-=========
-
-This section describes the expected behavior of the system in different
-scenarios.
-
-As we are targeting a cloud platform with the above use cases, it is crucial to
-keep the flexibility in the system. By this means it is hard to explicitely
-block hardware resources for the future and ensure their availablility for
-allocation therefore it can happen that the reservation plan cannot be fulfilled
-due to certain changes in the underlying environment. We need to ensure that we
-are prepared for error and edge cases during the design period.
diff --git a/docs/userguide/feature.userguide.rst b/docs/userguide/feature.userguide.rst
deleted file mode 100644
index 5fcae54..0000000
--- a/docs/userguide/feature.userguide.rst
+++ /dev/null
@@ -1,294 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-Abstract
-========
-This user guide document provides the users with:
-
-1. Short description of Promise project and key features implemented in
-Colorado.
-
-Promise description
-===================
-Promise is a resource reservation and management project to identify NFV related
-requirements and realize resource reservation for future usage by capacity
-management of resource pools regarding compute, network and storage.
-
-The following are the key features provided by this module:
-
-* Capacity Management
-* Reservation Management
-* Allocation Management
-
-Promise capabilities and usage
-==============================
-The Colorado implementation of Promise is built with the YangForge data modeling
-framework [#f2]_ , using a shim-layer on top of OpenStack to provide
-the Promise features. This approach requires communication between
-Consumers/Administrators and OpenStack to pass through the shim-layer. The
-shim-layer intercepts the message flow to manage the allocation requests based
-on existing reservations and available capacities in the providers. It also
-extracts information from the intercepted messages in order to update its
-internal databases. Furthermore, Promise provides additional intent-based APIs
-to allow a Consumer or Administrator to perform capacity management (i.e. add
-providers, update the capacity, and query the current capacity and utilization
-of a provider), reservation management (i.e. create, update, cancel, query
-reservations), and allocation management (i.e. create, destroy instances).
-
-Detailed information about Promise use cases, features, interface
-specifications, work flows, and the underlying Promise YANG schema can be found
-in the Promise requirement document [#f1]_ .
-
-Promise features and API usage guidelines and examples
-------------------------------------------------------
-This section lists the Promise features and API implemented in OPNFV Colorado.
-
-Note: The listed parameters are optional unless explicitly marked as "mandatory".
-
-Reservation management
-^^^^^^^^^^^^^^^^^^^^^^
-The reservation management allows a Consumer to request reservations for
-resource capacity. Reservations can be for now or a later time window.
-After the start time of a reservation has arrived, the Consumer can issue
-create server instance requests against the reserved capacity. Note, a
-reservation will expire after a predefined *expiry* time in case no
-allocation referring to the reservation is requested.
-
-The implemented workflow is well aligned with the described workflow in the
-Promise requirement document [#f1]_ (Section 6.1) except for the
-"multi-provider" scenario as described in :ref:`multi-provider` .
-
-.. _create-reservation:
-
-*create-reservation*
-""""""""""""""""""""
-
-This operation allows making a request to the reservation system to reserve
-resources.
-
-The operation takes the following input parameters:
-
-* start: start time of the requested reservation
-* end: end time of the requested reservation
-* capacity.instances: amount of instances to be reserved
-* capacity.cores: amount of cores to be reserved
-* capacity.ram: amount of ram in MB to be reserved
-
-Promise will check the available capacity in the given time window and in case
-sufficient capacity exists to meet the reservation request, will mark those
-resources "reserved" in its reservation map.
-
-*update-reservation*
-""""""""""""""""""""
-
-This operation allows to update the reservation details for an existing
-reservation.
-
-It can take the same input parameters as in *create-reservation*
-but in addition requires a mandatory reference to the *reservation-id* of the
-reservation that shall be updated.
-
-*cancel-reservation*
-""""""""""""""""""""
-
-This operation is used to cancel an existing reservation.
-
-The operation takes the following input parameter:
-
-* reservation-id (mandatory): identifier of the reservation to be canceled.
-
-*query-reservation*
-"""""""""""""""""""
-
-The operation queries the reservation system to return reservation(s) matching
-the specified query filter, e.g., reservations that are within a specified
-start/end time window.
-
-The operation takes the following input parameters to narrow down the query
-results:
-
-* without: excludes specified collection identifiers from the result
-* elements.some: query for ResourceCollection(s) that contain some or more of these element(s)
-* elements.every: query for ResourceCollection(s) that contain all of these element(s)
-* window.start: matches entries that are within the specified start/
-* window.end: end time window
-* window.scope: if set to 'exclusive', only reservations with start AND end time
- within the time window are returned. Otherwise ('inclusive'), all
- reservation starting OR ending in the time windows are returned.
-* show-utilization: boolean value that specifies whether to also return the
- resource utilization in the queried time window or not
-
-Allocation management
-^^^^^^^^^^^^^^^^^^^^^
-
-*create-instance*
-"""""""""""""""""
-
-This operation is used to create an instance of specified resource(s) for
-immediate use utilizing capacity from the pool. *Create-instance* requests can
-be issued against an existing reservation, but also allocations without a
-reference to an existing reservation are allowed. In case the allocation
-request specifies a reservation identifier, Promise checks if a reservation
-with that ID exists, the reservation start time has arrived (i.e. the
-reservation is 'active'), and the required capacity for the requested flavor is
-within the available capacity of the reservation. If those conditions are met,
-Promise creates a record for the allocation (VMState="INITIALIZED") and update
-its databases. If no *reservation_id* was provided in the allocation request,
-Promise checks whether the required capacity to meet the request can be
-provided from the available, non-reserved capacity. If yes, Promise creates a
-record for the allocation with an unique *instance-id* and update its
-databases. In any other case, Promise rejects the *create-instance* request.
-
-In case the *create-instance* request is rejected, Promise responds with a
-"status=rejected" providing the reason of the rejection. This will help the
-Consumer to take appropriate actions, e.g., send an updated *create-instance*
-request. In case the *create-instance* request was accepted and a related
-allocation record has been created, the shim-layer issues a *createServer*
-request to the VIM Controller (i.e. Nova) providing all information to create
-the server instance.
-
-The operation takes the following input parameters:
-
-* name (mandatory): Assigned name for the instance to be created
-* image (mandatory): the image to be booted in the new instance
-* flavor (mandatory): the flavor of the requested server instance
-* networks: the list of network uuids of the requested server instance
-* provider-id: identifier of the provider where the instance shall be created
-* reservation-id: identifier of a resource reservation the *create-instance*
-
-The Colorado implementation of Promise has the following limitations:
-
-* All create server instance requests shall pass through the Promise
- shim-layer such that Promise can keep track of all allocation requests. This
- is necessary as in the current release the sychronization between the VIM
- Controller and Promise on the available capacity is not yet implemented.
-* *Create-allocation* requests are limited to "simple" allocations, i.e., the
- current workflow only supports the Nova compute service and
- *create-allocation* requests are limited to creating one server instance at a
- time
-* Prioritization of reservations and allocations is yet not implemented.
- Future version may allow certain policy-based conflict resolution where,
- e.g., new allocation request with high priority can "forcefully" terminate
- lower priority allocations.
-
-
-*destroy-instance*
-""""""""""""""""""
-
-This operation request to destroy an existing server instance and release it
-back to the pool.
-
-The operation takes the following input parameter:
-
-* instance-id: identifier of the server instance to be destroyed
-
-Capacity management
-^^^^^^^^^^^^^^^^^^^
-The capacity management feature allows the Consumer or Administrator to do
-capacity planning, i.e. the capacity available to the reservation management
-can differ from the actual capacity in the registered provider(s). This feature
-can, e.g., be used to limit the available capacity for a given time window due
-to a planned downtime of some of the resources, or increase the capacity
-available to the reservation system in case of a planned upgrade of the
-available capacity.
-
-*increase/decrease-capacity*
-""""""""""""""""""""""""""""
-
-This operations allows to increase/decrease the total capacity that is made
-available to the Promise reservation service between a specified window in
-time. It does NOT increase the actual capacity of a given resource provider,
-but is used for capacity management inside Promise.
-
-This feature can be used in different ways, like
-
-* Limit the capacity available to the reservation system to a value below 100%
- of the available capacity in the VIM, e.g., in order to leave "buffer" in the
- actual NFVI to be used outside the Promise reservation service.
-
-* Inform the reservation system that, from a given time in the future,
- additional resources can be reserved, e.g., due to a planned upgrade of the
- available capacity of the provider.
-
-* Similarily, the "decrease-capacity" can be used to reduce the consumable
- resources in a given time window, e.g., to prepare for a planned downtime of
- some of the resources.
-
-* Expose multiple reservation service instances to different consumers sharing
- the same resource provider.
-
-The operation takes the following input parameters:
-
-* start: start time for the increased/decreased capacity
-* end: end time for the increased/decreased capacity
-* capacity.cores: Increased/decreased amount of cores
-* capacity.ram: Increased/decreased amount of RAM
-* capacity.instances: Increased/decreased amount of instances
-
-Note, increase/decreasing the capacity in Promise is completely transparent to
-the VIM. As such, when increasing the virtual capacity in Promise (e.g. for a
-planned upgrade of the capacity), it is in the responsibility of the
-Consumer/Administrator to ensure sufficient resources in the VIM are available
-at the appropriate time, in order to prevent allocations against reservations
-to fail due to a lack of resources. Therefore, this operations should only be
-used carefully.
-
-
-*query-capacity*
-""""""""""""""""
-
-This operation is used to query the available capacity information of the
-specified resource collection. A filter attribute can be specified to narrow
-down the query results.
-
-The current implementation supports the following filter criteria:
-
-* time window: returns reservations matching the specified window
-
-* window scope: if set to 'exclusive', only reservations with start AND end time
- within the time window are returned. Otherwise, all reservation starting OR
- ending in the time windows are returned.
-
-* metric: query for one of the following capacity metrics:
-
- * 'total': resource pools
- * 'reserved': reserved resources
- * 'usage': resource allocations
- * 'available': remaining capacity, i.e. neither reserved nor allocated
-
-.. _multi-provider:
-
-(Multi-)provider management
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This API towards OpenStack allows a Consumer/Administrator to add and remove
-resource providers to Promise. Note, Promise supports a multi-provider
-configuration, however, for Colorado, multi-provider support is not yet
-fully supported.
-
-*add-provider*
-""""""""""""""
-
-This operation is used to register a new resource provider into the Promise
-reservation system.
-
-Note, for Colorado, the add-provider operation should only be used to
-register one provider with the Promise shim-layer. Further note that currently
-only OpenStack is supported as a provider.
-
-The operation takes the following input parameters:
-
-* provider-type (mandatory) = 'openstack': select a specific resource provider
- type.
-* endpoint (mandatory): target URL endpoint for the resource provider.
-* username (mandatory)
-* password (mandatory)
-* region: specified region for the provider
-* tenant.id: id of the OpenStack tenant/project
-* tenant.name: name of the OpenStack tenant/project
-
-.. [#f1] Promise requirement document,
- http://artifacts.opnfv.org/promise/docs/requirements/index.html
-
-.. [#f2] YangForge framework, http://github.com/opnfv/yangforge
-
diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst
deleted file mode 100644
index f6cb21c..0000000
--- a/docs/userguide/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-==================
-Promise user guide
-==================
-
-
-.. toctree::
- :maxdepth: 3
-
- feature.userguide.rst
--
cgit