docs/userguide/featureusage.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 Promise capabilities and usage
   5 ==============================
   6
   7 Promise is a resource reservation and management project to identify NFV related
   8 requirements and realize resource reservation for future usage by capacity
   9 management of resource pools regarding compute, network and storage.
  10
  11 The following are the key features provided by this module:
  12
  13 * Capacity Management
  14 * Reservation Management
  15 * Allocation Management
  16
  17 The Brahmaputra implementation of Promise is built with the YangForge data
  18 modeling framework [#f2]_ , using a shim-layer on top of OpenStack to provide
  19 the Promise features. This approach requires communication between
  20 Consumers/Administrators and OpenStack to pass through the shim-layer. The
  21 shim-layer intercepts the message flow to manage the allocation requests based
  22 on existing reservations and available capacities in the providers. It also
  23 extracts information from the intercepted messages in order to update its
  24 internal databases. Furthermore, Promise provides additional intent-based APIs
  25 to allow a Consumer or Administrator to perform capacity management (i.e. add
  26 providers, update the capacity, and query the current capacity and utilization
  27 of a provider), reservation management (i.e. create, update, cancel, query
  28 reservations), and allocation management (i.e. create, destroy, query
  29 instances).
  30
  31 Detailed information about Promise use cases, features, interface
  32 specifications, work flows, and the underlying Promise YANG schema can be found
  33 in the Promise requirement document [#f1]_ .
  34
  35
  36 Promise usage
  37 -------------
  38
  39 The yfc run command will load the primary application package from this
  40 repository along with any other dependency files/assets referenced within the
  41 YAML manifest and instantiate the opnfv-promise module and run REST/JSON
  42 interface by default listeningon port 5000.::
  43     $ yfc run promise.yaml
  44
  45
  46 You can also checkout the GIT repository (https://github.com/opnfv/promise/) or
  47 simply download the files into your local system and run the application.
  48
  49
  50 Promise feature and API usage guidelines and examples
  51 -----------------------------------------------------
  52
  53 This section lists the Promise features and API implemented in OPNFV Brahmaputra.
  54
  55
  56 Note 1: In contrast to ETSI NFV specifications and the detailed interface
  57 specification in Section 7, the Promise shim-layer implementation does not
  58 distinguish intent interfaces per resource type, i.e. the various capacity,
  59 reservations, etc. operations have different endpoints for each domain such as
  60 compute, storage, and network. The current shim-layer implementation does not
  61 separate the endpoints for performing the various operations.
  62
  63 Note 2: The listed parameters are optional unless explicitly marked as
  64 "mandatory".
  65
  66
  67 Reservation management
  68 ^^^^^^^^^^^^^^^^^^^^^^
  69
  70 The reservation management allows a Consumer to request reservations for
  71 resource capacity or specific resource elements. Reservations can be for now or
  72 a later time window. After the start time of a reservation has arrived, the
  73 Consumer can issue create server instance requests against the reserved
  74 capacity / elements. Note, a reservation will expire after a predefined
  75 *expiry* time in case no allocation referring to the reservation is requested.
  76
  77 The implemented workflow is well aligned with the described workflow in the
  78 Promise requirement document [#f1]_ (Clause 6.1) except for the
  79 "multi-provider" scenario as described in :ref:`multi-provider` .
  80
  81 .. _create-reservation:
  82
  83 *create-reservation*
  84 """"""""""""""""""""
  85
  86 This operation allows making a request to the reservation system to reserve
  87 resources. The Consumer can either request to reserve a certain capacity
  88 (*container*) or specific resource elements (*elements*), like a certain server
  89 instance.
  90
  91 The operation takes the following input parameters:
  92
  93 * start: start time of the requested reservation
  94 * end: end time of the requested reservation
  95 * container: request for reservation of capacity
  96
  97   * instances: number of instances
  98   * cores: number of cores
  99   * ram: size of ram (in MB)
 100   * networks: number of networks
 101   * addresses: number of (public) IP addresses
 102   * ports: number of ports
 103   * routers: number of routers
 104   * subnets: number of subnets
 105   * gigabytes: size of storage (in GB)
 106   * volumes: number of volumes
 107   * snapshots: number of snapshots
 108
 109 * elements: reference to a list of 'pre-existing' resource elements that are
 110   required for fulfillment of the resource-usage-request
 111
 112   * instance-identifier: identifier of a specific resource element
 113
 114 * zone: identifier of an Availability Zone
 115
 116 Promise will check the available capacity in the given time window and in case
 117 sufficient capacity exists to meet the reservation request, will mark those
 118 resources "reserved" in its reservation map.
 119
 120
 121 *update-reservation*
 122 """"""""""""""""""""
 123
 124 This operation allows to update the reservation details for an existing
 125 reservation.
 126
 127 It can take the same input parameters as in *create-reservation*
 128 but in addition requires a mandatory reference to the *reservation-id* of the
 129 reservation that shall be updated.
 130
 131
 132 *cancel-reservation*
 133 """"""""""""""""""""
 134
 135 This operation is used to cancel an existing reservation.
 136
 137 The operation takes the following input parameter:
 138
 139 * reservation-id (mandatory): identifier of the reservation to be canceled.
 140
 141
 142 *query-reservation*
 143 """""""""""""""""""
 144
 145 The operation queries the reservation system to return reservation(s) matching
 146 the specified query filter, e.g., reservations that are within a specified
 147 start/end time window.
 148
 149 The operation takes the following input parameters to narrow down the query
 150 results:
 151
 152 * zone: identifier of an Availability Zone
 153 * without: excludes specified collection identifiers from the result
 154 * elements:
 155
 156   * some: query for ResourceCollection(s) that contain some or more of these
 157     element(s)
 158   * every: query for ResourceCollection(s) that contain all of these
 159     element(s)
 160
 161 * window: matches entries that are within the specified start/end time window
 162
 163   * start: start time
 164   * end: end time
 165   * scope: if set to 'exclusive', only reservations with start AND end time
 166     within the time window are returned. Otherwise ('inclusive'), all
 167     reservation starting OR ending in the time windows are returned.
 168
 169 * show-utilization: boolean value that specifies whether to also return the
 170   resource utilization in the queried time window or not
 171
 172
 173 *subscribe-reservation-events* / *notify-reservation-events*
 174 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 175
 176 Subscription to receive notifications about reservation-related events, e.g. a
 177 reservation is about to expire or a reservation is in conflict state due to a
 178 failure in the NFVI.
 179
 180 Note, this feature is not yet available in Brahmaputra release.
 181
 182
 183
 184 Allocation management
 185 ^^^^^^^^^^^^^^^^^^^^^
 186
 187 *create-instance*
 188 """""""""""""""""
 189
 190 This operation is used to create an instance of specified resource(s) for
 191 immediate use utilizing capacity from the pool. *Create-instance* requests can
 192 be issued against an existing reservation, but also allocations without a
 193 reference to an existing reservation are allowed. In case the allocation
 194 request specifies a reservation identifier, Promise checks if a reservation
 195 with that ID exists, the reservation start time has arrived (i.e. the
 196 reservation is 'active'), and the required capacity for the requested flavor is
 197 within the available capacity of the reservation. If those conditions are met,
 198 Promise creates a record for the allocation (VMState="INITIALIZED") and update
 199 its databases. If no *reservation_id* was provided in the allocation request,
 200 Promise checks whether the required capacity to meet the request can be
 201 provided from the available, non-reserved capacity. If yes, Promise creates a
 202 record for the allocation with an unique *instance-id* and update its
 203 databases. In any other case, Promise rejects the *create-instance* request.
 204
 205 In case the *create-instance* request is rejected, Promise responds with a
 206 "status=rejected" providing the reason of the rejection. This will help the
 207 Consumer to take appropriate actions, e.g., send an updated *create-instance*
 208 request. In case the *create-instance* request was accepted and a related
 209 allocation record has been created, the shim-layer issues a *createServer*
 210 request to the VIM Controller providing all information to create the server
 211 instance.
 212
 213 The operation takes the following input parameters:
 214
 215 * name (mandatory): Assigned name for the instance to be created
 216 * image (mandatory): the image to be booted in the new instance
 217 * flavor (mandatory): the flavor of the requested server instance
 218 * networks: the list of network uuids of the requested server instance
 219 * provider-id: identifier of the provider where the instance shall be created
 220 * reservation-id: identifier of a resource reservation the *create-instance*
 221   is issued against
 222
 223 The Brahamputra implementation of Promise has the following limitations:
 224
 225 * All create server instance requests shall pass through the Promise
 226   shim-layer such that Promise can keep track of all allocation requests. This
 227   is necessary as in the current release the sychronization between the VIM
 228   Controller and Promise on the available capacity is not yet implemented.
 229 * *Create-allocation* requests are limited to "simple" allocations, i.e., the
 230   current workflow only supports the Nova compute service and
 231   *create-allocation* requests are limited to creating one server instance at a
 232   time
 233 * Prioritization of reservations and allocations is yet not implemented.
 234   Future version may allow certain policy-based conflict resolution where,
 235   e.g., new allocation request with high priority can "forcefully" terminate
 236   lower priority allocations.
 237
 238
 239 *destroy-instance*
 240 """"""""""""""""""
 241
 242 This operation request to destroy an existing server instance and release it
 243 back to the pool.
 244
 245 The operation takes the following input parameter:
 246
 247 * instance-id: identifier of the server instance to be destroyed
 248
 249
 250 *query-resource-collection*
 251 """""""""""""""""""""""""""
 252
 253 This operation allows to query for resource collection(s) that are within the
 254 specified start/end time window.
 255
 256
 257 *subscribe-allocation-events* / *notify-allocation-events*
 258 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""
 259
 260 Subscription to receive notifications about allocation-related events, e.g. an
 261 allocation towards the VIM that did not pass the Promise shim-layer
 262
 263 Note, this feature is not yet available in Brahmaputra release.
 264
 265
 266
 267 Capacity management
 268 ^^^^^^^^^^^^^^^^^^^
 269
 270 The capacity management feature allows the Consumer or Administrator to do
 271 capacity planning, i.e. the capacity available to the reservation management
 272 can differ from the actual capacity in the registered provider(s). This feature
 273 can, e.g., be used to limit the available capacity for a given time window due
 274 to a planned downtime of some of the resources, or increase the capacity
 275 available to the reservation system in case of a plannes upgrade of the
 276 available capacity.
 277
 278 *increase/decrease-capacity*
 279 """"""""""""""""""""""""""""
 280
 281 This operations allows to increase/decrease the total capacity that is made
 282 available to the Promise reservation service between a specified window in
 283 time. It does NOT increase the actual capacity of a given resource provider,
 284 but is used for capacity management inside Promise.
 285
 286 This feature can be used in different ways, like
 287
 288 * Limit the capacity available to the reservation system to a value below 100%
 289   of the available capacity in the VIM, e.g., in order to leave "buffer" in the
 290   actual NFVI to be used outside the Promise reservation service.
 291
 292 * Inform the reservation system that, from a given time in the future,
 293   additional resources can be reserved, e.g., due to a planned upgrade of the
 294   available capacity of the provider.
 295
 296 * Similarily, the "decrease-capacity" can be used to reduce the consumable
 297   resources in a given time window, e.g., to prepare for a planned downtime of
 298   some of the resources.
 299
 300 * Expose multiple reservation service instances to different consumers sharing
 301   the same resource provider.
 302
 303 The operation takes the following input parameters:
 304
 305 * start: start time for the increased/decreased capacity
 306
 307 * end: end time for the increased/decreased capacity
 308
 309 * container: see :ref:`create-reservation`
 310
 311 Note, increase/decreasing the capacity in Promise is completely transparent to
 312 the VIM. As such, when increasing the virtual capacity in Promise (e.g. for a
 313 planned upgrade of the capacity), it is in the responsibility of the
 314 Consumer/Administrator to ensure sufficient resources in the VIM are available
 315 at the appropriate time, in order to prevent allocations against reservations
 316 to fail due to a lack of resources. Therefore, this operations should only be
 317 used carefully.
 318
 319
 320 *query-capacity*
 321 """"""""""""""""
 322
 323 This operation is used to query the available capacity information of the
 324 specified resource collection. A filter attribute can be specified to narrow
 325 down the query results.
 326
 327 The current implementation supports the following filter criteria:
 328
 329 * time window: returns reservations matching the specified window
 330
 331 * window scope: if set to 'exclusive', only reservations with start AND end time
 332   within the time window are returned. Otherwise, all reservation starting OR
 333   ending in the time windows are returned.
 334
 335 * metric: query for one of the following capacity metrics:
 336
 337   * 'total': resource pools
 338   * 'reserved': reserved resources
 339   * 'usage': resource allocations
 340   * 'available': remaining capacity, i.e. neither reserved nor allocated
 341
 342
 343 *subscribe-capacity-events* / *notify-capacity-events*
 344 """"""""""""""""""""""""""""""""""""""""""""""""""""""
 345
 346 These operations enable the Consumer to subscribe to receiving notifications
 347 about capacity-related events, e.g., increased/decreased capacity for a
 348 provider due to a failure or upgrade of a resource pool. In order to provide
 349 such notifications to its Consumers, Promise shim-layer has to subscribe itself
 350 to OpenStack Aodh to be notified from the VIM about any capacity related events.
 351
 352 Note, this feature is not yet available in Brahmaputra release.
 353
 354
 355 .. _multi-provider:
 356
 357 (Multi-)provider management
 358 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 359
 360 This API  towards OpenStack allows an Consumer/Administrator to add and remove
 361 resource providers to Promise. Note, Promise supports a multi-provider
 362 configuration, however, for Brahmaputra, multi-provider support is not yet
 363 fully supported.
 364
 365 *add-provider*
 366 """"""""""""""
 367
 368 This operation is used to register a new resource provider into the Promise
 369 reservation system.
 370
 371 Note, for Brahmaputra, the add-provider operation should only be used to
 372 register one provider with the Promise shim-layer. Further note that currently
 373 only OpenStack is supported as a provider.
 374
 375 The operation takes the following input parameters:
 376
 377 * provider-type (mandatory) = 'openstack': select a specific resource provider
 378   type.
 379 * endpoint (mandatory): target URL endpoint for the resource provider.
 380 * username (mandatory)
 381 * password (mandatory)
 382 * region: specified region for the provider
 383 * tenant
 384
 385   * id
 386   * name
 387
 388
 389 *remove-provider*
 390 """""""""""""""""
 391 This operation removes a resource provider from the reservation system. Note,
 392 this feature is not yet available in Brahmaputra release.
 393
 394
 395
 396 .. [#f1] Promise requirement document,
 397    http://http://artifacts.opnfv.org/promise/docs/requirements/index.html
 398
 399 .. [#f2] YangForge framework, http://github.com/opnfv/yangforge