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