Minor fixes to Promise deliverable

JIRA: PROMISE-23

Change-Id: Ie86e449e0a0e0695cddc29c9e2aeccea87bdb117
Signed-off-by: bertys <souville@docomolab-euro.com>

10 files changed, 329 insertions, 201 deletions

diff --git a/requirements/01-intro.rst b/requirements/01-intro.rst
index fdceaf1..6738df2 100644
--- a/requirements/01-intro.rst
+++ b/requirements/01-intro.rst
@@ -15,10 +15,10 @@ 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 [5], the list of
-gaps in upstream projects, potential implementation architecture and plan, and
-the VIM northbound interface specification for resource reservation and
-capacity management.
+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
 ===================
@@ -34,4 +34,4 @@ 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 [5] and is required in network operation.
+defined in ETSI NFV MAN GS [NFVMAN]_ and is required in network operation.
diff --git a/requirements/03-arch.rst b/requirements/03-arch.rst
index c8fe320..8c4db91 100644
--- a/requirements/03-arch.rst
+++ b/requirements/03-arch.rst
@@ -6,15 +6,16 @@ Architecture Overview
 =====================
 
 .. figure:: images/figure1.png
+   :name: figure1
    :width: 90%
 
    Resource Reservation Architecture
 
-Figure 1 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.
 
@@ -62,38 +63,42 @@ Resource Capacity Management
 ----------------------------
 
 .. figure:: images/figure2.png
+   :name: figure2
    :width: 90%
 
    Resource capacity management message flow: notification of capacity change
 
-Figure 2 shows a high level flow for a use case of resource capacity
+: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
 
-Figure 3 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.
+: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
 
-Figure 4 shows a high level flow for a use case of resource reservation. The
-main steps are:
+: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.
diff --git a/requirements/04-gap.rst b/requirements/04-gap.rst
index cae2698..9532495 100644
--- a/requirements/04-gap.rst
+++ b/requirements/04-gap.rst
@@ -4,7 +4,7 @@ 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 [2] in this first release.
+current OpenStack Blazar project [BLAZAR]_ in this first release.
 
 OpenStack
 =========
diff --git a/requirements/05-impl.rst b/requirements/05-impl.rst
index 2bc0731..9903a54 100644
--- a/requirements/05-impl.rst
+++ b/requirements/05-impl.rst
@@ -469,12 +469,13 @@ Resource Capacity Management
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. figure:: images/figure5.png
+   :name: figure5
    :width: 90%
 
    Capacity Management Scenario
 
-Figure 5 shows a detailed message flow between the consumers and the
-functionalblocks inside the VIM and has the following steps:
+: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
 
@@ -492,12 +493,13 @@ Resource Reservation
 ^^^^^^^^^^^^^^^^^^^^
 
 .. figure:: images/figure6.png
+   :name: figure6
    :width: 90%
 
    Resource Reservation for Future Use Scenario
 
-Figure 6 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 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
diff --git a/requirements/07-schemas.rst b/requirements/07-schemas.rst
index 3887cc7..fdcd249 100644
--- a/requirements/07-schemas.rst
+++ b/requirements/07-schemas.rst
@@ -1,195 +1,306 @@
-Promise YANG Schemas based on StormForge
-----------------------------------------
-
-Promise Schema
-^^^^^^^^^^^^^^
+ANNEX A: PROMISE YANG SCHEMA BASED ON YANGFORGE
+===============================================
 
 .. code::
 
   module opnfv-promise {
-    namespace "urn:opnfv:vim:promise";
-    prefix prom;
+  namespace "urn:opnfv:promise";
+  prefix promise;
 
-    import opnfv-promise-models { prefix opm; }
-    import complex-types { prefix ct; }
+  import complex-types { prefix ct; }
+  import iana-crypt-hash { prefix ianach; }
+  import ietf-inet-types { prefix inet; }
+  import ietf-yang-types { prefix yang; }
+  import opnfv-promise-vim { prefix vim; }
 
-    description
-      "OPNFV Promise Resource Reservation/Allocation controller module";
+  feature multi-provider {
+    description "";
+  }
 
-    revision 2015-04-16 {
-      description
-        "Initial revision.";
-    }
+  description
+    "OPNFV Promise Resource Reservation/Allocation controller module";
 
-    // MAIN CONTAINER
+  revision 2015-04-16 {
+    description "Initial revision.";
+  }
 
-    container promise {
-      ct:instance-list reservations {
-        description
-          "Aggregate collection of all registered ResourceReservation
-           instances";
-        ct:instance-type opm:ResourceReservation;
-      }
+  revision 2015-08-06 {
+    description "Updated to incorporate YangForge framework";
+  }
+
+  grouping resource-capacity {
+    container capacity {
+      container quota { description 'Conceptual container that should be extended'; }
+      container usage { description 'Conceptual container that should be extended';
+                        config false; }
+      container reserved { description 'Conceptual container that should be extended';
+                        config false; }
+      container available { description 'Conceptual container that should be extended';
+			config false; }
     }
+  }
 
-    rpc list-reservations;
-    rpc create-reservation;
-    rpc cancel-reservation;
+  grouping compute-capacity {
+    leaf cores { type number; }
+    leaf ram { type number; }
+    leaf instances { type number; }
+  }
 
-    notification reservation-event;
-    notification capacity-event;
-    notification allocation-event;
+  grouping networking-capacity {
+    leaf network { type number; }
+    leaf port { type number; }
+    leaf router { type number; }
+    leaf subnet { type number; }
+    leaf address { type number; }
   }
 
-OPNFV Promise YANG Schema
-^^^^^^^^^^^^^^^^^^^^^^^^^
+  ct:complex-type ResourceReservation {
+    ct:extends vim:ResourceElement;
 
-.. code::
+    description
+      "Contains the capacities of various resource services being reserved
+       along with any resource elements needed to be available at
+       the time of allocation(s).";
+
+    reference "OPNFV-PROMISE, Section 3.4.1";
+
+    leaf start { type yang:date-and-time; }
+    leaf end   { type yang:date-and-time; }
+    leaf expiry {
+      description "Duration in seconds from start when unallocated reserved resources
+                   will be released back into the pool";
+      type number; units "seconds";
+    }
+    leaf zone { type instance-identifier { ct:instance-type vim:AvailabilityZone; } }
+    container capacity {
+      uses vim:compute-capacity;
+      uses vim:networking-capcity;
+      uses vim:storage-capacity;
+    }
+    leaf-list resources {
+      description
+        "Reference to a collection of existing resource elements required by
+         this reservation. It can contain any instance derived from
+         ResourceElement, such as ServerInstances or even other
+         ResourceReservations. If the ResourceReservation request is
+         accepted, the ResourceElement(s) listed here will be placed
+         into 'protected' mode as to prevent accidental delete.";
+      type instance-identifier {
+        ct:instance-type vim:ResourceElement;
+      }
+      // following 'must' statement applies to each element
+      must "boolean(/provider/elements/*[@id=id])" {
+        error-message "One or more of the ResourceElement(s) does not exist in
+                       the provider to be reserved";
+      }
+    }
 
-  module opnfv-promise-models {
-    prefix opm;
+    leaf provider {
+      if-feature multi-provider;
+      config false;
 
-    import storm-common-models { prefix scm; }
-    import complex-types { prefix ct; }
+      description
+        "Reference to a specified existing provider from which this reservation
+         will be drawn if used in the context of multi-provider
+         environment.";
+      type instance-identifier {
+        ct:instance-type vim:ResourceProvider;
+        require-instance true;
+      }
+    }
 
-    feature resource-reservation;
+    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.";
 
-    ct:complex-type ResourceReservation {
-      ct:extends scm:ResourceElement;
+      uses vim:compute-capacity;
+      uses vim:networking-capcity;
+      uses vim:storage-capacity;
+    }
 
+    leaf-list allocations {
+      config false;
       description
-        "Contains the capacities of various resource services being reserved
-         along with any resource elements needed to be available at
-         the time of allocation(s).";
-
-      reference "OPNFV-PROMISE, Section 3.4.1";
-
-      leaf start { type ct:date-and-time; }
-      leaf end   { type ct:date-and-time; }
-      leaf expiry {
-        description
-          "Duration in seconds from start when unallocated reserved resources
-           will be released back into the pool";
-        type number; units "seconds";
-      }
-      leaf zone {
-        type instance-identifier { ct:instance-type scm:AvailabilityZone; }
-      }
-      container capacity {
-        uses scm:compute-capacity;
-        uses scm:networking-capcity;
-        uses scm:storage-capacity;
-      }
-      leaf-list resources {
-        description
-          "Reference to a collection of existing resource elements required by
-           this reservation. It can contain any instance derived from
-           ResourceElement, such as ServerInstances or even other
-           ResourceReservations. If the ResourceReservation request is
-           accepted, the ResourceElement(s) listed here will be placed
-           into 'protected' mode as to prevent accidental delete.";
-        type instance-identifier {
-          ct:instance-type scm:ResourceElement;
-        }
-        // following 'must' statement applies to each element
-        must "boolean(/provider/elements/*[@id=id])" {
-          error-message
-            "One or more of the ResourceElement(s) does not exist in the
-             provider to be reserved";
-        }
+        "Reference to a collection of consumed allocations referencing
+         this reservation.";
+      type instance-identifier {
+        ct:instance-type ResourceAllocation;
       }
+    }
+  }
 
-      leaf provider {
-        if-feature multi-provider;
-        config false;
+  ct:complex-type ResourceAllocation {
+    ct:extends vim:ResourceElement;
 
-        description
-          "Reference to a specified existing provider from which this
-           reservation will be drawn if used in the context of multi-provider
-           environment.";
-        type instance-identifier {
-          ct:instance-type scm:ResourceProvider;
-          require-instance true;
-        }
-      }
+    description
+       "Contains a list of resources to be allocated with optional reference
+       to an existing reservation.
 
-      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.";
+       If reservation is specified but this request is received prior
+       to reservation start timestamp, then it will be rejected unless
+       'allocate-on-start' is set to true.  'allocate-on-start' allows
+       the allocation to be auto-initiated and scheduled to run in the
+       future.
 
-        uses scm:compute-capacity;
-        uses scm:networking-capcity;
-        uses scm:storage-capacity;
-      }
+       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.
 
-      leaf-list allocations {
-        config false;
-        description
-          "Reference to a collection of consumed allocations referencing
-           this reservation.";
-        type instance-identifier {
-          ct:instance-type ResourceAllocation;
-        }
-      }
+       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";
 
-    ct:complex-type ResourceAllocation {
-      ct:extends scm:ResourceElement;
+      type instance-identifier {
+        ct:instance-type ResourceReservation;
+        require-instance true;
+      }
+    }
 
+    leaf allocate-on-start {
       description
-         "Contains a list of resources to be allocated with optional reference
-         to an existing reservation.
+       "If 'allocate-on-start' is set to true, the 'planned' allocations will
+       take effect automatically at the reservation 'start' date/time.";
+      type boolean; default false;
+    }
 
-         If reservation is specified but this request is received prior
-         to reservation start timestamp, then it will be rejected unless
-         'allocate-on-start' is set to true.  'allocate-on-start' allows
-         the allocation to be auto-initiated and scheduled to run in the
-         future.
+    ct:instance-list resources {
+      description "Contains list of new ResourceElements that will be allocated";
+      ct:instance-type vim:ResourceElement;
+    }
 
-         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.
+    leaf priority {
+      description
+        "Reflects current priority level of the allocation according to classification rules";
+      type number;
+      config false;
+    }
+  }
 
-         Allocations without reference to an existing reservation will
-         receive the lowest priority.";
+  // MAIN CONTAINER
+  container promise {
+    ct:instance-list providers {
+      description "Aggregate collection of all registered ResourceProvider instances";
+      ct:instance-type vim:ResourceProvider;
+      config false;
+
+     // augment compute container with capacity elements
+     augment "compute" {
+       uses resource-capacity {
+         augment "capacity/quota" { uses compute-capacity; }
+         augment "capacity/usage" { uses compute-capacity; }
+         augment "capacity/reserved" { uses compute-capacity; }
+         augment "capacity/available" { uses compute-capacity; }
+       }
+     }
+
+     // augment networking container with capacity elements
+     augment "networking" {
+       uses resource-capacity {
+         if-feature has-networking-capacity;
+         augment "capacity/quota" { uses networking-capacity; }
+         augment "capacity/usage" { uses networking-capacity; }
+         augment "capacity/reserved" { uses networking-capacity; }
+         augment "capacity/available" { uses networking-capacity; }
+       }
+     }
+
+     // track references to reservations for this resource provider
+     leaf-list reservations {
+       type instance-identifier {
+         ct:instance-type ResourceReservation;
+       }
+     }
+    }
 
-      reference "OPNFV-PROMISE, Section 3.4.3";
+    ct:instance-list reservations {
+      description "Aggregate collection of all registered ResourceReservation instances";
+      ct:instance-type ResourceReservation;
+    }
 
-      leaf reservation {
-        description "Reference to an existing reservation identifier";
+    ct:instance-list allocations {
+      description "Aggregate collection of all active ResourceAllocation instances";
+      ct:instance-type ResourceAllocation;
+    }
+  }
 
-        type instance-identifier {
-          ct:instance-type ResourceReservation;
-          require-instance true;
+  rpc add-provider {
+    description "This operation allows you to register a new ResourceProvider
+                 into promise management service";
+    input {
+      leaf provider {
+        description "Select a specific resource provider";
+        mandatory true;
+        type enumeration {
+          enum openstack;
+          enum hp;
+          enum rackspace;
+          enum amazon {
+            status planned;
+          }
+          enum joyent {
+            status planned;
+          }
+          enum azure {
+            status planned;
+          }
         }
       }
-
-      leaf allocate-on-start {
-        description
-         "If 'allocate-on-start' is set to true, the 'planned' allocations will
-         take effect automatically at the reservation 'start' date/time.";
-        type boolean; default false;
+      leaf username {
+        type string;
+        mandatory true;
       }
-
-      ct:instance-list resources {
-        description "Contains list of new ResourceElements that will be
-                     allocated";
-        ct:instance-type scm:ResourceElement;
+      leaf password {
+        type ianach:crypt-hash;
+        mandatory true;
       }
-
-      leaf priority {
-        description
-          "Reflects current priority level of the allocation according to
-           classification rules";
-        type number;
-        config false;
+      leaf endpoint {
+        type inet:uri;
+        description "The target URL endpoint for the resource provider";
+        mandatory true;
+      }
+      leaf region {
+        type string;
+        description "Optional specified regsion for the provider";
       }
     }
+    output {
+      leaf id {
+        description "Unique identifier for the newly added provider found in /promise/providers";
+        type instance-identifier {
+          ct:instance-type ResourceProvider;
+        }
+      }
+      leaf result {
+        type enumeration {
+          enum success;
+          enum error;
+        }
+      }
+    }
+  }
+  rpc remove-provider;
+  rpc list-providers;
+
+  rpc check-capacity;
+
+  rpc list-reservations;
+  rpc create-reservation;
+  rpc update-reservation;
+  rpc cancel-reservation;
+
+  rpc list-allocations;
+  rpc create-allocation;
+
+  notification reservation-event;
+  notification capacity-event;
+  notification allocation-event;
   }
 
-.. -*
diff --git a/requirements/08-revision.rst b/requirements/08-revision.rst
new file mode 100644
index 0000000..2db306d
--- /dev/null
+++ b/requirements/08-revision.rst
@@ -0,0 +1,12 @@
+ANNEX B: DOCUMENT REVISION
+==========================
+
++---------+-----------------------------------------+
+| Version |      Description                        |
++---------+-----------------------------------------+
+| 1.0.1   | JIRA: PROMISE-23                        |
+|         |  - Reference to YangForge Framework     |
+|         |  - Corrections to figure 3.1            |
++---------+-----------------------------------------+
+|         |                                         |
++---------+-----------------------------------------+
diff --git a/requirements/99-references.rst b/requirements/99-references.rst
new file mode 100644
index 0000000..4dd4845
--- /dev/null
+++ b/requirements/99-references.rst
@@ -0,0 +1,19 @@
+.. [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/requirements/glossary.rst b/requirements/glossary.rst
index e56f31e..99b593f 100644
--- a/requirements/glossary.rst
+++ b/requirements/glossary.rst
@@ -11,7 +11,7 @@ mapping/translating the OPNFV terms to terminology used in other contexts.
 
    Consumer
       User-side Manager; consumer of the interfaces produced by the VIM; VNFM,
-      NFVO, or Orchestrator in ETSI NFV [7] terminology.
+      NFVO, or Orchestrator in ETSI NFV [NFV003]_ terminology.
 
    NFV
       Network Function Virtualization
diff --git a/requirements/images/figure1.png b/requirements/images/figure1.png
index ef78c00..065a995 100755..100644
--- a/requirements/images/figure1.png
+++ b/requirements/images/figure1.png
diff --git a/requirements/index.rst b/requirements/index.rst
index ddaa8b2..0b4ffcb 100644
--- a/requirements/index.rst
+++ b/requirements/index.rst
@@ -51,30 +51,9 @@ Promise: Resource Management
    04-gap.rst
    05-impl.rst
    06-summary.rst
+   07-schemas.rst
+   08-revision.rst
+   99-references.rst
 
-.. raw:: latex
-
-    \newpage
-
-.. rubric::  References and bibliography
-
-[1] OPNFV, "Promise" requirement project, [Online]. Available at
-https://wiki.opnfv.org/doctor
-
-[2] OpenStack Blazar Project, [Online]. Available at
-https://wiki.openstack.org/wiki/Blazar
-
-[3] Stormforge Project, [Online]. Available at
-https://github.com/stormstack/stormforge
-
-[4] Stormify Project, [Online]. Available at
-https://github.com/stormstack/stormify
-
-[5] ETSI GS NFV MAN 001, "Network Function Virtualisation (NFV); Management
-and Orchestration"
-
-[6] ETSI GS NFV 003, "Network Function Virtualisation (NFV); Terminology
-for Main Concepts in NFV"
-
-[7] ETSI NFV, [Online]. Available at
-http://www.etsi.org/technologies-clusters/technologies/nfv
+..
+  vim: set tabstop=4 expandtab textwidth=80: