1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
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.
10 The following are the key features provided by this module:
13 * Reservation Management
14 * Allocation Management
16 The following sections provide details on the Promise capabilities and its API usage.
18 Promise capabilities and usage
19 ==============================
20 The Euphrates 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).
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]_ .
37 Keystone v3 support has been added during the Euphrates release.
40 Promise features and API usage guidelines and examples
41 ------------------------------------------------------
42 This section lists the Promise features and API implemented in OPNFV Euphrates.
44 Note: The listed parameters are optional unless explicitly marked as "mandatory".
46 Reservation management
47 ^^^^^^^^^^^^^^^^^^^^^^
48 The reservation management allows a Consumer to request reservations for
49 resource capacity. Reservations can be for now or a later time window.
50 After the start time of a reservation has arrived, the Consumer can issue
51 create server instance requests against the reserved capacity. Note, a
52 reservation will expire after a predefined *expiry* time in case no
53 allocation referring to the reservation is requested.
55 The implemented workflow is well aligned with the described workflow in the
56 Promise requirement document [#f1]_ (Section 6.1) except for the
57 "multi-provider" scenario as described in :ref:`multi-provider` .
59 .. _create-reservation:
64 This operation allows making a request to the reservation system to reserve
67 The operation takes the following input parameters:
69 * start: start time of the requested reservation
70 * end: end time of the requested reservation
71 * capacity.instances: amount of instances to be reserved
72 * capacity.cores: amount of cores to be reserved
73 * capacity.ram: amount of ram in MB to be reserved
75 Promise will check the available capacity in the given time window and in case
76 sufficient capacity exists to meet the reservation request, will mark those
77 resources "reserved" in its reservation map.
82 This operation allows to update the reservation details for an existing
85 It can take the same input parameters as in *create-reservation*
86 but in addition requires a mandatory reference to the *reservation-id* of the
87 reservation that shall be updated.
92 This operation is used to cancel an existing reservation.
94 The operation takes the following input parameter:
96 * reservation-id (mandatory): identifier of the reservation to be canceled.
101 The operation queries the reservation system to return reservation(s) matching
102 the specified query filter, e.g., reservations that are within a specified
103 start/end time window.
105 The operation takes the following input parameters to narrow down the query
108 * without: excludes specified collection identifiers from the result
109 * elements.some: query for ResourceCollection(s) that contain some or more of these element(s)
110 * elements.every: query for ResourceCollection(s) that contain all of these element(s)
111 * window.start: matches entries that are within the specified start/
112 * window.end: end time window
113 * window.scope: if set to 'exclusive', only reservations with start AND end time
114 within the time window are returned. Otherwise ('inclusive'), all
115 reservation starting OR ending in the time windows are returned.
116 * show-utilization: boolean value that specifies whether to also return the
117 resource utilization in the queried time window or not
119 Allocation management
120 ^^^^^^^^^^^^^^^^^^^^^
125 This operation is used to create an instance of specified resource(s) for
126 immediate use utilizing capacity from the pool. *Create-instance* requests can
127 be issued against an existing reservation, but also allocations without a
128 reference to an existing reservation are allowed. In case the allocation
129 request specifies a reservation identifier, Promise checks if a reservation
130 with that ID exists, the reservation start time has arrived (i.e. the
131 reservation is 'active'), and the required capacity for the requested flavor is
132 within the available capacity of the reservation. If those conditions are met,
133 Promise creates a record for the allocation (VMState="INITIALIZED") and update
134 its databases. If no *reservation_id* was provided in the allocation request,
135 Promise checks whether the required capacity to meet the request can be
136 provided from the available, non-reserved capacity. If yes, Promise creates a
137 record for the allocation with an unique *instance-id* and update its
138 databases. In any other case, Promise rejects the *create-instance* request.
140 In case the *create-instance* request is rejected, Promise responds with a
141 "status=rejected" providing the reason of the rejection. This will help the
142 Consumer to take appropriate actions, e.g., send an updated *create-instance*
143 request. In case the *create-instance* request was accepted and a related
144 allocation record has been created, the shim-layer issues a *createServer*
145 request to the VIM Controller (i.e. Nova) providing all information to create
148 The operation takes the following input parameters:
150 * name (mandatory): Assigned name for the instance to be created
151 * image (mandatory): the image to be booted in the new instance
152 * flavor (mandatory): the flavor of the requested server instance
153 * networks: the list of network uuids of the requested server instance
154 * provider-id: identifier of the provider where the instance shall be created
155 * reservation-id: identifier of a resource reservation the *create-instance*
157 The Euphrates implementation of Promise has the following limitations:
159 * All create server instance requests shall pass through the Promise
160 shim-layer such that Promise can keep track of all allocation requests. This
161 is necessary as in the current release the sychronization between the VIM
162 Controller and Promise on the available capacity is not yet implemented.
163 * *Create-allocation* requests are limited to "simple" allocations, i.e., the
164 current workflow only supports the Nova compute service and
165 *create-allocation* requests are limited to creating one server instance at a
167 * Prioritization of reservations and allocations is yet not implemented.
168 Future version may allow certain policy-based conflict resolution where,
169 e.g., new allocation request with high priority can "forcefully" terminate
170 lower priority allocations.
176 This operation request to destroy an existing server instance and release it
179 The operation takes the following input parameter:
181 * instance-id: identifier of the server instance to be destroyed
185 The capacity management feature allows the Consumer or Administrator to do
186 capacity planning, i.e. the capacity available to the reservation management
187 can differ from the actual capacity in the registered provider(s). This feature
188 can, e.g., be used to limit the available capacity for a given time window due
189 to a planned downtime of some of the resources, or increase the capacity
190 available to the reservation system in case of a planned upgrade of the
193 *increase/decrease-capacity*
194 """"""""""""""""""""""""""""
196 This operations allows to increase/decrease the total capacity that is made
197 available to the Promise reservation service between a specified window in
198 time. It does NOT increase the actual capacity of a given resource provider,
199 but is used for capacity management inside Promise.
201 This feature can be used in different ways, like
203 * Limit the capacity available to the reservation system to a value below 100%
204 of the available capacity in the VIM, e.g., in order to leave "buffer" in the
205 actual NFVI to be used outside the Promise reservation service.
207 * Inform the reservation system that, from a given time in the future,
208 additional resources can be reserved, e.g., due to a planned upgrade of the
209 available capacity of the provider.
211 * Similarily, the "decrease-capacity" can be used to reduce the consumable
212 resources in a given time window, e.g., to prepare for a planned downtime of
213 some of the resources.
215 * Expose multiple reservation service instances to different consumers sharing
216 the same resource provider.
218 The operation takes the following input parameters:
220 * start: start time for the increased/decreased capacity
221 * end: end time for the increased/decreased capacity
222 * capacity.cores: Increased/decreased amount of cores
223 * capacity.ram: Increased/decreased amount of RAM
224 * capacity.instances: Increased/decreased amount of instances
226 Note, increase/decreasing the capacity in Promise is completely transparent to
227 the VIM. As such, when increasing the virtual capacity in Promise (e.g. for a
228 planned upgrade of the capacity), it is in the responsibility of the
229 Consumer/Administrator to ensure sufficient resources in the VIM are available
230 at the appropriate time, in order to prevent allocations against reservations
231 to fail due to a lack of resources. Therefore, this operations should only be
238 This operation is used to query the available capacity information of the
239 specified resource collection. A filter attribute can be specified to narrow
240 down the query results.
242 The current implementation supports the following filter criteria:
244 * time window: returns reservations matching the specified window
246 * window scope: if set to 'exclusive', only reservations with start AND end time
247 within the time window are returned. Otherwise, all reservation starting OR
248 ending in the time windows are returned.
250 * metric: query for one of the following capacity metrics:
252 * 'total': resource pools
253 * 'reserved': reserved resources
254 * 'usage': resource allocations
255 * 'available': remaining capacity, i.e. neither reserved nor allocated
259 (Multi-)provider management
260 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
262 This API towards OpenStack allows a Consumer/Administrator to add and remove
263 resource providers to Promise. Note, Promise supports a multi-provider
264 configuration, however, for Euphrates, multi-provider support is not yet
270 This operation is used to register a new resource provider into the Promise
273 Note, for Euphrates, the add-provider operation should only be used to
274 register one provider with the Promise shim-layer. Further note that currently
275 only OpenStack is supported as a provider.
277 The operation takes the following input parameters:
279 * provider-type = 'openstack': select a specific resource provider
281 * endpoint : target URL endpoint for the resource provider.
282 * username : name of the user
283 * password : user password
284 * user-domain-name : domain name of the user
285 * project.name : name of the OpenStack project
286 * project.domain-name : domain name of the OpenStack project
288 .. [#f1] Promise requirement document,
289 http://artifacts.opnfv.org/promise/docs/development_requirements/index.html
291 .. [#f2] YangForge framework, http://github.com/opnfv/yangforge