docs/requirements/schemas.rst

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