diff options
| -rw-r--r-- | .gitignore | 6 | ||||
| -rw-r--r-- | docs/configguide/featureconfig.rst | 5 | ||||
| -rw-r--r-- | docs/configguide/index.rst | 9 | ||||
| -rw-r--r-- | docs/platformoverview/index.rst | 9 | ||||
| -rw-r--r-- | docs/platformoverview/promise_platform.rst | 15 | ||||
| -rw-r--r-- | docs/requirements/index.rst | 1 | ||||
| -rw-r--r-- | docs/requirements/revision.rst | 9 | ||||
| -rw-r--r-- | docs/requirements/schemas.rst | 650 | ||||
| -rw-r--r-- | docs/requirements/supported_apis.rst | 604 | ||||
| -rw-r--r-- | docs/userguide/index.rst | 9 | ||||
| -rw-r--r-- | docs/userguide/userguide.rst | 5 |
11 files changed, 1164 insertions, 158 deletions
@@ -1,3 +1,5 @@ -/build/ -/output/ +*~ +.*.sw? +/docs_build/ +/docs_output/ /releng/ diff --git a/docs/configguide/featureconfig.rst b/docs/configguide/featureconfig.rst new file mode 100644 index 0000000..44e7a3a --- /dev/null +++ b/docs/configguide/featureconfig.rst @@ -0,0 +1,5 @@ +====================================== +Promise Feature Configuration Overview +====================================== + +Overview of Promise configuration. diff --git a/docs/configguide/index.rst b/docs/configguide/index.rst new file mode 100644 index 0000000..88bb1a2 --- /dev/null +++ b/docs/configguide/index.rst @@ -0,0 +1,9 @@ +******************************************** +Promise Installation and Configuration Guide +******************************************** + +.. toctree:: + :numbered: + :maxdepth: 2 + + featureconfig.rst diff --git a/docs/platformoverview/index.rst b/docs/platformoverview/index.rst new file mode 100644 index 0000000..aa926dc --- /dev/null +++ b/docs/platformoverview/index.rst @@ -0,0 +1,9 @@ +**************************** +Overview of Promise Platform +**************************** + +.. toctree:: + :numbered: + :maxdepth: 2 + + promise_platform.rst diff --git a/docs/platformoverview/promise_platform.rst b/docs/platformoverview/promise_platform.rst new file mode 100644 index 0000000..0dd3cb9 --- /dev/null +++ b/docs/platformoverview/promise_platform.rst @@ -0,0 +1,15 @@ +========================= +Promise Platform Overview +========================= + +https://wiki.opnfv.org/promise + +Features +======== + +Description of platform capabilities + +Components +========== + +Describe the platform architecture diff --git a/docs/requirements/index.rst b/docs/requirements/index.rst index 5337ff5..3bf0777 100644 --- a/docs/requirements/index.rst +++ b/docs/requirements/index.rst @@ -45,4 +45,5 @@ Promise: Resource Management references.rst annex1.rst schemas.rst + supported_apis.rst revision.rst diff --git a/docs/requirements/revision.rst b/docs/requirements/revision.rst index fcb8c7d..2c4cb54 100644 --- a/docs/requirements/revision.rst +++ b/docs/requirements/revision.rst @@ -1,4 +1,4 @@ -ANNEX C: Document revision +ANNEX D: Document revision ========================== +---------+-----------------------------------------+ @@ -22,3 +22,10 @@ ANNEX C: Document revision | | - Split shim-layer architecture and | | | integrated architecture sections | +---------+-----------------------------------------+ +| 1.0.5 | JIRA: PROMISE-61 | +| | - Updated Promise Yang Schema | ++---------+-----------------------------------------+ +| 1.0.6 | JIRA: PROMISE-62 | +| | - Supported APIs for Brahmaputra | ++---------+-----------------------------------------+ + diff --git a/docs/requirements/schemas.rst b/docs/requirements/schemas.rst index db89c5b..de9d9f8 100644 --- a/docs/requirements/schemas.rst +++ b/docs/requirements/schemas.rst @@ -10,103 +10,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; } } @@ -118,9 +245,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 { @@ -130,22 +255,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 @@ -158,7 +283,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; @@ -166,79 +291,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; @@ -254,53 +620,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; diff --git a/docs/requirements/supported_apis.rst b/docs/requirements/supported_apis.rst new file mode 100644 index 0000000..50a47ab --- /dev/null +++ b/docs/requirements/supported_apis.rst @@ -0,0 +1,604 @@ +ANNEX C: Supported APIS +======================= + +Add Provider +------------ + +Register a new resource provider (e.g. OpenStack) into reservation system. + +Request parameters + +============================ =========== ============================================== +Name Type Description +============================ =========== ============================================== +provider-type Enumeration Name of the resource provider +endpoint URI Targer URL end point for the resource provider +username String User name +password String Password +region String Specified region for the provider +tenant.id String Id of the tenant +tenant.name String Name of the tenant +============================ =========== ============================================== + +Response parameters + +============================ =========== ============================================== +Name Type Description +============================ =========== ============================================== +provider-id String Id of the new resource provider +result Enumeration Result info +============================ =========== ============================================== + +.. http:post:: /add-provider + :noindex: + + **Example request**: + + .. sourcecode:: http + + POST /add-provider HTTP/1.1 + Accept: application/json + + { + "provider-type": "openstack", + "endpoint": "http://10.0.2.15:5000/v2.0/tokens", + "username": "promise_user", + "password": "******", + "tenant": { + "name": "promise" + } + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302", + "result": "ok" + } + +Create Reservation +------------------ + +Make a request to the reservation system to reserve resources. + +Request parameters + +============================ =============== ============================================== +Name Type Description +============================ =============== ============================================== +zone String Id to an availability zone +start DateTime Timestamp when the consumption of reserved + resources can begin +end DateTime Timestamp when the consumption of reserved + resources should end +capacity.cores int16 Amount of cores to be reserved +capacity.ram int32 Amount of RAM to be reserved +capacity.instances int16 Amount of instances to be reserved +capacity.addresses int32 Amount of public IP addresses to be reserved +elements ResourceElement List of pre-existing resource elements + to be reserved +============================ =============== ============================================== + +Response parameters + +============================ =========== ============================================== +Name Type Description +============================ =========== ============================================== +reservation-id String Id of the reservation +result Enumeration Result info +message String Output message +============================ =========== ============================================== + +.. http:post:: /create-reservation + :noindex: + + **Example request**: + + .. sourcecode:: http + + POST /create-reservation HTTP/1.1 + Accept: application/json + + { + "capacity": { + "cores": "5", + "ram": "25600", + "addresses": "3", + "instances": "3" + }, + "start": "2016-02-02T00:00:00Z", + "end": "2016-02-03T00:00:00Z" + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "reservation-id": "269b2944-9efc-41e0-b067-6898221e8619", + "result": "ok", + "message": "reservation request accepted" + } + +Update Reservation +------------------ + +Update reservation details for an existing reservation. + +Request parameters + +============================ =============== ============================================== +Name Type Description +============================ =============== ============================================== +reservation-id String Id of the reservation to be updated +zone String Id to an availability zone +start DateTime Updated timestamp when the consumption of + reserved resources can begin +end DateTime Updated timestamp when the consumption of + reserved resources should end +capacity.cores int16 Updated amount of cores to be reserved +capacity.ram int32 Updated amount of RAM to be reserved +capacity.instances int16 Updated amount of instances to be reserved +capacity.addresses int32 Updated amount of public IP addresses + to be reserved +elements ResourceElement Updated list of pre-existing resource elements + to be reserved +============================ =============== ============================================== + +Response parameters + +============================ =========== ============================================== +Name Type Description +============================ =========== ============================================== +result Enumeration Result info +message String Output message +============================ =========== ============================================== + +.. http:post:: /update-reservation + :noindex: + + **Example request**: + + .. sourcecode:: http + + POST /update-reservation HTTP/1.1 + Accept: application/json + + { + "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619", + "capacity": { + "cores": "1", + "ram": "5120", + "addresses": "1", + "instances": "1" + } + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "result": "ok", + "message": "reservation update successful" + } + +Cancel Reservation +------------------ + +Cancel the reservation. + +Request parameters + +============================ =============== ============================================== +Name Type Description +============================ =============== ============================================== +reservation-id String Id of the reservation to be canceled +============================ =============== ============================================== + +Response parameters + +============================ =========== ============================================== +Name Type Description +============================ =========== ============================================== +result Enumeration Result info +message String Output message +============================ =========== ============================================== + +.. http:post:: /cancel-reservation + :noindex: + + **Example request**: + + .. sourcecode:: http + + POST /cancel-reservation HTTP/1.1 + Accept: application/json + + { + "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619" + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "result": "ok", + "message": "reservation canceled" + } + +Query Reservation +----------------- + +Query the reservation system to return matching reservation(s). + +Request parameters + +============================ ================== ============================================== +Name Type Description +============================ ================== ============================================== +zone String Id to an availability zone +show-utilization Boolean Show capacity utilization +without ResourceCollection Excludes specified collection identifiers + from the result +elements.some ResourceElement Query for ResourceCollection(s) that contain + some or more of these element(s) +elements.every ResourceElement Query for ResourceCollection(s) that contain + all of these element(s) +window.start DateTime Matches entries that are within the specified + start/end window +window.end DateTime +wndow.scope Enumeration Matches entries that start {and/or} end + within the time window +============================ ================== ============================================== + +Response parameters + +============================ =================== ================================ +Name Type Description +============================ =================== ================================ +reservations ResourceReservation List of matching reservations +utilization CapacityUtilization Capacity utilization over time +============================ =================== ================================ + +.. http:post:: /query-reservation + :noindex: + + **Example request**: + + .. sourcecode:: http + + POST /query-reservation HTTP/1.1 + Accept: application/json + + { + "show-utilization": false, + "window": { + "start": "2016-02-01T00:00:00Z", + "end": "2016-02-04T00:00:00Z" + } + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "reservations": [ + "269b2944-9efv-41e0-b067-6898221e8619" + ], + "utilization": [] + } + +Create Instance +--------------- + +Create an instance of specified resource(s) utilizing capacity from the pool. + +Request parameters + +============================ =============== ============================================== +Name Type Description +============================ =============== ============================================== +provider-id String Id of the resource provider +reservation-id String Id of the resource reservation +name String Name of the instance +image String Id of the image +flavor String Id of the flavor +============================ =============== ============================================== + +Response parameters + +============================ =========== ============================================== +Name Type Description +============================ =========== ============================================== +instance-id String Id of the instance +result Enumeration Result info +message String Output message +============================ =========== ============================================== + +.. http:post:: /create-instance + :noindex: + + **Example request**: + + .. sourcecode:: http + + POST /create-instance HTTP/1.1 + Accept: application/json + + { + "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302", + "name": "vm1", + "image": "ddffc6f5-5c86-4126-b0fb-2c71678633f8", + "flavor": "91bfdf57-863b-4b73-9d93-fc311894b902" + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "instance-id": "82572779-896b-493f-92f6-a63008868250", + "result": "ok", + "message": "created-instance request accepted" + } + +Destroy Instance +---------------- + +Destroy an instance of resource utilization and release it back to the pool. + +Request parameters + +============================ =============== ============================================== +Name Type Description +============================ =============== ============================================== +instance-id String Id of the instance to be destroyed +============================ =============== ============================================== + +Response parameters + +============================ =========== ============================================== +Name Type Description +============================ =========== ============================================== +result Enumeration Result info +message String Output message +============================ =========== ============================================== + +.. http:post:: /destroy-instance + :noindex: + + **Example request**: + + .. sourcecode:: http + + POST /destroy-instance HTTP/1.1 + Accept: application/json + + { + "instance-id": "82572779-896b-493f-92f6-a63008868250" + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "result": "ok", + "message": "instance destroyed and resource released back to pool" + } + +Decrease Capacity +----------------- + +Decrease total capacity for the reservation system for a given time window. + +Request parameters + +============================ =============== ============================================== +Name Type Description +============================ =============== ============================================== +source String Id of the resource container +start DateTime Start/end defines the time window when total + capacity is decreased +end DateTime +capacity.cores int16 Decreased amount of cores +capacity.ram int32 Decreased amount of RAM +capacity.instances int16 Decreased amount of instances +capacity.addresses int32 Decreased amount of public IP addresses +============================ =============== ============================================== + +Response parameters + +============================ =========== ============================================== +Name Type Description +============================ =========== ============================================== +pool-id String Id of the resource pool +result Enumeration Result info +message String Output message +============================ =========== ============================================== + +.. http:post:: /decrease-capacity + :noindex: + + **Example request**: + + .. sourcecode:: http + + POST /decrease-capacity HTTP/1.1 + Accept: application/json + + { + "source": "ResourcePool:4085f0da-8030-4252-a0ff-c6f93870eb5f", + "capacity": { + "cores": "3", + "ram": "5120", + "addresses": "1" + } + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "pool-id": "c63b2a41-bcc6-42f6-8254-89d633e1bd0b", + "result": "ok", + "message": "capacity decrease successful" + } + +Increase Capacity +----------------- + +Increase total capacity for the reservation system for a given time window. + +Request parameters + +============================ =============== ============================================== +Name Type Description +============================ =============== ============================================== +source String Id of the resource container +start DateTime Start/end defines the time window when total + capacity is increased +end DateTime +capacity.cores int16 Increased amount of cores +capacity.ram int32 Increased amount of RAM +capacity.instances int16 Increased amount of instances +capacity.addresses int32 Increased amount of public IP addresses +============================ =============== ============================================== + +Response parameters + +============================ =========== ============================================== +Name Type Description +============================ =========== ============================================== +pool-id String Id of the resource pool +result Enumeration Result info +message String Output message +============================ =========== ============================================== + +.. http:post:: /increase-capacity + :noindex: + + **Example request**: + + .. sourcecode:: http + + POST /increase-capacity HTTP/1.1 + Accept: application/json + + { + "source": "ResourceProvider:f6f13fe3-0126-4c6d-a84f-15f1ab685c4f", + "capacity": { + "cores": "20", + "ram": "51200", + "instances": "10", + "addresses": "10" + } + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "pool-id": "279217a4-7461-4176-bf9d-66770574ca6a", + "result": "ok", + "message": "capacity increase successful" + } + +Query Capacity +-------------- + +Query for capacity information about a specified resource collection. + +Request parameters + +============================ ================== ============================================== +Name Type Description +============================ ================== ============================================== +capacity Enumeration Return total or reserved or available or + usage capacity information +zone String Id to an availability zone +show-utilization Boolean Show capacity utilization +without ResourceCollection Excludes specified collection identifiers + from the result +elements.some ResourceElement Query for ResourceCollection(s) that contain + some or more of these element(s) +elements.every ResourceElement Query for ResourceCollection(s) that contain + all of these element(s) +window.start DateTime Matches entries that are within the specified + start/end window +window.end DateTime +window.scope Enumeration Matches entries that start {and/or} end + within the time window +============================ ================== ============================================== + +Response parameters + +============================ =================== ================================ +Name Type Description +============================ =================== ================================ +collections ResourceCollection List of matching collections +utilization CapacityUtilization Capacity utilization over time +============================ =================== ================================ + +.. http:post:: /query-capacity + :noindex: + + **Example request**: + + .. sourcecode:: http + + POST /query-capacity HTTP/1.1 + Accept: application/json + + { + "show-utilization": false + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 201 CREATED + Content-Type: application/json + + { + "collections": [ + "ResourcePool:279217a4-7461-4176-bf9d-66770574ca6a" + ], + "utilization": [] + } + diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst new file mode 100644 index 0000000..0000aa6 --- /dev/null +++ b/docs/userguide/index.rst @@ -0,0 +1,9 @@ +****************** +Promise User Guide +****************** + +.. toctree:: + :numbered: + :maxdepth: 2 + + userguide.rst diff --git a/docs/userguide/userguide.rst b/docs/userguide/userguide.rst new file mode 100644 index 0000000..e337adf --- /dev/null +++ b/docs/userguide/userguide.rst @@ -0,0 +1,5 @@ +================== +Promise User Guide +================== + +Promise user guide documentation. |