Update message flow for shim-layer architecture

This patch is updating the message flow for "capacity management",
"reservation management", and "allocation management" for the shim-layer
architecture.
It also starts a new (but still empty) section on the shim-layers
internal logic and operations. This section will be updated with a
separate patch.

JIRA: PROMISE-63

Change-Id: I131a5c34c7e145153831556321e7366af0401c8c
(cherry picked from commit 555f6877d454259230db9444be7ca1d2c8994ff3)

6 files changed, 187 insertions, 41 deletions

diff --git a/docs/requirements/NB_interface.rst b/docs/requirements/NB_interface.rst
index 28c25ae..3a38191 100644
--- a/docs/requirements/NB_interface.rst
+++ b/docs/requirements/NB_interface.rst
@@ -1,3 +1,5 @@
+.. _northbound_API:
+
 Detailed northbound interface specification
 ===========================================
 
diff --git a/docs/requirements/images/figure5_new.png b/docs/requirements/images/figure5_new.png
new file mode 100644
index 0000000..9307aa2
--- /dev/null
+++ b/docs/requirements/images/figure5_new.png
diff --git a/docs/requirements/images/figure6_new.png b/docs/requirements/images/figure6_new.png
new file mode 100644
index 0000000..5ec4b43
--- /dev/null
+++ b/docs/requirements/images/figure6_new.png
diff --git a/docs/requirements/images/figure7_new.png b/docs/requirements/images/figure7_new.png
new file mode 100644
index 0000000..6684949
--- /dev/null
+++ b/docs/requirements/images/figure7_new.png
diff --git a/docs/requirements/impl_architecture.rst b/docs/requirements/impl_architecture.rst
index 46cbba1..4022231 100644
--- a/docs/requirements/impl_architecture.rst
+++ b/docs/requirements/impl_architecture.rst
@@ -1,92 +1,234 @@
 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
+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.
+the capacity management, resource reservation, and resource allocation features.
 
 
 Detailed Message Flows
 ^^^^^^^^^^^^^^^^^^^^^^
 
-.. note:: This section has to be updated.
+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.png
+.. figure:: images/figure5_new.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:
+capacity management functional blocks inside the shim-layer. It has the
+following steps:
 
-Step 1: The consumer subscribes to capacity change notifications
+    * 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 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 1b: The shim-layer will respond with information about the
+      total, available, reserved, and used (allocated) capacities matching the
+      filter.
 
-Step 3: Capacity changes are notified to the consumer
+    * 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 4: The consumer queries the Capacity Manager to retrieve capacity detailed
-information
+    * 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.png
+.. figure:: images/figure6_new.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:
+: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 1: The consumer creates a resource reservation request for future use by
-setting a start and end time for the allocation
+    * 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 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 7b: Promise sends a notification message to the subscribed
+      Consumer with information on the allocated resources including their new
+      VMState.
 
-Step 3: The consumer subscribes to reservation notification events
+    * 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 4: The Resource Reservation Manager checks the feasibility of the
-reservation request by consulting the Capacity Manager
+    * Step 9a: Promise sends a *deleteServer* request for the instance_id
+      to the VIM Controller.
 
-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 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 6: Once the reservation process is completed, the VIM sends a notification
-message to the consumer with information on the reserved resources
+    * Step 10b: The shim-layer also notifies the subscribed Consumer about
+      the successfully destroyed instance.
 
-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".
+Internal operations
+^^^^^^^^^^^^^^^^^^^
 
-Step 9: The consumer subscribes to allocation notification events
+.. note:: This section is to be updated
 
-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
+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).
 
-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
diff --git a/docs/requirements/schemas.rst b/docs/requirements/schemas.rst
index 479c9a8..de9d9f8 100644
--- a/docs/requirements/schemas.rst
+++ b/docs/requirements/schemas.rst
@@ -1,3 +1,5 @@
+.. _yang_schema:
+
 ANNEX B: Promise YANG schema based on YangForge
 ===============================================