diff options
| -rw-r--r-- | docs/requirements/revision.rst | 3 | ||||
| -rw-r--r-- | docs/requirements/schemas.rst | 650 |
2 files changed, 498 insertions, 155 deletions
diff --git a/docs/requirements/revision.rst b/docs/requirements/revision.rst index fcb8c7d..0bc4b32 100644 --- a/docs/requirements/revision.rst +++ b/docs/requirements/revision.rst @@ -22,3 +22,6 @@ ANNEX C: Document revision | | - Split shim-layer architecture and | | | integrated architecture sections | +---------+-----------------------------------------+ +| 1.0.5 | JIRA: PROMISE-61 | +| | - Updated Promise Yang Schema | ++---------+-----------------------------------------+ diff --git a/docs/requirements/schemas.rst b/docs/requirements/schemas.rst index e42e02e..479c9a8 100644 --- a/docs/requirements/schemas.rst +++ b/docs/requirements/schemas.rst @@ -8,103 +8,230 @@ ANNEX B: Promise YANG schema based on YangForge prefix promise; import complex-types { prefix ct; } - import iana-crypt-hash { prefix ianach; } - import ietf-inet-types { prefix inet; } import ietf-yang-types { prefix yang; } - import opnfv-promise-vim { prefix vim; } - - feature multi-provider { - description ""; - } + import ietf-inet-types { prefix inet; } + import access-control-models { prefix acm; } + import nfv-infrastructure { prefix nfvi; } + import nfv-mano { prefix mano; } description "OPNFV Promise Resource Reservation/Allocation controller module"; - revision 2015-04-16 { - description "Initial revision."; + revision 2015-10-05 { + description "Complete coverage of reservation related intents"; } revision 2015-08-06 { description "Updated to incorporate YangForge framework"; } - grouping resource-capacity { + revision 2015-04-16 { + description "Initial revision."; + } + + feature reservation-service { + description "When enabled, provides resource reservation service"; + } + + feature multi-provider { + description "When enabled, provides resource management across multiple providers"; + } + + grouping resource-utilization { container capacity { - container quota { description 'Conceptual container that should be extended'; } - container usage { description 'Conceptual container that should be extended'; - config false; } - container reserved { description 'Conceptual container that should be extended'; - config false; } + container total { description 'Conceptual container that should be extended'; } + container reserved { description 'Conceptual container that should be extended'; + config false; } + container usage { description 'Conceptual container that should be extended'; + config false; } container available { description 'Conceptual container that should be extended'; config false; } } } - grouping compute-capacity { - leaf cores { type number; } - leaf ram { type number; } - leaf instances { type number; } + grouping temporal-resource-collection { + description + "Information model capturing resource-collection with start/end time window"; + + leaf start { type yang:date-and-time; } + leaf end { type yang:date-and-time; } + + uses nfvi:resource-collection; + } + + grouping resource-usage-request { + description + "Information model capturing available parameters to make a resource + usage request."; + reference "OPNFV-PROMISE, Section 3.4.1"; + + uses temporal-resource-collection { + refine elements { + description + "Reference to a list of 'pre-existing' resource elements that are + required for fulfillment of the resource-usage-request. + + It can contain any instance derived from ResourceElement, + such as ServerInstances or even other + ResourceReservations. If the resource-usage-request is + accepted, the ResourceElement(s) listed here will be placed + into 'protected' mode as to prevent accidental removal. + + If any of these resource elements become 'unavailable' due to + environmental or administrative activity, a notification will + be issued informing of the issue."; + } + } + + leaf zone { + description "Optional identifier to an Availability Zone"; + type instance-identifier { ct:instance-type nfvi:AvailabilityZone; } + } + } + + grouping query-start-end-window { + container window { + description "Matches entries that are within the specified start/end time window"; + leaf start { type yang:date-and-time; } + leaf end { type yang:date-and-time; } + leaf scope { + type enumeration { + enum "exclusive" { + description "Matches entries that start AND end within the window"; + } + enum "inclusive" { + description "Matches entries that start OR end within the window"; + } + } + default "inclusive"; + } + } } - grouping networking-capacity { - leaf network { type number; } - leaf port { type number; } - leaf router { type number; } - leaf subnet { type number; } - leaf address { type number; } + grouping query-resource-collection { + uses query-start-end-window { + description "Match for ResourceCollection(s) that are within the specified + start/end time window"; + } + leaf-list without { + description "Excludes specified collection identifiers from the result"; + type instance-identifier { ct:instance-type ResourceCollection; } + } + leaf show-utilization { type boolean; default true; } + container elements { + leaf-list some { + description "Query for ResourceCollection(s) that contain some or more of + these element(s)"; + type instance-identifier { ct:instance-type nfvi:ResourceElement; } + } + leaf-list every { + description "Query for ResourceCollection(s) that contain all of + these element(s)"; + type instance-identifier { ct:instance-type nfvi:ResourceElement; } + } + } } - ct:complex-type ResourceReservation { - ct:extends vim:ResourceElement; + grouping common-intent-output { + leaf result { + type enumeration { + enum "ok"; + enum "conflict"; + enum "error"; + } + } + leaf message { type string; } + } - description - "Contains the capacities of various resource services being reserved - along with any resource elements needed to be available at - the time of allocation(s)."; + grouping utilization-output { + list utilization { + key 'timestamp'; + leaf timestamp { type yang:date-and-time; } + leaf count { type int16; } + container capacity { uses nfvi:resource-capacity; } + } + } - reference "OPNFV-PROMISE, Section 3.4.1"; + ct:complex-type ResourceCollection { + ct:extends nfvi:ResourceContainer; + ct:abstract true; + + description + "Describes an abstract ResourceCollection data model, which represents + a grouping of capacity and elements available during a given + window in time which must be extended by other resource + collection related models"; leaf start { type yang:date-and-time; } leaf end { type yang:date-and-time; } - leaf expiry { - description "Duration in seconds from start when unallocated reserved resources - will be released back into the pool"; - type number; units "seconds"; - } - leaf zone { type instance-identifier { ct:instance-type vim:AvailabilityZone; } } - container capacity { - uses vim:compute-capacity; - uses vim:networking-capcity; - uses vim:storage-capacity; - } - leaf-list resources { + + leaf active { + config false; description - "Reference to a collection of existing resource elements required by - this reservation. It can contain any instance derived from - ResourceElement, such as ServerInstances or even other - ResourceReservations. If the ResourceReservation request is - accepted, the ResourceElement(s) listed here will be placed - into 'protected' mode as to prevent accidental delete."; + "Provides current state of this record whether it is enabled and within + specified start/end time"; + type boolean; + } + } + + ct:complex-type ResourcePool { + ct:extends ResourceCollection; + + description + "Describes an instance of an active ResourcePool record, which + represents total available capacity and elements from a given + source."; + + leaf source { type instance-identifier { - ct:instance-type vim:ResourceElement; + ct:instance-type nfvi:ResourceContainer; + require-instance true; } + mandatory true; + } + + refine elements { // following 'must' statement applies to each element - must "boolean(/provider/elements/*[@id=id])" { + // NOTE: just a non-working example for now... + must "boolean(/source/elements/*[@id=id])" { error-message "One or more of the ResourceElement(s) does not exist in the provider to be reserved"; } } + } - leaf provider { - if-feature multi-provider; - config false; + ct:complex-type ResourceReservation { + ct:extends ResourceCollection; + + description + "Describes an instance of an accepted resource reservation request, + created usually as a result of 'create-reservation' request. + + A ResourceReservation is a derived instance of a generic + ResourceCollection which has additional parameters to map the + pool(s) that were referenced to accept this reservation as well + as to track allocations made referencing this reservation. + + Contains the capacities of various resource attributes being + reserved along with any resource elements that are needed to be + available at the time of allocation(s)."; + + reference "OPNFV-PROMISE, Section 3.4.1"; + + leaf created-on { type yang:date-and-time; config false; } + leaf modified-on { type yang:date-and-time; config false; } + leaf-list pools { + config false; description - "Reference to a specified existing provider from which this reservation - will be drawn if used in the context of multi-provider - environment."; + "Provides list of one or more pools that were referenced for providing + the requested resources for this reservation. This is an + important parameter for informing how/where allocation + requests can be issued using this reservation since it is + likely that the total reserved resource capacity/elements are + made availble from multiple sources."; type instance-identifier { - ct:instance-type vim:ResourceProvider; + ct:instance-type ResourcePool; require-instance true; } } @@ -116,9 +243,7 @@ ANNEX B: Promise YANG schema based on YangForge reservation based on allocations that took effect utilizing this reservation ID as a reference."; - uses vim:compute-capacity; - uses vim:networking-capcity; - uses vim:storage-capacity; + uses nfvi:resource-capacity; } leaf-list allocations { @@ -128,22 +253,22 @@ ANNEX B: Promise YANG schema based on YangForge this reservation."; type instance-identifier { ct:instance-type ResourceAllocation; + require-instance true; } } } ct:complex-type ResourceAllocation { - ct:extends vim:ResourceElement; + ct:extends ResourceCollection; description - "Contains a list of resources to be allocated with optional reference - to an existing reservation. + "A ResourceAllocation record denotes consumption of resources from a + referenced ResourcePool. - If reservation is specified but this request is received prior - to reservation start timestamp, then it will be rejected unless - 'allocate-on-start' is set to true. 'allocate-on-start' allows - the allocation to be auto-initiated and scheduled to run in the - future. + It does not reflect an accepted request but is created to + represent the actual state about the ResourcePool. It is + created once the allocation(s) have successfully taken effect + on the 'source' of the ResourcePool. The 'priority' state indicates the classification for dealing with resource starvation scenarios. Lower priority allocations @@ -156,7 +281,7 @@ ANNEX B: Promise YANG schema based on YangForge reference "OPNFV-PROMISE, Section 3.4.3"; leaf reservation { - description "Reference to an existing reservation identifier"; + description "Reference to an existing reservation identifier (optional)"; type instance-identifier { ct:instance-type ResourceReservation; @@ -164,79 +289,320 @@ ANNEX B: Promise YANG schema based on YangForge } } - leaf allocate-on-start { - description - "If 'allocate-on-start' is set to true, the 'planned' allocations will - take effect automatically at the reservation 'start' date/time."; - type boolean; default false; + leaf pool { + description "Reference to an existing resource pool from which allocation is drawn"; + + type instance-identifier { + ct:instance-type ResourcePool; + require-instance true; + } } - ct:instance-list resources { - description "Contains list of new ResourceElements that will be allocated"; - ct:instance-type vim:ResourceElement; + container instance-ref { + config false; + description + "Reference to actual instance identifier of the provider/server + for this allocation"; + leaf provider { + type instance-identifier { ct:instance-type ResourceProvider; } + } + leaf server { type yang:uuid; } } leaf priority { + config false; description - "Reflects current priority level of the allocation according to classification rules"; - type number; + "Reflects current priority level of the allocation according to + classification rules"; + type enumeration { + enum "high" { value 1; } + enum "normal" { value 2; } + enum "low" { value 3; } + } + default "normal"; + } + } + + ct:complex-type ResourceProvider { + ct:extends nfvi:ResourceContainer; + + key "name"; + leaf token { type string; mandatory true; } + + container services { // read-only + config false; + container compute { + leaf endpoint { type inet:uri; } + ct:instance-list flavors { ct:instance-type nfvi:ComputeFlavor; } + } + } + + leaf-list pools { config false; + description + "Provides list of one or more pools that are referencing this provider."; + + type instance-identifier { + ct:instance-type ResourcePool; + require-instance true; + } } } // MAIN CONTAINER container promise { + + uses resource-utilization { + description "Describes current state info about capacity utilization info"; + + augment "capacity/total" { uses nfvi:resource-capacity; } + augment "capacity/reserved" { uses nfvi:resource-capacity; } + augment "capacity/usage" { uses nfvi:resource-capacity; } + augment "capacity/available" { uses nfvi:resource-capacity; } + } + ct:instance-list providers { - description "Aggregate collection of all registered ResourceProvider instances"; - ct:instance-type vim:ResourceProvider; - config false; + if-feature multi-provider; + description "Aggregate collection of all registered ResourceProvider instances + for Promise resource management service"; + ct:instance-type ResourceProvider; + } - // augment compute container with capacity elements - augment "compute" { - uses resource-capacity { - augment "capacity/quota" { uses compute-capacity; } - augment "capacity/usage" { uses compute-capacity; } - augment "capacity/reserved" { uses compute-capacity; } - augment "capacity/available" { uses compute-capacity; } - } - } - - // augment networking container with capacity elements - augment "networking" { - uses resource-capacity { - if-feature has-networking-capacity; - augment "capacity/quota" { uses networking-capacity; } - augment "capacity/usage" { uses networking-capacity; } - augment "capacity/reserved" { uses networking-capacity; } - augment "capacity/available" { uses networking-capacity; } - } - } - - // track references to reservations for this resource provider - leaf-list reservations { - type instance-identifier { - ct:instance-type ResourceReservation; - } - } + ct:instance-list pools { + if-feature reservation-service; + description "Aggregate collection of all ResourcePool instances"; + ct:instance-type ResourcePool; } ct:instance-list reservations { - description "Aggregate collection of all registered ResourceReservation instances"; + if-feature reservation-service; + description "Aggregate collection of all ResourceReservation instances"; ct:instance-type ResourceReservation; } ct:instance-list allocations { - description "Aggregate collection of all active ResourceAllocation instances"; + description "Aggregate collection of all ResourceAllocation instances"; ct:instance-type ResourceAllocation; } + + container policy { + container reservation { + leaf max-future-start-range { + description + "Enforce reservation request 'start' time is within allowed range from now"; + type uint16 { range 0..365; } + units "days"; + } + leaf max-future-end-range { + description + "Enforce reservation request 'end' time is within allowed range from now"; + type uint16 { range 0..365; } + units "days"; + } + leaf max-duration { + description + "Enforce reservation duration (end-start) does not exceed specified threshold"; + type uint16; + units "hours"; + default 8760; // for now cap it at max one year as default + } + leaf expiry { + description + "Duration in minutes from start when unallocated reserved resources + will be released back into the pool"; + type uint32; + units "minutes"; + } + } + } + } + + //------------------- + // INTENT INTERFACE + //------------------- + + // RESERVATION INTENTS + rpc create-reservation { + if-feature reservation-service; + description "Make a request to the reservation system to reserve resources"; + input { + uses resource-usage-request; + } + output { + uses common-intent-output; + leaf reservation-id { + type instance-identifier { ct:instance-type ResourceReservation; } + } + } + } + + rpc update-reservation { + description "Update reservation details for an existing reservation"; + input { + leaf reservation-id { + type instance-identifier { + ct:instance-type ResourceReservation; + require-instance true; + } + mandatory true; + } + uses resource-usage-request; + } + output { + uses common-intent-output; + } + } + + rpc cancel-reservation { + description "Cancel the reservation and be a good steward"; + input { + leaf reservation-id { + type instance-identifier { ct:instance-type ResourceReservation; } + mandatory true; + } + } + output { + uses common-intent-output; + } + } + + rpc query-reservation { + if-feature reservation-service; + description "Query the reservation system to return matching reservation(s)"; + input { + leaf zone { type instance-identifier { ct:instance-type nfvi:AvailabilityZone; } } + uses query-resource-collection; + } + output { + leaf-list reservations { type instance-identifier + { ct:instance-type ResourceReservation; } } + uses utilization-output; + } + } + + // CAPACITY INTENTS + rpc increase-capacity { + description "Increase total capacity for the reservation system + between a window in time"; + input { + uses temporal-resource-collection; + leaf source { + type instance-identifier { + ct:instance-type nfvi:ResourceContainer; + } + } + } + output { + uses common-intent-output; + leaf pool-id { + type instance-identifier { ct:instance-type ResourcePool; } + } + } + } + + rpc decrease-capacity { + description "Decrease total capacity for the reservation system + between a window in time"; + input { + uses temporal-resource-collection; + leaf source { + type instance-identifier { + ct:instance-type nfvi:ResourceContainer; + } + } + } + output { + uses common-intent-output; + leaf pool-id { + type instance-identifier { ct:instance-type ResourcePool; } + } + } + } + + rpc query-capacity { + description "Check available capacity information about a specified + resource collection"; + input { + leaf capacity { + type enumeration { + enum 'total'; + enum 'reserved'; + enum 'usage'; + enum 'available'; + } + default 'available'; + } + leaf zone { type instance-identifier { ct:instance-type nfvi:AvailabilityZone; } } + uses query-resource-collection; + // TBD: additional parameters for query-capacity + } + output { + leaf-list collections { type instance-identifier + { ct:instance-type ResourceCollection; } } + uses utilization-output; + } + } + + // ALLOCATION INTENTS (should go into VIM module in the future) + rpc create-instance { + description "Create an instance of specified resource(s) utilizing capacity + from the pool"; + input { + leaf provider-id { + if-feature multi-provider; + type instance-identifier { ct:instance-type ResourceProvider; + require-instance true; } + } + leaf name { type string; mandatory true; } + leaf image { + type union { + type yang:uuid; + type inet:uri; + } + mandatory true; + } + leaf flavor { + type union { + type yang:uuid; + type inet:uri; + } + mandatory true; + } + // TODO: consider supporting a template-id (such as HEAT) for more complex instantiation + + leaf reservation-id { + type instance-identifier { ct:instance-type ResourceReservation; + require-instance true; } + } + } + output { + uses common-intent-output; + leaf instance-id { + type instance-identifier { ct:instance-type ResourceAllocation; } + } + } + } + + rpc destroy-instance { + description "Destroy an instance of resource utilization and release it + back to the pool"; + input { + leaf instance-id { + type instance-identifier { ct:instance-type ResourceAllocation; + require-instance true; } + } + } + output { + uses common-intent-output; + } } + // PROVIDER INTENTS (should go into VIM module in the future) rpc add-provider { - description "This operation allows you to register a new ResourceProvider - into promise management service"; + description "Register a new resource provider into reservation system"; input { - leaf provider { - description "Select a specific resource provider"; + leaf provider-type { + description "Select a specific resource provider type"; mandatory true; type enumeration { enum openstack; @@ -252,53 +618,27 @@ ANNEX B: Promise YANG schema based on YangForge status planned; } } + default openstack; } - leaf username { - type string; - mandatory true; - } - leaf password { - type ianach:crypt-hash; - mandatory true; - } - leaf endpoint { - type inet:uri; - description "The target URL endpoint for the resource provider"; - mandatory true; + uses mano:provider-credentials { + refine endpoint { + default "http://localhost:5000/v2.0/tokens"; + } } - leaf region { - type string; - description "Optional specified regsion for the provider"; + container tenant { + leaf id { type string; } + leaf name { type string; } } } output { - leaf id { - description "Unique identifier for the newly added provider found in /promise/providers"; - type instance-identifier { - ct:instance-type ResourceProvider; - } - } - leaf result { - type enumeration { - enum success; - enum error; - } + uses common-intent-output; + leaf provider-id { + type instance-identifier { ct:instance-type ResourceProvider; } } } } - rpc remove-provider; - rpc list-providers; - - rpc check-capacity; - - rpc list-reservations; - rpc create-reservation; - rpc update-reservation; - rpc cancel-reservation; - - rpc list-allocations; - rpc create-allocation; + // TODO... notification reservation-event; notification capacity-event; notification allocation-event; |