docs/release/userguide/feature.userguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 Abstract
   5 ========
   6 Promise is a resource reservation and management project to identify NFV related
   7 requirements and realize resource reservation for future usage by capacity
   8 management of resource pools regarding compute, network and storage.
   9
  10 The following are the key features provided by this module:
  11
  12 * Capacity Management
  13 * Reservation Management
  14 * Allocation Management
  15
  16 The following sections provide details on the Promise capabilities and its API usage.
  17
  18 Promise capabilities and usage
  19 ==============================
  20 The Danube implementation of Promise is built with the YangForge data modeling
  21 framework [#f2]_ , using a shim-layer on top of OpenStack to provide
  22 the Promise features. This approach requires communication between
  23 Consumers/Administrators and OpenStack to pass through the shim-layer. The
  24 shim-layer intercepts the message flow to manage the allocation requests based
  25 on existing reservations and available capacities in the providers. It also
  26 extracts information from the intercepted messages in order to update its
  27 internal databases. Furthermore, Promise provides additional intent-based APIs
  28 to allow a Consumer or Administrator to perform capacity management (i.e. add
  29 providers, update the capacity, and query the current capacity and utilization
  30 of a provider), reservation management (i.e. create, update, cancel, query
  31 reservations), and allocation management (i.e. create, destroy instances).
  32
  33 Detailed information about Promise use cases, features, interface
  34 specifications, work flows, and the underlying Promise YANG schema can be found
  35 in the Promise requirement document [#f1]_ .
  36
  37 Promise features and API usage guidelines and examples
  38 ------------------------------------------------------
  39 This section lists the Promise features and API implemented in OPNFV Danube.
  40
  41 Note: The listed parameters are optional unless explicitly marked as "mandatory".
  42
  43 Reservation management
  44 ^^^^^^^^^^^^^^^^^^^^^^
  45 The reservation management allows a Consumer to request reservations for
  46 resource capacity. Reservations can be for now or a later time window.
  47 After the start time of a reservation has arrived, the Consumer can issue
  48 create server instance requests against the reserved capacity. Note, a
  49 reservation will expire after a predefined *expiry* time in case no
  50 allocation referring to the reservation is requested.
  51
  52 The implemented workflow is well aligned with the described workflow in the
  53 Promise requirement document [#f1]_ (Section 6.1) except for the
  54 "multi-provider" scenario as described in :ref:`multi-provider` .
  55
  56 .. _create-reservation:
  57
  58 *create-reservation*
  59 """"""""""""""""""""
  60
  61 This operation allows making a request to the reservation system to reserve
  62 resources.
  63
  64 The operation takes the following input parameters:
  65
  66 * start: start time of the requested reservation
  67 * end: end time of the requested reservation
  68 * capacity.instances: amount of instances to be reserved
  69 * capacity.cores: amount of cores to be reserved
  70 * capacity.ram: amount of ram in MB to be reserved
  71
  72 Promise will check the available capacity in the given time window and in case
  73 sufficient capacity exists to meet the reservation request, will mark those
  74 resources "reserved" in its reservation map.
  75
  76 *update-reservation*
  77 """"""""""""""""""""
  78
  79 This operation allows to update the reservation details for an existing
  80 reservation.
  81
  82 It can take the same input parameters as in *create-reservation*
  83 but in addition requires a mandatory reference to the *reservation-id* of the
  84 reservation that shall be updated.
  85
  86 *cancel-reservation*
  87 """"""""""""""""""""
  88
  89 This operation is used to cancel an existing reservation.
  90
  91 The operation takes the following input parameter:
  92
  93 * reservation-id (mandatory): identifier of the reservation to be canceled.
  94
  95 *query-reservation*
  96 """""""""""""""""""
  97
  98 The operation queries the reservation system to return reservation(s) matching
  99 the specified query filter, e.g., reservations that are within a specified
 100 start/end time window.
 101
 102 The operation takes the following input parameters to narrow down the query
 103 results:
 104
 105 * without: excludes specified collection identifiers from the result
 106 * elements.some: query for ResourceCollection(s) that contain some or more of these element(s)
 107 * elements.every: query for ResourceCollection(s) that contain all of these element(s)
 108 * window.start: matches entries that are within the specified start/
 109 * window.end: end time window
 110 * window.scope: if set to 'exclusive', only reservations with start AND end time
 111     within the time window are returned. Otherwise ('inclusive'), all
 112     reservation starting OR ending in the time windows are returned.
 113 * show-utilization: boolean value that specifies whether to also return the
 114   resource utilization in the queried time window or not
 115
 116 Allocation management
 117 ^^^^^^^^^^^^^^^^^^^^^
 118
 119 *create-instance*
 120 """""""""""""""""
 121
 122 This operation is used to create an instance of specified resource(s) for
 123 immediate use utilizing capacity from the pool. *Create-instance* requests can
 124 be issued against an existing reservation, but also allocations without a
 125 reference to an existing reservation are allowed. In case the allocation
 126 request specifies a reservation identifier, Promise checks if a reservation
 127 with that ID exists, the reservation start time has arrived (i.e. the
 128 reservation is 'active'), and the required capacity for the requested flavor is
 129 within the available capacity of the reservation. If those conditions are met,
 130 Promise creates a record for the allocation (VMState="INITIALIZED") and update
 131 its databases. If no *reservation_id* was provided in the allocation request,
 132 Promise checks whether the required capacity to meet the request can be
 133 provided from the available, non-reserved capacity. If yes, Promise creates a
 134 record for the allocation with an unique *instance-id* and update its
 135 databases. In any other case, Promise rejects the *create-instance* request.
 136
 137 In case the *create-instance* request is rejected, Promise responds with a
 138 "status=rejected" providing the reason of the rejection. This will help the
 139 Consumer to take appropriate actions, e.g., send an updated *create-instance*
 140 request. In case the *create-instance* request was accepted and a related
 141 allocation record has been created, the shim-layer issues a *createServer*
 142 request to the VIM Controller (i.e. Nova) providing all information to create
 143 the server instance.
 144
 145 The operation takes the following input parameters:
 146
 147 * name (mandatory): Assigned name for the instance to be created
 148 * image (mandatory): the image to be booted in the new instance
 149 * flavor (mandatory): the flavor of the requested server instance
 150 * networks: the list of network uuids of the requested server instance
 151 * provider-id: identifier of the provider where the instance shall be created
 152 * reservation-id: identifier of a resource reservation the *create-instance*
 153
 154 The Danube implementation of Promise has the following limitations:
 155
 156 * All create server instance requests shall pass through the Promise
 157   shim-layer such that Promise can keep track of all allocation requests. This
 158   is necessary as in the current release the sychronization between the VIM
 159   Controller and Promise on the available capacity is not yet implemented.
 160 * *Create-allocation* requests are limited to "simple" allocations, i.e., the
 161   current workflow only supports the Nova compute service and
 162   *create-allocation* requests are limited to creating one server instance at a
 163   time
 164 * Prioritization of reservations and allocations is yet not implemented.
 165   Future version may allow certain policy-based conflict resolution where,
 166   e.g., new allocation request with high priority can "forcefully" terminate
 167   lower priority allocations.
 168
 169
 170 *destroy-instance*
 171 """"""""""""""""""
 172
 173 This operation request to destroy an existing server instance and release it
 174 back to the pool.
 175
 176 The operation takes the following input parameter:
 177
 178 * instance-id: identifier of the server instance to be destroyed
 179
 180 Capacity management
 181 ^^^^^^^^^^^^^^^^^^^
 182 The capacity management feature allows the Consumer or Administrator to do
 183 capacity planning, i.e. the capacity available to the reservation management
 184 can differ from the actual capacity in the registered provider(s). This feature
 185 can, e.g., be used to limit the available capacity for a given time window due
 186 to a planned downtime of some of the resources, or increase the capacity
 187 available to the reservation system in case of a planned upgrade of the
 188 available capacity.
 189
 190 *increase/decrease-capacity*
 191 """"""""""""""""""""""""""""
 192
 193 This operations allows to increase/decrease the total capacity that is made
 194 available to the Promise reservation service between a specified window in
 195 time. It does NOT increase the actual capacity of a given resource provider,
 196 but is used for capacity management inside Promise.
 197
 198 This feature can be used in different ways, like
 199
 200 * Limit the capacity available to the reservation system to a value below 100%
 201   of the available capacity in the VIM, e.g., in order to leave "buffer" in the
 202   actual NFVI to be used outside the Promise reservation service.
 203
 204 * Inform the reservation system that, from a given time in the future,
 205   additional resources can be reserved, e.g., due to a planned upgrade of the
 206   available capacity of the provider.
 207
 208 * Similarily, the "decrease-capacity" can be used to reduce the consumable
 209   resources in a given time window, e.g., to prepare for a planned downtime of
 210   some of the resources.
 211
 212 * Expose multiple reservation service instances to different consumers sharing
 213   the same resource provider.
 214
 215 The operation takes the following input parameters:
 216
 217 * start: start time for the increased/decreased capacity
 218 * end: end time for the increased/decreased capacity
 219 * capacity.cores: Increased/decreased amount of cores
 220 * capacity.ram: Increased/decreased amount of RAM
 221 * capacity.instances: Increased/decreased amount of instances
 222
 223 Note, increase/decreasing the capacity in Promise is completely transparent to
 224 the VIM. As such, when increasing the virtual capacity in Promise (e.g. for a
 225 planned upgrade of the capacity), it is in the responsibility of the
 226 Consumer/Administrator to ensure sufficient resources in the VIM are available
 227 at the appropriate time, in order to prevent allocations against reservations
 228 to fail due to a lack of resources. Therefore, this operations should only be
 229 used carefully.
 230
 231
 232 *query-capacity*
 233 """"""""""""""""
 234
 235 This operation is used to query the available capacity information of the
 236 specified resource collection. A filter attribute can be specified to narrow
 237 down the query results.
 238
 239 The current implementation supports the following filter criteria:
 240
 241 * time window: returns reservations matching the specified window
 242
 243 * window scope: if set to 'exclusive', only reservations with start AND end time
 244   within the time window are returned. Otherwise, all reservation starting OR
 245   ending in the time windows are returned.
 246
 247 * metric: query for one of the following capacity metrics:
 248
 249   * 'total': resource pools
 250   * 'reserved': reserved resources
 251   * 'usage': resource allocations
 252   * 'available': remaining capacity, i.e. neither reserved nor allocated
 253
 254 .. _multi-provider:
 255
 256 (Multi-)provider management
 257 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 258
 259 This API  towards OpenStack allows a Consumer/Administrator to add and remove
 260 resource providers to Promise. Note, Promise supports a multi-provider
 261 configuration, however, for Danube, multi-provider support is not yet
 262 fully supported.
 263
 264 *add-provider*
 265 """"""""""""""
 266
 267 This operation is used to register a new resource provider into the Promise
 268 reservation system.
 269
 270 Note, for Danube, the add-provider operation should only be used to
 271 register one provider with the Promise shim-layer. Further note that currently
 272 only OpenStack is supported as a provider.
 273
 274 The operation takes the following input parameters:
 275
 276 * provider-type (mandatory) = 'openstack': select a specific resource provider
 277   type.
 278 * endpoint (mandatory): target URL endpoint for the resource provider.
 279 * username (mandatory)
 280 * password (mandatory)
 281 * region: specified region for the provider
 282 * tenant.id: id of the OpenStack tenant/project
 283 * tenant.name: name of the OpenStack tenant/project
 284
 285 .. [#f1] Promise requirement document,
 286          http://artifacts.opnfv.org/promise/docs/requirements/index.html
 287
 288 .. [#f2] YangForge framework, http://github.com/opnfv/yangforge
 289