docs/requirements/07-schemas.rst

   1 ANNEX A: PROMISE YANG SCHEMA BASED ON YANGFORGE
   2 ===============================================
   3
   4 .. code::
   5
   6   module opnfv-promise {
   7   namespace "urn:opnfv:promise";
   8   prefix promise;
   9
  10   import complex-types { prefix ct; }
  11   import iana-crypt-hash { prefix ianach; }
  12   import ietf-inet-types { prefix inet; }
  13   import ietf-yang-types { prefix yang; }
  14   import opnfv-promise-vim { prefix vim; }
  15
  16   feature multi-provider {
  17     description "";
  18   }
  19
  20   description
  21     "OPNFV Promise Resource Reservation/Allocation controller module";
  22
  23   revision 2015-04-16 {
  24     description "Initial revision.";
  25   }
  26
  27   revision 2015-08-06 {
  28     description "Updated to incorporate YangForge framework";
  29   }
  30
  31   grouping resource-capacity {
  32     container capacity {
  33       container quota { description 'Conceptual container that should be extended'; }
  34       container usage { description 'Conceptual container that should be extended';
  35                         config false; }
  36       container reserved { description 'Conceptual container that should be extended';
  37                            config false; }
  38       container available { description 'Conceptual container that should be extended';
  39                             config false; }
  40     }
  41   }
  42
  43   grouping compute-capacity {
  44     leaf cores { type number; }
  45     leaf ram { type number; }
  46     leaf instances { type number; }
  47   }
  48
  49   grouping networking-capacity {
  50     leaf network { type number; }
  51     leaf port { type number; }
  52     leaf router { type number; }
  53     leaf subnet { type number; }
  54     leaf address { type number; }
  55   }
  56
  57   ct:complex-type ResourceReservation {
  58     ct:extends vim:ResourceElement;
  59
  60     description
  61       "Contains the capacities of various resource services being reserved
  62        along with any resource elements needed to be available at
  63        the time of allocation(s).";
  64
  65     reference "OPNFV-PROMISE, Section 3.4.1";
  66
  67     leaf start { type yang:date-and-time; }
  68     leaf end   { type yang:date-and-time; }
  69     leaf expiry {
  70       description "Duration in seconds from start when unallocated reserved resources
  71                    will be released back into the pool";
  72       type number; units "seconds";
  73     }
  74     leaf zone { type instance-identifier { ct:instance-type vim:AvailabilityZone; } }
  75     container capacity {
  76       uses vim:compute-capacity;
  77       uses vim:networking-capcity;
  78       uses vim:storage-capacity;
  79     }
  80     leaf-list resources {
  81       description
  82         "Reference to a collection of existing resource elements required by
  83          this reservation. It can contain any instance derived from
  84          ResourceElement, such as ServerInstances or even other
  85          ResourceReservations. If the ResourceReservation request is
  86          accepted, the ResourceElement(s) listed here will be placed
  87          into 'protected' mode as to prevent accidental delete.";
  88       type instance-identifier {
  89         ct:instance-type vim:ResourceElement;
  90       }
  91       // following 'must' statement applies to each element
  92       must "boolean(/provider/elements/*[@id=id])" {
  93         error-message "One or more of the ResourceElement(s) does not exist in
  94                        the provider to be reserved";
  95       }
  96     }
  97
  98     leaf provider {
  99       if-feature multi-provider;
 100       config false;
 101
 102       description
 103         "Reference to a specified existing provider from which this reservation
 104          will be drawn if used in the context of multi-provider
 105          environment.";
 106       type instance-identifier {
 107         ct:instance-type vim:ResourceProvider;
 108         require-instance true;
 109       }
 110     }
 111
 112     container remaining {
 113       config false;
 114       description
 115         "Provides visibility into total remaining capacity for this
 116          reservation based on allocations that took effect utilizing
 117          this reservation ID as a reference.";
 118
 119       uses vim:compute-capacity;
 120       uses vim:networking-capcity;
 121       uses vim:storage-capacity;
 122     }
 123
 124     leaf-list allocations {
 125       config false;
 126       description
 127         "Reference to a collection of consumed allocations referencing
 128          this reservation.";
 129       type instance-identifier {
 130         ct:instance-type ResourceAllocation;
 131       }
 132     }
 133   }
 134
 135   ct:complex-type ResourceAllocation {
 136     ct:extends vim:ResourceElement;
 137
 138     description
 139        "Contains a list of resources to be allocated with optional reference
 140        to an existing reservation.
 141
 142        If reservation is specified but this request is received prior
 143        to reservation start timestamp, then it will be rejected unless
 144        'allocate-on-start' is set to true.  'allocate-on-start' allows
 145        the allocation to be auto-initiated and scheduled to run in the
 146        future.
 147
 148        The 'priority' state indicates the classification for dealing
 149        with resource starvation scenarios. Lower priority allocations
 150        will be forcefully terminated to allow for higher priority
 151        allocations to be fulfilled.
 152
 153        Allocations without reference to an existing reservation will
 154        receive the lowest priority.";
 155
 156     reference "OPNFV-PROMISE, Section 3.4.3";
 157
 158     leaf reservation {
 159       description "Reference to an existing reservation identifier";
 160
 161       type instance-identifier {
 162         ct:instance-type ResourceReservation;
 163         require-instance true;
 164       }
 165     }
 166
 167     leaf allocate-on-start {
 168       description
 169        "If 'allocate-on-start' is set to true, the 'planned' allocations will
 170        take effect automatically at the reservation 'start' date/time.";
 171       type boolean; default false;
 172     }
 173
 174     ct:instance-list resources {
 175       description "Contains list of new ResourceElements that will be allocated";
 176       ct:instance-type vim:ResourceElement;
 177     }
 178
 179     leaf priority {
 180       description
 181         "Reflects current priority level of the allocation according to classification rules";
 182       type number;
 183       config false;
 184     }
 185   }
 186
 187   // MAIN CONTAINER
 188   container promise {
 189     ct:instance-list providers {
 190       description "Aggregate collection of all registered ResourceProvider instances";
 191       ct:instance-type vim:ResourceProvider;
 192       config false;
 193
 194      // augment compute container with capacity elements
 195      augment "compute" {
 196        uses resource-capacity {
 197          augment "capacity/quota" { uses compute-capacity; }
 198          augment "capacity/usage" { uses compute-capacity; }
 199          augment "capacity/reserved" { uses compute-capacity; }
 200          augment "capacity/available" { uses compute-capacity; }
 201        }
 202      }
 203
 204      // augment networking container with capacity elements
 205      augment "networking" {
 206        uses resource-capacity {
 207          if-feature has-networking-capacity;
 208          augment "capacity/quota" { uses networking-capacity; }
 209          augment "capacity/usage" { uses networking-capacity; }
 210          augment "capacity/reserved" { uses networking-capacity; }
 211          augment "capacity/available" { uses networking-capacity; }
 212        }
 213      }
 214
 215      // track references to reservations for this resource provider
 216      leaf-list reservations {
 217        type instance-identifier {
 218          ct:instance-type ResourceReservation;
 219        }
 220      }
 221     }
 222
 223     ct:instance-list reservations {
 224       description "Aggregate collection of all registered ResourceReservation instances";
 225       ct:instance-type ResourceReservation;
 226     }
 227
 228     ct:instance-list allocations {
 229       description "Aggregate collection of all active ResourceAllocation instances";
 230       ct:instance-type ResourceAllocation;
 231     }
 232   }
 233
 234   rpc add-provider {
 235     description "This operation allows you to register a new ResourceProvider
 236                  into promise management service";
 237     input {
 238       leaf provider {
 239         description "Select a specific resource provider";
 240         mandatory true;
 241         type enumeration {
 242           enum openstack;
 243           enum hp;
 244           enum rackspace;
 245           enum amazon {
 246             status planned;
 247           }
 248           enum joyent {
 249             status planned;
 250           }
 251           enum azure {
 252             status planned;
 253           }
 254         }
 255       }
 256       leaf username {
 257         type string;
 258         mandatory true;
 259       }
 260       leaf password {
 261         type ianach:crypt-hash;
 262         mandatory true;
 263       }
 264       leaf endpoint {
 265         type inet:uri;
 266         description "The target URL endpoint for the resource provider";
 267         mandatory true;
 268       }
 269       leaf region {
 270         type string;
 271         description "Optional specified regsion for the provider";
 272       }
 273     }
 274     output {
 275       leaf id {
 276         description "Unique identifier for the newly added provider found in /promise/providers";
 277         type instance-identifier {
 278           ct:instance-type ResourceProvider;
 279         }
 280       }
 281       leaf result {
 282         type enumeration {
 283           enum success;
 284           enum error;
 285         }
 286       }
 287     }
 288   }
 289   rpc remove-provider;
 290   rpc list-providers;
 291
 292   rpc check-capacity;
 293
 294   rpc list-reservations;
 295   rpc create-reservation;
 296   rpc update-reservation;
 297   rpc cancel-reservation;
 298
 299   rpc list-allocations;
 300   rpc create-allocation;
 301
 302   notification reservation-event;
 303   notification capacity-event;
 304   notification allocation-event;
 305   }
 306