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