b6063823f617e3892c15cd496331e207b4ccb27a
[promise.git] / source / schema / opnfv-promise.yang
1 module opnfv-promise {
2   namespace "urn:opnfv:promise";
3   prefix promise;
4
5   import complex-types { prefix ct; }
6   import ietf-yang-types { prefix yang; }
7   import ietf-inet-types { prefix inet; }
8   import access-control-models { prefix acm; }
9   import nfv-infrastructure { prefix nfvi; }
10
11   description
12     "OPNFV Promise Resource Reservation/Allocation controller module";
13
14   revision 2015-10-05 {
15     description "Complete coverage of reservation related intents";
16   }
17   
18   revision 2015-08-06 {
19     description "Updated to incorporate YangForge framework";
20   }
21
22   revision 2015-04-16 {
23     description "Initial revision.";
24   }
25
26   feature reservation-service {
27     description "When enabled, provides resource reservation service";
28   }
29
30   feature multi-provider {
31     description "When enabled, provides resource management across multiple providers";
32   }
33
34   typedef reference-identifier {
35     description "defines valid formats for external reference id";
36     type union {
37       type yang:uuid;
38       type inet:uri;
39       type uint32;
40     }
41   }
42   
43   grouping resource-utilization {
44     container capacity {
45       container total     { description 'Conceptual container that should be extended'; }
46       container reserved  { description 'Conceptual container that should be extended'; config false; }
47       container usage     { description 'Conceptual container that should be extended'; config false; }
48       container available { description 'Conceptual container that should be extended'; config false; }
49     }
50   }
51
52   grouping temporal-resource-collection {
53     description
54       "Information model capturing resource-collection with start/end time window";
55     
56     leaf start { type yang:date-and-time; }
57     leaf end   { type yang:date-and-time; }
58     
59     uses nfvi:resource-collection;
60   }
61   
62   grouping resource-usage-request {
63     description
64       "Information model capturing available parameters to make a resource
65        usage request.";
66     reference "OPNFV-PROMISE, Section 3.4.1";
67
68     uses temporal-resource-collection {
69       refine elements {
70         description
71           "Reference to a list of 'pre-existing' resource elements that are
72          required for fulfillment of the resource-usage-request.
73
74          It can contain any instance derived from ResourceElement,
75          such as ServerInstances or even other
76          ResourceReservations. If the resource-usage-request is
77          accepted, the ResourceElement(s) listed here will be placed
78          into 'protected' mode as to prevent accidental removal.
79
80          If any of these resource elements become 'unavailable' due to
81          environmental or administrative activity, a notification will
82          be issued informing of the issue.";
83       }
84     }
85     
86     leaf zone {
87       description "Optional identifier to an Availability Zone";
88       type instance-identifier { ct:instance-type nfvi:AvailabilityZone; }
89     }
90   }
91
92   grouping query-start-end-window {
93     container window {
94       description "Matches entries that are within the specified start/end time window";
95       leaf start { type yang:date-and-time; }
96       leaf end   { type yang:date-and-time; }
97       leaf scope {
98         type enumeration {
99           enum "exclusive" {
100             description "Matches entries that start AND end within the window";
101           }
102           enum "inclusive" {
103             description "Matches entries that start OR end within the window";
104           }
105         }
106         default "inclusive";
107       }
108     }
109   }
110
111   grouping query-resource-collection {
112     uses query-start-end-window {
113       description "Match for ResourceCollection(s) that are within the specified start/end time window";
114     }
115     leaf-list without {
116       description "Excludes specified collection identifiers from the result";
117       type instance-identifier { ct:instance-type ResourceCollection; }
118     }
119     leaf show-utilization { type boolean; default true; }
120     container elements {
121       leaf-list some {
122         description "Query for ResourceCollection(s) that contain some or more of these element(s)";
123         type instance-identifier { ct:instance-type nfvi:ResourceElement; }
124       }
125       leaf-list every {
126         description "Query for ResourceCollection(s) that contain all of these element(s)";
127         type instance-identifier { ct:instance-type nfvi:ResourceElement; }
128       }
129     }
130   }
131
132   grouping common-intent-output {
133     leaf result {
134       type enumeration {
135         enum "ok";
136         enum "conflict";
137         enum "error";
138       }
139     }
140     leaf message { type string; }
141   }
142   
143   grouping utilization-output {
144     list utilization {
145       key 'timestamp';
146       leaf timestamp { type yang:date-and-time; }
147       leaf count { type int16; }
148       container capacity { uses nfvi:resource-capacity; }
149     }
150   }
151
152   ct:complex-type ResourceCollection {
153     ct:extends nfvi:ResourceContainer;
154     ct:abstract true;
155
156     description
157       "Describes an abstract ResourceCollection data model, which represents
158        a grouping of capacity and elements available during a given
159        window in time which must be extended by other resource
160        collection related models";
161
162     leaf start { type yang:date-and-time; }
163     leaf end   { type yang:date-and-time; }
164     
165     leaf active {
166       config false;
167       description
168         "Provides current state of this record whether it is enabled and within
169          specified start/end time";
170       type boolean;
171     }
172   }
173
174   ct:complex-type ResourcePool {
175     ct:extends ResourceCollection;
176
177     description
178       "Describes an instance of an active ResourcePool record, which
179        represents total available capacity and elements from a given
180        source.";
181
182     leaf source {
183       type instance-identifier {
184         ct:instance-type nfvi:ResourceContainer;
185         require-instance true;
186       }
187       mandatory true;
188     }
189
190     refine elements {
191       // following 'must' statement applies to each element
192       // NOTE: just a non-working example for now...
193       must "boolean(/source/elements/*[@id=id])" {
194         error-message "One or more of the ResourceElement(s) does not exist in the provider to be reserved";
195       }
196     }
197   }
198
199   ct:complex-type ResourceReservation {
200     ct:extends ResourceCollection;
201     
202     description
203       "Describes an instance of an accepted resource reservation request,
204        created usually as a result of 'create-reservation' request.
205
206        A ResourceReservation is a derived instance of a generic
207        ResourceCollection which has additional parameters to map the
208        pool(s) that were referenced to accept this reservation as well
209        as to track allocations made referencing this reservation.
210
211        Contains the capacities of various resource attributes being
212        reserved along with any resource elements that are needed to be
213        available at the time of allocation(s).";
214     
215     reference "OPNFV-PROMISE, Section 3.4.1";
216
217     leaf created-on  { type yang:date-and-time; config false; }
218     leaf modified-on { type yang:date-and-time; config false; }
219
220     leaf-list pools {
221       config false;
222       description
223         "Provides list of one or more pools that were referenced for providing
224          the requested resources for this reservation.  This is an
225          important parameter for informing how/where allocation
226          requests can be issued using this reservation since it is
227          likely that the total reserved resource capacity/elements are
228          made availble from multiple sources.";
229       type instance-identifier {
230         ct:instance-type ResourcePool;
231         require-instance true;
232       }
233     }
234     
235     container remaining {
236       config false;
237       description
238         "Provides visibility into total remaining capacity for this
239          reservation based on allocations that took effect utilizing
240          this reservation ID as a reference.";
241
242       uses nfvi:resource-capacity;
243     }
244     
245     leaf-list allocations {
246       config false;
247       description
248         "Reference to a collection of consumed allocations referencing
249          this reservation.";
250       type instance-identifier {
251         ct:instance-type ResourceAllocation;
252         require-instance true;
253       }
254     }
255   }
256
257   ct:complex-type ResourceAllocation {
258     ct:extends ResourceCollection;
259
260     description
261       "A ResourceAllocation record denotes consumption of resources from a
262        referenced ResourcePool.
263
264        It does not reflect an accepted request but is created to
265        represent the actual state about the ResourcePool. It is
266        created once the allocation(s) have successfully taken effect
267        on the 'source' of the ResourcePool.
268        
269        The 'priority' state indicates the classification for dealing
270        with resource starvation scenarios. Lower priority allocations
271        will be forcefully terminated to allow for higher priority
272        allocations to be fulfilled.
273
274        Allocations without reference to an existing reservation will
275        receive the lowest priority.";
276     
277     reference "OPNFV-PROMISE, Section 3.4.3";
278
279     leaf reservation {
280       description "Reference to an existing reservation identifier (optional)";
281       
282       type instance-identifier {
283         ct:instance-type ResourceReservation;
284         require-instance true;
285       }
286     }
287
288     leaf pool {
289       description "Reference to an existing resource pool from which allocation is drawn";
290       
291       type instance-identifier {
292         ct:instance-type ResourcePool;
293         require-instance true;
294       }
295     }
296
297     container instance-ref {
298       config false;
299       description
300         "Reference to actual instance identifier of the provider/server for this allocation";
301       leaf provider {
302         type instance-identifier { ct:instance-type ResourceProvider; }
303       }
304       leaf server { type yang:uuid; }
305     }
306
307     leaf priority {
308       config false;
309       description
310         "Reflects current priority level of the allocation according to classification rules";
311       type enumeration {
312         enum "high"   { value 1; }
313         enum "normal" { value 2; }
314         enum "low"    { value 3; }
315       }
316       default "normal";
317     }
318   }
319
320   ct:complex-type ResourceFlavor {
321     description "currently NOT an extension of ResourceElement.";
322     key "id";
323     leaf id    { type string; }
324     leaf name  { type string; }
325     leaf disk  { type uint32; units 'GB'; default 0; }
326     leaf ram   { type uint32; units 'MB'; default 0; }
327     leaf vcpus { type uint16; default 0; }
328   }
329   
330   ct:complex-type ResourceProvider {
331     ct:extends nfvi:ResourceContainer;
332
333     key "name";
334     leaf token { type string; mandatory true; }
335     
336     container services { // read-only
337       config false;
338       container compute {
339         leaf endpoint { type inet:uri; }
340         ct:instance-list flavors { ct:instance-type ResourceFlavor; }
341       }
342     }
343     
344     leaf-list pools {
345       config false;
346       description
347         "Provides list of one or more pools that are referencing this provider.";
348       
349       type instance-identifier {
350         ct:instance-type ResourcePool;
351         require-instance true;
352       }
353     }
354   }
355   
356   // MAIN CONTAINER
357   container promise {
358     
359     uses resource-utilization {
360       description "Describes current state info about capacity utilization info";
361       
362       augment "capacity/total"     { uses nfvi:resource-capacity; }
363       augment "capacity/reserved"  { uses nfvi:resource-capacity; }
364       augment "capacity/usage"     { uses nfvi:resource-capacity; }
365       augment "capacity/available" { uses nfvi:resource-capacity; }
366     }
367
368     ct:instance-list providers {
369       if-feature multi-provider;
370       description "Aggregate collection of all registered ResourceProvider instances for Promise resource management service";
371       ct:instance-type ResourceProvider;
372     }
373
374     ct:instance-list pools {
375       if-feature reservation-service;
376       description "Aggregate collection of all ResourcePool instances";
377       ct:instance-type ResourcePool;
378     }
379     
380     ct:instance-list reservations {
381       if-feature reservation-service;
382       description "Aggregate collection of all ResourceReservation instances";
383       ct:instance-type ResourceReservation;
384     }
385
386     ct:instance-list allocations {
387       description "Aggregate collection of all ResourceAllocation instances";
388       ct:instance-type ResourceAllocation;
389     }
390
391     container policy {
392       container reservation {
393         leaf max-future-start-range {
394           description
395             "Enforce reservation request 'start' time is within allowed range from now";
396           type uint16 { range 0..365; }
397           units "days";
398         }
399         leaf max-future-end-range {
400           description
401             "Enforce reservation request 'end' time is within allowed range from now";
402           type uint16 { range 0..365; }
403           units "days";
404         }
405         leaf max-duration {
406           description
407             "Enforce reservation duration (end-start) does not exceed specified threshold";
408           type uint16;
409           units "hours";
410           default 8760; // for now cap it at max one year as default
411         }
412         leaf expiry {
413           description
414             "Duration in minutes from start when unallocated reserved resources
415              will be released back into the pool";
416           type uint32;
417           units "minutes";
418         }
419       }
420     }
421   }
422
423   //-------------------
424   // INTENT INTERFACE
425   //-------------------
426
427   // RESERVATION INTENTS
428   rpc create-reservation {
429     if-feature reservation-service;
430     description "Make a request to the reservation system to reserve resources";
431     input {
432       uses resource-usage-request;
433     }
434     output {
435       uses common-intent-output;
436       leaf reservation-id {
437         type instance-identifier { ct:instance-type ResourceReservation; }
438       }
439     }
440   }
441   
442   rpc update-reservation {
443     description "Update reservation details for an existing reservation";
444     input {
445       leaf reservation-id {
446         type instance-identifier {
447           ct:instance-type ResourceReservation;
448           require-instance true;
449         }
450         mandatory true;
451       }
452       uses resource-usage-request;
453     }
454     output {
455       uses common-intent-output;
456     }
457   }
458   
459   rpc cancel-reservation {
460     description "Cancel the reservation and be a good steward";
461     input {
462       leaf reservation-id {
463         type instance-identifier { ct:instance-type ResourceReservation; }
464         mandatory true;
465       }
466     }
467     output {
468       uses common-intent-output;
469     }
470   }
471
472   rpc query-reservation {
473     if-feature reservation-service;
474     description "Query the reservation system to return matching reservation(s)";
475     input {
476       leaf zone { type instance-identifier { ct:instance-type nfvi:AvailabilityZone; } }
477       uses query-resource-collection;
478     }
479     output {
480       leaf-list reservations { type instance-identifier { ct:instance-type ResourceReservation; } }
481       uses utilization-output;
482     }
483   }
484   
485   // CAPACITY INTENTS
486   rpc increase-capacity {
487     description "Increase total capacity for the reservation system between a window in time";
488     input {
489       uses temporal-resource-collection;
490       leaf source {
491         type instance-identifier {
492           ct:instance-type nfvi:ResourceContainer;
493         }
494       }
495     }
496     output {
497       uses common-intent-output;
498       leaf pool-id {
499         type instance-identifier { ct:instance-type ResourcePool; }
500       }
501     }
502   }
503
504   rpc decrease-capacity {
505     description "Decrease total capacity for the reservation system between a window in time";
506     input {
507       uses temporal-resource-collection;
508       leaf source {
509         type instance-identifier {
510           ct:instance-type nfvi:ResourceContainer;
511         }
512       }
513     }
514     output {
515       uses common-intent-output;
516       leaf pool-id {
517         type instance-identifier { ct:instance-type ResourcePool; }
518       }
519     }
520   }
521
522   rpc query-capacity {
523     description "Check available capacity information about a specified resource collection";
524     input {
525       leaf capacity {
526         type enumeration {
527           enum 'total';
528           enum 'reserved';
529           enum 'usage';
530           enum 'available';
531         }
532         default 'available';
533       }
534       leaf zone { type instance-identifier { ct:instance-type nfvi:AvailabilityZone; } }
535       uses query-resource-collection;
536       // TBD: additional parameters for query-capacity
537     }
538     output {
539       leaf-list collections { type instance-identifier { ct:instance-type ResourceCollection; } }
540       uses utilization-output;
541     }
542   }
543
544   // ALLOCATION INTENTS (should go into VIM module in the future)
545   rpc create-instance {
546     description "Create an instance of specified resource(s) utilizing capacity from the pool";
547     input {
548       leaf provider-id {
549         if-feature multi-provider;
550         type instance-identifier { ct:instance-type ResourceProvider; require-instance true; }
551       }
552       leaf name   { type string; mandatory true; }
553       leaf image  {
554         type reference-identifier;
555         mandatory true;
556       }
557       leaf flavor {
558         type reference-identifier;
559         mandatory true;
560       }
561       leaf-list networks {
562         type reference-identifier;
563         description "optional, will assign default network if not provided";
564       }
565       
566       // TODO: consider supporting a template-id (such as HEAT) for more complex instantiation
567       
568       leaf reservation-id {
569         type instance-identifier { ct:instance-type ResourceReservation; require-instance true; }
570       }
571     }
572     output {
573       uses common-intent-output;
574       leaf instance-id {
575         type instance-identifier { ct:instance-type ResourceAllocation; }
576       }
577     }
578   }
579
580   rpc destroy-instance {
581     description "Destroy an instance of resource utilization and release it back to the pool";
582     input {
583       leaf instance-id {
584         type instance-identifier { ct:instance-type ResourceAllocation; require-instance true; }
585       }
586     }
587     output {
588       uses common-intent-output;
589     }
590   }
591
592   // PROVIDER INTENTS (should go into VIM module in the future)
593   rpc add-provider {
594     description "Register a new resource provider into reservation system";
595     input {
596       leaf provider-type {
597         description "Select a specific resource provider type";
598         mandatory true;
599         type enumeration {
600           enum openstack;
601           enum hp;
602           enum rackspace;
603           enum amazon {
604             status planned;
605           }
606           enum joyent {
607             status planned;
608           }
609           enum azure {
610             status planned;
611           }
612         }
613         default openstack;
614       }
615       uses acm:access-credentials {
616         refine strategy {
617           default keystone;
618         }
619         refine endpoint {
620           default "http://localhost:5000/v2.0";
621         }
622       }
623       container tenant {
624         leaf id { type string; }
625         leaf name { type string; }
626       }
627     }
628     output {
629       uses common-intent-output;
630       leaf provider-id {
631         type instance-identifier { ct:instance-type ResourceProvider; }
632       }
633     }
634   }
635   
636   // TODO...
637   notification reservation-event;
638   notification capacity-event;
639   notification allocation-event;
640 }