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