Changes between Version 30 and Version 31 of AaronHelsinger/GAPI_AM_API_DRAFT


Ignore:
Timestamp:
03/30/12 09:31:54 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • AaronHelsinger/GAPI_AM_API_DRAFT

    v30 v31  
    341341}}}
    342342 - Give up the reservation for resources.
    343  - Return: True or error
     343 - Return: true (1 in XMLRPC) or error
    344344 - Omitting the ticket causes the aggregate to release the 0 or 1 outstanding tickets for this slice.
    345345 - If this ticket was from !UpdateSlivers, then the sliver returns to the {{{allocated}}} state and existing resources are not modified.
    … …  
    497497These methods all take a new option (aggregates must support it, clients do not need to supply it):
    498498{{{
    499    geni_best_effort: <True/False, default False>
     499   geni_best_effort: <XML-RPC boolean 1/0, default 0>
    500500}}}
    501501If false, the client is requesting that the aggregate either fully satisfy the request, moving all listed slivers to the desired state, or fully fail the request, leaving all slivers in their original state.
    … …  
    504504'''Note''': !CreateSlivers remains all or nothing (either the aggregate can allocate all desired resources as requested, or the call fails).
    505505
    506 '''Note''': These calls are synchronous - when they return, the slivers shall be in their final state. In particular, the transition from state 2 to 3 (`geni_allocated` to `geni_provisioned`) should be quick. The resource that is now in the 'provisioned' state may take a long time to actually be ready for operational use (e.g. imaging and booting the node) -- this remains true as in version 2 after !CreateSliver.
     506'''Note''': These calls are synchronous - when they return, the slivers shall be in their final state. In particular, the transition from state 2 to 3 (`geni_allocated` to `geni_provisioned`) should be quick. The resource that is now in the 'provisioned' state may take a long time to actually be ready for operational use (e.g. imaging and booting the node) -- this remains true as in version 2 after !CreateSliver. Note that the `geni_allocated` state is by definition cheap, such that transitioning to this state should also be quick.
    507507
    508508!SliverStatus, where it currently includes {{{geni_status}}} for each `geni_resource`, shall now return {{{geni_allocation_status}}} with one of the above defined values, and {{{geni_operational_status}}}. The values of {{{geni_operational_status}}} are still under discussion.
    … …  
    918918----
    919919 = Change summary - method signatures =
    920 If all change sets listed here are adopted, the final method signatures will be as follows:
     920If the generally agreed-upon change sets listed here are adopted, the final method signatures will be as follows:
     921
     922== Common Arguments and Returns ==
     923=== `credentials` ===
     924Many methods take an array of credentials. This is an array of credential type, version, and string value.
     925{{{
     926credentials = [
     927   {
     928    geni_type: <string>,
     929    geni_version: <string>,
     930    geni_value: <string>,
     931    <others>
     932   }
     933]
     934}}}
    921935
    922936 == !GetVersion ==
     937Query static configuration information about this aggregate manager implementation, such as API and RSpec versions supported.
    923938{{{
    924939struct GetVersion([optional: struct options])
    … …  
    956971
    957972 == !ListResources ==
     973Retrieve RSpecs listing resources at this aggregate. Without arguments, retrieve an Advertisement RSpec of available resources. With arguments naming a particular slice and/or slivers, retrieve a Manifest RSpec of resources allocated to the given slivers.
     974
    958975{{{
    959976struct ListResources(struct credentials[], struct options)
    … …  
    975992}}}
    976993
    977 Where credentials is:
    978 {{{
    979 credentials = [
    980    {
    981     geni_type: <string>,
    982     geni_version: <string>,
    983     geni_value: <string>,
    984     <others>
    985    }
    986 ]
    987 }}}
     994Where credentials is the standard argument defined above.
    988995
    989996Where supplying `geni_sliver_urns`, whether or not the `geni_slice_urn` is also supplied, means return a manifest RSpec showing the (allocated or provisioned) slivers listed - not necessarily the complete slice at this aggregate.
    … …  
    10131020 == !CreateSlivers ==
    10141021AKA Allocate()
     1022Request resources described by the given request RSpec to be allocated to the given slice. On success, one or more slivers are allocated, containing resources satisfying the request, and assigned to the given slice. The manifest RSpec describing those resources is returned.
    10151023{{{
    10161024struct CreateSlivers(string slice_urn,
    … …  
    10201028}}}
    10211029
    1022 Where credentials is:
    1023 {{{
    1024 credentials = [
    1025    {
    1026     geni_type: <string>,
    1027     geni_version: <string>,
    1028     geni_value: <string>,
    1029     <others>
    1030    }
    1031 ]
    1032 }}}
     1030Where credentials is the standard argument defined above.
    10331031
    10341032Options include:
    … …  
    10591057 == Renew ==
    10601058AKA !RenewSliver() or !RenewAllocated
     1059Request that the named slivers be renewed, with their expiration extended. If possible, the aggregate should extend the slivers to the requested expiration time, or to a sooner time if policy limits apply. This method applies to slivers that are `geni_allocated` or to slivers that are `geni_provisioned`, though different policies may apply to slivers in the different states, resulting in much shorter max expiration times for `geni_allocated` slivers.
    10611060{{{
    10621061struct Renew(string urn[],
    … …  
    10661065}}}
    10671066
    1068 Where credentials is:
    1069 {{{
    1070 credentials = [
    1071    {
    1072     geni_type: <string>,
    1073     geni_version: <string>,
    1074     geni_value: <string>,
    1075     <others>
    1076    }
    1077 ]
    1078 }}}
    1079 
    1080 Options include {{{geni_best_effort: <True/False, default false>}}}
     1067Where credentials is the standard argument defined above.
     1068
     1069Options include {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
    10811070
    10821071Return list of structs:
    … …  
    10981087 == !UpdateAllocations ==
    10991088AKA !UpdateAllocated()
     1089This method modifies a set of allocated slivers in place. The existing reservations are not lost if the newly requested allocations cannot be satisfied by the aggregate.
     1090
     1091Details are suppressed pending agreement on this method.
     1092{{{
     1093#!comment
     1094
    11001095{{{
    11011096struct UpdateAllocations(string urn[], struct credentials[], string rspec,
    … …  
    11031098}}}
    11041099
    1105 Where credentials is:
    1106 {{{
    1107 credentials = [
    1108    {
    1109     geni_type: <string>,
    1110     geni_version: <string>,
    1111     geni_value: <string>,
    1112     <others>
    1113    }
    1114 ]
    1115 }}}
    1116 
    1117 Options include {{{geni_end_time}}} and {{{geni_best_effort: <True/False, default false>}}}
     1100Where credentials is the standard argument defined above.
     1101
     1102Options include {{{geni_end_time}}} and {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
    11181103
    11191104Return struct:
    … …  
    11371122FIXME: Split Update(slice) from Update(slivers)
    11381123FIXME: Is this the same method as for updating provisioned slivers?
    1139 
     1124}}}
    11401125 == !ProvisionSlivers ==
    11411126AKA Provision()
     1127Request that the named `geni_allocated` slivers be made `geni_provisioned`, instantiating or otherwise realizing the resources, such that they have a valid `geni_operational_status` and may possibly be made `geni_ready` for experimenter use.
    11421128{{{
    11431129struct ProvisionSlivers(string urn[], struct credentials[], 
    … …  
    11451131}}}
    11461132
    1147 Where credentials is:
    1148 {{{
    1149 credentials = [
    1150    {
    1151     geni_type: <string>,
    1152     geni_version: <string>,
    1153     geni_value: <string>,
    1154     <others>
    1155    }
    1156 ]
    1157 }}}
     1133Where credentials is the standard argument defined above.
    11581134
    11591135Options include:
    1160  - {{{geni_best_effort = True/False, default false}}}
     1136 - {{{geni_best_effort = XML-RPC boolean 1 or 0, default false (0)}}}
    11611137 - {{{geni_end_time}}}
    11621138 - `struct geni_users[]`: An array of user structs, which contain information about the users that might login to the sliver that the AM needs to know about. Each struct must include the key 'keys', which is an array of strings and can be empty. The struct must also include the key 'urn', which is the user’s URN string. The users array can be empty. For example:
    … …  
    11971173 == !UpdateSlivers ==
    11981174AKA Update()
     1175This method requests a modification to 1 or more provisioned slivers. The slivers end up in a new `geni_allocated+geni_provisioned` state.
     1176
     1177Details are suppressed pending agreement on this method.
     1178{{{
     1179#!comment
     1180
    11991181{{{
    12001182struct UpdateSlivers(string urn[], struct credentials[], string rspec,
    … …  
    12021184}}}
    12031185
    1204 Where credentials is:
    1205 {{{
    1206 credentials = [
    1207    {
    1208     geni_type: <string>,
    1209     geni_version: <string>,
    1210     geni_value: <string>,
    1211     <others>
    1212    }
    1213 ]
    1214 }}}
     1186Where credentials is the standard argument defined above.
    12151187
    12161188Options include:
    12171189 - {{{geni_end_time}}}
    1218  - {{{geni_best_effort: <True/False, default false>}}}
     1190 - {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
    12191191 - `struct geni_users[]`: An array of user structs, which contain information about the users that might login to the sliver that the AM needs to know about. Each struct must include the key 'keys', which is an array of strings and can be empty. The struct must also include the key 'urn', which is the user’s URN string. The users array can be empty. For example:
    12201192{{{
    … …  
    12531225FIXME: Is this the same method as for updating allocated slivers?
    12541226FIXME: Return both a manifest and a delta RSpec?
    1255 
     1227}}}
    12561228 == !SliversStatus ==
     1229Retrieve status information about the named slivers. This should be relatively dynamic data, not descriptive data as returned in the manifest RSpec by !ListResources.
    12571230{{{
    12581231struct SliversStatus(string urn[], struct credentials[], struct options)
    12591232}}}
    12601233
    1261 Where credentials is:
    1262 {{{
    1263 credentials = [
    1264    {
    1265     geni_type: <string>,
    1266     geni_version: <string>,
    1267     geni_value: <string>,
    1268     <others>
    1269    }
    1270 ]
    1271 }}}
     1234Where credentials is the standard argument defined above.
    12721235
    12731236Return:
    … …  
    12971260
    12981261 == !PerformOperationalAction ==
     1262Perform the named operational action on the named slivers, possibly changing the `geni_operational_status` of the named slivers.
    12991263{{{
    13001264struct PerformOperationalAction (string urn[], struct credentials[], string action,
    … …  
    13021266}}}
    13031267
    1304 Where credentials is:
    1305 {{{
    1306 credentials = [
    1307    {
    1308     geni_type: <string>,
    1309     geni_version: <string>,
    1310     geni_value: <string>,
    1311     <others>
    1312    }
    1313 ]
    1314 }}}
    1315 
    1316 Options include: {{{geni_best_effort: <True/False, default false>}}}
     1268Where credentials is the standard argument defined above.
     1269
     1270Options include: {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
    13171271
    13181272Return list of structs:
    … …  
    13331287
    13341288 == !DeleteSlivers ==
     1289Delete the named slivers, making them `geni_unallocated`. Resources are de-provisioned. No further AM API operations may be performed on slivers that have been deleted.
    13351290{{{
    13361291struct DeleteSlivers(string urn[], struct credentials[], struct options)
    13371292}}}
    13381293
    1339 Where credentials is:
    1340 {{{
    1341 credentials = [
    1342    {
    1343     geni_type: <string>,
    1344     geni_version: <string>,
    1345     geni_value: <string>,
    1346     <others>
    1347    }
    1348 ]
    1349 }}}
    1350 
    1351 Options include: {{{geni_best_effort: <True/False, default false>}}}
     1294Where credentials is the standard argument defined above.
     1295
     1296Options include: {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
    13521297
    13531298Return list of structs:
    … …  
    13651310
    13661311 == Shutdown ==
     1312Perform an emergency shutdown on the slice at this aggregate. Resources should be taken offline, such that experimenter access (on both the control and data plane) is cut off. No further actions on the slice should be possible at this aggregate, until an un-specified operator action restores the slice.
    13671313{{{
    13681314struct Shutdown(string slice_urn, struct credentials[], struct options)
    13691315}}}
    13701316
    1371 Where credentials is:
    1372 {{{
    1373 credentials = [
    1374    {
    1375     geni_type: <string>,
    1376     geni_version: <string>,
    1377     geni_value: <string>,
    1378     <others>
    1379    }
    1380 ]
    1381 }}}
    1382 
    1383 Return: boolean
     1317Where credentials is the standard argument defined above.
     1318
     1319Return: XML-RPC boolean