Use case for Brahmaputra

This patch is adding the agreed use case for B-release to the Annex of
the requirement document. 

JIRA: PROMISE-54

Change-Id: Id63bbcf49d53ddd07920721a5b9b12e9d9410036

4 files changed, 64 insertions, 25 deletions

diff --git a/docs/requirements/02-usecase.rst b/docs/requirements/02-usecase.rst
index 15342eb..f408cf4 100644
--- a/docs/requirements/02-usecase.rst
+++ b/docs/requirements/02-usecase.rst
@@ -6,7 +6,8 @@ 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.
+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
@@ -16,26 +17,26 @@ reservation is presented.
 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.
+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
+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,
@@ -88,11 +89,11 @@ implicit or explicit priority scheme:
   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 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
 
diff --git a/docs/requirements/08-revision.rst b/docs/requirements/08-revision.rst
index b543fa5..f25c7b0 100644
--- a/docs/requirements/08-revision.rst
+++ b/docs/requirements/08-revision.rst
@@ -1,10 +1,10 @@
-ANNEX B: DOCUMENT REVISION
+ANNEX C: DOCUMENT REVISION
 ==========================
 
 +---------+-----------------------------------------+
 | Version |      Description                        |
 +---------+-----------------------------------------+
-| 1.0.1   | JIRA: PROMISE-23                        |
+| 1.0.1   | JIRA: PROMISE-23                        |
 |         |  - Reference to YangForge Framework     |
 |         |  - Corrections to figure 3.1            |
 +---------+-----------------------------------------+
@@ -12,5 +12,8 @@ ANNEX B: DOCUMENT REVISION
 |         |  - OPNFV Logo Added                     |
 |         |  - Alignment to ETSI NFV Specs          |
 +---------+-----------------------------------------+
-|         |                                         |
+| 1.0.3   | JIRA: PROMISE-54                        |
+|         |  - Use case for Brahmaputra             |
++---------+-----------------------------------------+
+|         |                                         |
 +---------+-----------------------------------------+
diff --git a/docs/requirements/90-annex1.rst b/docs/requirements/90-annex1.rst
new file mode 100644
index 0000000..8185b18
--- /dev/null
+++ b/docs/requirements/90-annex1.rst
@@ -0,0 +1,34 @@
+.. _uc-brahmaputra:
+
+ANNEX B: 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
\ No newline at end of file
diff --git a/docs/requirements/index.rst b/docs/requirements/index.rst
index 9e50420..c047730 100644
--- a/docs/requirements/index.rst
+++ b/docs/requirements/index.rst
@@ -42,5 +42,6 @@ Promise: Resource Management
    05-impl.rst
    06-summary.rst
    07-schemas.rst
+   90-annex1.rst
    08-revision.rst
    99-references.rst