Split Shim-layer architecture and Integrated architecture

Create two sub-sections in "05 Detailed architecture" for the Shim-layer
architecture and the Integrated architecture.
Fix several implementations bugs and warnings. Remove numbering of
files.

JIRA: PROMISE-57

Change-Id: Ia0b4067c0cc3a461e54b6b010f8310764fb08d73

13 files changed, 202 insertions, 149 deletions

diff --git a/docs/requirements/05-impl.rst b/docs/requirements/NB_interface.rst
index 45ef449..28c25ae 100644
--- a/docs/requirements/05-impl.rst
+++ b/docs/requirements/NB_interface.rst
@@ -1,14 +1,11 @@
-Detailed architecture and message flows
-=======================================
-
 Detailed northbound interface specification
--------------------------------------------
+===========================================
 
 .. Note::
    This is Work in Progress.
 
 ETSI NFV IFA Information Models
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 Compute Flavor
 ^^^^^^^^^^^^^^
@@ -22,13 +19,13 @@ virtual memory, size of virtual storage, and virtual network interfaces
    :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
 
@@ -73,9 +70,10 @@ Subscription from Consumer to VIM to be notified about compute capacity changes
    :statuscode 400: resourceDescriptor is missing
 
 Query Compute Capacity
-______________________
+""""""""""""""""""""""
 
-Request to find out about available, reserved, total and allocated compute capacity.
+Request to find out about available, reserved, total and allocated compute
+capacity.
 
 .. http:get:: /capacity/compute/query
    :noindex:
@@ -120,7 +118,7 @@ Request to find out about available, reserved, total and allocated compute capac
    :statuscode 404: resource zone unknown
 
 Notify Compute Capacity Change Event
-____________________________________
+""""""""""""""""""""""""""""""""""""
 
 Notification about compute capacity changes
 
@@ -152,7 +150,7 @@ Compute Resource Reservation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Create Compute Resource Reservation
-___________________________________
+"""""""""""""""""""""""""""""""""""
 
 Request the reservation of compute resource capacity
 
@@ -270,7 +268,7 @@ and/or virtualized containers
 
 
 Query Compute Resource Reservation
-__________________________________
+""""""""""""""""""""""""""""""""""
 
 Request to find out about reserved compute resources that the consumer has
 access to.
@@ -320,7 +318,8 @@ access to.
    :statuscode 404: reservation id unknown
 
 Update Compute Resource Reservation
-___________________________________
+"""""""""""""""""""""""""""""""""""
+
 Request to update compute resource reservation
 
 .. http:post:: /reservation/compute/update
@@ -360,20 +359,21 @@ Request to update compute resource reservation
        }
 
 Terminate Compute Resource Reservation
-______________________________________
+""""""""""""""""""""""""""""""""""""""
+
 Request to terminate a compute resource reservation
 
 .. http:delete:: /reservation/compute/(reservation_id)
    :noindex:
 
 Virtualised Network Resources
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 Network Capacity Management
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Subscribe Network Capacity Change Event
-_______________________________________
+"""""""""""""""""""""""""""""""""""""""
 
 Susbcription from Consumer to VIM to be notified about network capacity changes
 
@@ -415,9 +415,10 @@ Susbcription from Consumer to VIM to be notified about network capacity changes
         }
 
 Query Network Capacity
-______________________
+""""""""""""""""""""""
 
-Request to find out about available, reserved, total and allocated network capacity.
+Request to find out about available, reserved, total and allocated network
+capacity.
 
 .. http:get:: /capacity/network/query
     :noindex:
@@ -457,7 +458,7 @@ Request to find out about available, reserved, total and allocated network capac
         }
 
 Notify Network Capacity Change Event
-____________________________________
+""""""""""""""""""""""""""""""""""""
 
 Notification about network capacity changes
 
@@ -488,9 +489,10 @@ Network Resource Reservation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Create Network Resource Reservation
-___________________________________
+"""""""""""""""""""""""""""""""""""
 
-Request the reservation of network resource capacity and/or virtual networks, network ports
+Request the reservation of network resource capacity and/or virtual networks,
+network ports
 
 .. http:post:: /reservation/network/create
     :noindex:
@@ -531,9 +533,10 @@ Request the reservation of network resource capacity and/or virtual networks, ne
         }
 
 Query Network Resource Reservation
-__________________________________
+""""""""""""""""""""""""""""""""""
 
-Request to find out about reserved network resources that the consumer has access to.
+Request to find out about reserved network resources that the consumer has
+access to.
 
 .. http:get:: /reservation/network/query
     :noindex:
@@ -573,7 +576,7 @@ Request to find out about reserved network resources that the consumer has acces
        }
 
 Update Network Resource Reservation
-___________________________________
+"""""""""""""""""""""""""""""""""""
 
 Request to update network resource reservation
 
@@ -614,20 +617,23 @@ Request to update network resource reservation
         }
 
 Terminate Network Resource Reservation
-______________________________________
+""""""""""""""""""""""""""""""""""""""
+
 Request to terminate a network resource reservation
 
 .. http:delete:: /reservation/network/(reservation_id)
     :noindex:
 
+
 Virtualised Storage Resources
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-----------------------------
 
 Storage Capacity Management
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Subscribe Storage Capacity Change Event
-_______________________________________
+"""""""""""""""""""""""""""""""""""""""
 
 Subscription from Consumer to VIM to be notified about storage capacity changes
 
@@ -669,9 +675,10 @@ Subscription from Consumer to VIM to be notified about storage capacity changes
         }
 
 Query Storage Capacity
-______________________
+""""""""""""""""""""""
 
-Request to find out about available, reserved, total and allocated storage capacity.
+Request to find out about available, reserved, total and allocated storage
+capacity.
 
 .. http:get:: /capacity/storage/query
     :noindex:
@@ -711,7 +718,7 @@ Request to find out about available, reserved, total and allocated storage capac
        }
 
 Notify Storage Capacity Change Event
-____________________________________
+""""""""""""""""""""""""""""""""""""
 
 Notification about storage capacity changes
 
@@ -742,7 +749,7 @@ Storage Resource Reservation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Create Storage Resource Reservation
-___________________________________
+"""""""""""""""""""""""""""""""""""
 
 Request the reservation of storage resource capacity
 
@@ -786,8 +793,10 @@ Request the reservation of storage resource capacity
         }
 
 Query Storage Resource Reservation
-__________________________________
-Request to find out about reserved storage resources that the consumer has access to.
+""""""""""""""""""""""""""""""""""
+
+Request to find out about reserved storage resources that the consumer has
+access to.
 
 .. http:get:: /reservation/storage/query
     :noindex:
@@ -828,7 +837,7 @@ Request to find out about reserved storage resources that the consumer has acces
         }
 
 Update Storage Resource Reservation
-___________________________________
+"""""""""""""""""""""""""""""""""""
 
 Request to update storage resource reservation
 
@@ -842,10 +851,12 @@ Request to update storage resource reservation
         POST /reservation/storage/update HTTP/1.1
         Accept: application/json
 
-       {
+
+        {
             "startTime": "2015-09-20T23:00:00Z",
             "reservationId": "vvvv-wwww-xxxx"
-       }
+
+        }
 
     **Example response**:
 
@@ -868,81 +879,9 @@ Request to update storage resource reservation
         }
 
 Terminate Storage Resource Reservation
-______________________________________
+""""""""""""""""""""""""""""""""""""""
+
 Request to terminate a storage resource reservation
 
 .. http:delete:: /reservation/storage/(reservation_id)
     :noindex:
-
-Detailed Message Flows
-----------------------
-
-Resource Capacity Management
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. figure:: images/figure5.png
-    :name: figure5
-    :width: 90%
-
-    Capacity Management Scenario
-
-:numref:`figure5` shows a detailed message flow between the consumers and the
-functional blocks inside the VIM and has the following steps:
-
-Step 1: The consumer subscribes to capacity change notifications
-
-Step 2: The Capacity Manager monitors the capacity information for the various
-types of resources by querying the various Controllers (e.g. Nova, Neutron,
-Cinder), either periodically or on demand and updates capacity information in
-the Capacity Map
-
-Step 3: Capacity changes are notified to the consumer
-
-Step 4: The consumer queries the Capacity Manager to retrieve capacity detailed
-information
-
-Resource Reservation
-~~~~~~~~~~~~~~~~~~~~
-
-.. figure:: images/figure6.png
-    :name: figure6
-    :width: 90%
-
-    Resource Reservation for Future Use Scenario
-
-:numref:`figure6` shows a detailed message flow between the consumers and
-the functional blocks inside the VIM and has the following steps:
-
-Step 1: The consumer creates a resource reservation request for future use by
-setting a start and end time for the allocation
-
-Step 2: The consumer gets an immediate reply with a reservation status message
-"reservationStatus" and an identifier to be used with this reservation instance
-"reservationID"
-
-Step 3: The consumer subscribes to reservation notification events
-
-Step 4: The Resource Reservation Manager checks the feasibility of the
-reservation request by consulting the Capacity Manager
-
-Step 5: The Resource Reservation Manager reserves the resources and stores the
-list of reservations IDs generated by the Controllers (e.g. Nova, Neutron,
-Cinder) in the Reservation Map
-
-Step 6: Once the reservation process is completed, the VIM sends a notification
-message to the consumer with information on the reserved resources
-
-Step 7: When start time arrives, the consumer creates a resource allocation
-request.
-
-Step 8: The consumer gets an immediate reply with an allocation status message
-"allocationStatus".
-
-Step 9: The consumer subscribes to allocation notification events
-
-Step 10: The Resource Allocation Manager allocates the reserved resources. If
-not all reserved resources are allocated before expiry, the reserved resources
-are released and a notification is sent to the consumer
-
-Step 11: Once the allocation process is completed, the VIM sends a notification
-message to the consumer with information on the allocated resources
diff --git a/docs/requirements/90-annex1.rst b/docs/requirements/annex1.rst
index 8185b18..aa5546c 100644
--- a/docs/requirements/90-annex1.rst
+++ b/docs/requirements/annex1.rst
@@ -1,6 +1,6 @@
 .. _uc-brahmaputra:
 
-ANNEX B: Use case for OPNFV Brahmaputra
+ANNEX A: Use case for OPNFV Brahmaputra
 =======================================
 
 A basic resource reservation use case to be realized for OPNFV B-release may
@@ -31,4 +31,4 @@ look as follows:
   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
+  using the reservation identifier in Step 3
diff --git a/docs/requirements/03-arch.rst b/docs/requirements/architecture.rst
index 8c4db91..c937898 100644
--- a/docs/requirements/03-arch.rst
+++ b/docs/requirements/architecture.rst
@@ -11,11 +11,11 @@ Architecture Overview
 
    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.
+: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.
 
@@ -48,9 +48,10 @@ Promise project.
     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 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
@@ -81,11 +82,11 @@ information using the Query Capacity Request interface operation.
    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.
+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
 --------------------
@@ -97,8 +98,7 @@ Resource Reservation
    Resource reservation flow
 
 :numref:`figure4` shows a high level flow for a use case of resource
-reservation.
-The main steps are:
+reservation. The main steps are:
 
 * The NFVO sends a resource reservation request to the VIM using the Create
   Resource Reservation Request interface operation.
@@ -120,8 +120,7 @@ Resource Capacity Management
 Notify Capacity Change Event
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The notification change message shall include the following information
-elements:
+The notification change message shall include the following information elements:
 
 ============================ ========== =====================================
 Name                         Type       Description
diff --git a/docs/requirements/04-gap.rst b/docs/requirements/gap_analysis.rst
index 9532495..8bd8140 100644
--- a/docs/requirements/04-gap.rst
+++ b/docs/requirements/gap_analysis.rst
@@ -93,3 +93,4 @@ Resource Discovery
     quota
 
 * Related Blueprints: N/A
+
diff --git a/docs/requirements/glossary.rst b/docs/requirements/glossary.rst
index 1addb9c..c958563 100644
--- a/docs/requirements/glossary.rst
+++ b/docs/requirements/glossary.rst
@@ -1,4 +1,6 @@
-**Definition of terms**
+===================
+Definition of terms
+===================
 
 Different SDOs and communities use different terminology related to
 NFV/Cloud/SDN. This list tries to define an OPNFV terminology,
@@ -53,8 +55,8 @@ mapping/translating the OPNFV terms to terminology used in other contexts.
 
    Virtual resource
       A Virtual Machine (VM), a virtual network, or virtualized storage; Offered
-      resources to "Consumer" as result of infrastructure virtualization; visible
-      to Consumer.
+      resources to "Consumer" as result of infrastructure virtualization;
+      visible to Consumer.
 
    Virtual Storage
       Virtualized non-volatile storage allocated to a VM.
diff --git a/docs/requirements/impl_architecture.rst b/docs/requirements/impl_architecture.rst
new file mode 100644
index 0000000..46cbba1
--- /dev/null
+++ b/docs/requirements/impl_architecture.rst
@@ -0,0 +1,105 @@
+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:: This section has to be updated.
+
+Resource Capacity Management
+""""""""""""""""""""""""""""
+
+.. figure:: images/figure5.png
+    :name: figure5
+    :width: 90%
+
+    Capacity Management Scenario
+
+:numref:`figure5` shows a detailed message flow between the consumers and the
+functional blocks inside the VIM and has the following steps:
+
+Step 1: The consumer subscribes to capacity change notifications
+
+Step 2: The Capacity Manager monitors the capacity information for the various
+types of resources by querying the various Controllers (e.g. Nova, Neutron,
+Cinder), either periodically or on demand and updates capacity information in
+the Capacity Map
+
+Step 3: Capacity changes are notified to the consumer
+
+Step 4: The consumer queries the Capacity Manager to retrieve capacity detailed
+information
+
+Resource Reservation
+""""""""""""""""""""
+
+.. figure:: images/figure6.png
+    :name: figure6
+    :width: 90%
+
+    Resource Reservation for Future Use Scenario
+
+:numref:`figure6` shows a detailed message flow between the consumers and the
+functional blocks inside the VIM and has the following steps:
+
+Step 1: The consumer creates a resource reservation request for future use by
+setting a start and end time for the allocation
+
+Step 2: The consumer gets an immediate reply with a reservation status message
+"reservationStatus" and an identifier to be used with this reservation instance
+"reservationID"
+
+Step 3: The consumer subscribes to reservation notification events
+
+Step 4: The Resource Reservation Manager checks the feasibility of the
+reservation request by consulting the Capacity Manager
+
+Step 5: The Resource Reservation Manager reserves the resources and stores the
+list of reservations IDs generated by the Controllers (e.g. Nova, Neutron,
+Cinder) in the Reservation Map
+
+Step 6: Once the reservation process is completed, the VIM sends a notification
+message to the consumer with information on the reserved resources
+
+Step 7: When start time arrives, the consumer creates a resource allocation
+request.
+
+Step 8: The consumer gets an immediate reply with an allocation status message
+"allocationStatus".
+
+Step 9: The consumer subscribes to allocation notification events
+
+Step 10: The Resource Allocation Manager allocates the reserved resources. If
+not all reserved resources are allocated before expiry, the reserved resources
+are released and a notification is sent to the consumer
+
+Step 11: Once the allocation process is completed, the VIM sends a notification
+message to the consumer with information on the allocated resources
+
+
+Integrated architecture
+-----------------------
+
+The *integrated architecture* aims at full integration with OpenStack.
+
+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
index c047730..5337ff5 100644
--- a/docs/requirements/index.rst
+++ b/docs/requirements/index.rst
@@ -29,19 +29,20 @@ Promise: Resource Management
 
     \newpage
 
-.. include:: glossary.rst
-
 .. toctree::
    :maxdepth: 4
    :numbered:
 
-   01-intro.rst
-   02-usecase.rst
-   03-arch.rst
-   04-gap.rst
-   05-impl.rst
-   06-summary.rst
-   07-schemas.rst
-   90-annex1.rst
-   08-revision.rst
-   99-references.rst
+   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
+   revision.rst
diff --git a/docs/requirements/01-intro.rst b/docs/requirements/intro.rst
index 6738df2..59af4b4 100644
--- a/docs/requirements/01-intro.rst
+++ b/docs/requirements/intro.rst
@@ -1,4 +1,3 @@
-
 ============
 Introduction
 ============
diff --git a/docs/requirements/99-references.rst b/docs/requirements/references.rst
index 4dd4845..72fbb73 100644
--- a/docs/requirements/99-references.rst
+++ b/docs/requirements/references.rst
@@ -1,3 +1,6 @@
+References and bibliography
+===========================
+
 .. [PROMISE]   OPNFV, "Promise" requirements project, [Online]. Available at
                https://wiki.opnfv.org/promise
 .. [BLAZAR]    OpenStack Blazar Project, [Online]. Available at
diff --git a/docs/requirements/08-revision.rst b/docs/requirements/revision.rst
index f25c7b0..fcb8c7d 100644
--- a/docs/requirements/08-revision.rst
+++ b/docs/requirements/revision.rst
@@ -1,4 +1,4 @@
-ANNEX C: DOCUMENT REVISION
+ANNEX C: Document revision
 ==========================
 
 +---------+-----------------------------------------+
@@ -15,5 +15,10 @@ ANNEX C: DOCUMENT REVISION
 | 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     |
 +---------+-----------------------------------------+
diff --git a/docs/requirements/07-schemas.rst b/docs/requirements/schemas.rst
index 64d87f3..e42e02e 100644
--- a/docs/requirements/07-schemas.rst
+++ b/docs/requirements/schemas.rst
@@ -1,4 +1,4 @@
-ANNEX A: PROMISE YANG SCHEMA BASED ON YANGFORGE
+ANNEX B: Promise YANG schema based on YangForge
 ===============================================
 
 .. code::
@@ -303,4 +303,3 @@ ANNEX A: PROMISE YANG SCHEMA BASED ON YANGFORGE
   notification capacity-event;
   notification allocation-event;
   }
-
diff --git a/docs/requirements/06-summary.rst b/docs/requirements/summary.rst
index 381ab87..ebd2bb9 100644
--- a/docs/requirements/06-summary.rst
+++ b/docs/requirements/summary.rst
@@ -16,7 +16,7 @@ the VNFM. The use cases include:
 * 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 fulfil the
+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
diff --git a/docs/requirements/02-usecase.rst b/docs/requirements/usecase.rst
index f408cf4..f408cf4 100644
--- a/docs/requirements/02-usecase.rst
+++ b/docs/requirements/usecase.rst