Changes between Version 32 and Version 33 of AaronHelsinger/GAPI_AM_API_DRAFT


Ignore:
Timestamp:
03/30/12 10:26:16 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • AaronHelsinger/GAPI_AM_API_DRAFT

    v32 v33  
    949949}}}
    950950
     951=== `geni_end_time` ===
     952The `geni_end_time` argument requests an expiration of the specified slivers. It is in dateTime.rfc3339 format (defined above).
     953When an explicit argument, it is required, and aggregates must honor the request to the extent local policy permits.
     954When an option in the `options` struct, clients may omit the option, and AMs may choose not to or be unable to honor this option, but may still succeed the overall request.
     955
     956=== `geni_best_effort` ===
     957 {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
     958Clients may omit this option, but aggregates must honor the option if possible. This option modifies the way that the operation applies to all named slivers. By default (`geni_best_effort`=false), the operation must apply equally to all slivers, either succeeding or failing for all. When true, the aggregate may succeed the operation for some slivers, while failing the operation for other slivers.
     959
     960=== `geni_users` ===
     961`struct geni_users[]` is an option for some methods.
     962
     963Clients may omit this option. Aggregates should honor this option for any resource that accepts the provided login keys, and ignore it for other resources. This option is an array of user structs, which contain information about the users that might login to the sliver that the AM needs to know about. For example, this option is the mechanism by which users supply their SSH public keys, permitting SSH login to allocated nodes. In such cases, the corresponding manifest RSpec will contain the `ssh-users` element on each such node, showing the login username and applicable public keys. When this option is supplied, 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. For example:
     964{{{
     965[
     966  {
     967    urn: urn:publicid:IDN+geni.net:gcf+user+alice
     968    keys: [<ssh key>, <ssh key>]
     969  },
     970  {
     971    urn: urn:publicid:IDN+geni.net:gcf+user+bob
     972    keys: [<ssh key>]
     973  }
     974]
     975}}}
     976
    951977 == !GetVersion ==
    952978Query static configuration information about this aggregate manager implementation, such as API and RSpec versions supported.
     
    954980struct GetVersion([optional: struct options])
    955981}}}
     982
     983The `options` argument may be omitted entirely by clients.
    956984
    957985Return struct:
     
    9951023{{{
    9961024{
    997   boolean geni_available;
    998   boolean geni_compressed;
    999   string geni_slice_urn;
    1000   string geni_sliver_urns[];
     1025  boolean geni_available <optional>;
     1026  boolean geni_compressed <optional>;
     1027  string geni_slice_urn <optional>;
     1028  string geni_sliver_urns[] <optional>;
    10011029  struct geni_rspec_version {
    10021030    string type;
    10031031    string version;
    10041032  };
    1005   dateTime.rfc3339 geni_end_time;
    1006 }
    1007 }}}
    1008 
    1009 Where credentials is the standard argument defined above.
     1033}
     1034}}}
     1035
     1036Note that all options may be omitted by the client, exception `geni_rspec_version` which is required. The aggregate must honor all supplied options.
     1037
     1038Where `credentials` is the standard argument defined above.
    10101039
    10111040Where 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.
     
    10641093        ...
    10651094    ]
    1066  <others that are AM specific>
    1067 }
    1068 }}}
    1069 
    1070 The manifest is a manifest of only newly allocated slivers. The `geni_end_time` argument requests an expiration of the allocated slivers. AMs may not be able to honor it, but may still succeed the overall request.
     1095}
     1096}}}
     1097
     1098The manifest is a manifest of only newly allocated slivers.
    10711099
    10721100 == Renew ==
     
    10821110Where credentials is the standard argument defined above.
    10831111
    1084 Options include {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
     1112Options include {{{geni_best_effort}}}
    10851113
    10861114Return list of structs:
     
    10921120   geni_operational_status: <string>,
    10931121   geni_expires: <dateTime.rfc3339 when the sliver expires from its current state>,
    1094    <others AM or method specific>
    10951122  },
    10961123  ...
     
    11151142Where credentials is the standard argument defined above.
    11161143
    1117 Options include {{{geni_end_time}}} and {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
     1144Options include:
     1145 - {{{geni_end_time}}}:
     1146 - {{{geni_best_effort}}}
    11181147
    11191148Return struct:
     
    11291158        ...
    11301159    ]
    1131  <others that are AM specific>
    1132 }
    1133 }}}
    1134 
    1135 The manifest is a manifest of only referenced allocated slivers. The `geni_end_time` argument requests an expiration of the allocated slivers. AMs may not be able to honor it, but may still succeed the overall request.
     1160}
     1161}}}
     1162
     1163The manifest is a manifest of only referenced allocated slivers.
    11361164
    11371165FIXME: Split Update(slice) from Update(slivers)
     
    11491177
    11501178Options include:
    1151  - {{{geni_best_effort = XML-RPC boolean 1 or 0, default false (0)}}}
     1179 - {{{geni_best_effort}}}
    11521180 - {{{geni_end_time}}}
    1153  - `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:
    1154 {{{
    1155 [
    1156   {
    1157     urn: urn:publicid:IDN+geni.net:gcf+user+alice
    1158     keys: [<ssh key>, <ssh key>]
    1159   },
    1160   {
    1161     urn: urn:publicid:IDN+geni.net:gcf+user+bob
    1162     keys: [<ssh key>]
    1163   }
    1164 ]
    1165 }}}
     1181 - `struct geni_users[]`
    11661182
    11671183Return struct:
     
    11751191     geni_operational_status: <string>,
    11761192     geni_expires <dateTime.rfc3339 when the sliver expires from its current state>,
    1177      <others AM or resource specific>
    11781193    },
    11791194    ...
    11801195  ],
    1181   <others AM or resource specific>
    1182 }}}
    1183 
    1184 The `geni_end_time` argument requests an expiration of the provisioned slivers. AMs may not be able to honor it, but may still succeed the overall request.
     1196}}}
    11851197
    11861198FIXME: Is the returned manifest only for newly provisioned slivers? Or all slivers at this AM for this slice?
     
    12031215Options include:
    12041216 - {{{geni_end_time}}}
    1205  - {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
    1206  - `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:
    1207 {{{
    1208 [
    1209   {
    1210     urn: urn:publicid:IDN+geni.net:gcf+user+alice
    1211     keys: [<ssh key>, <ssh key>]
    1212   },
    1213   {
    1214     urn: urn:publicid:IDN+geni.net:gcf+user+bob
    1215     keys: [<ssh key>]
    1216   }
    1217 ]
    1218 }}}
     1217 - {{{geni_best_effort}}}
     1218 - `struct geni_users[]`
    12191219
    12201220Return struct:
     
    12351235
    12361236The RSpec argument may be a new delta format.
    1237 The manifest is a manifest of only referenced provisioned slivers. The `geni_end_time` argument requests an expiration of the provisioned slivers. AMs may not be able to honor it, but may still succeed the overall request.
     1237The manifest is a manifest of only referenced provisioned slivers.
    12381238
    12391239FIXME: Split Update(slice) from Update(slivers)
     
    12411241FIXME: Return both a manifest and a delta RSpec?
    12421242}}}
     1243
    12431244 == !SliversStatus ==
    12441245Retrieve status information about the named slivers. This should be relatively dynamic data, not descriptive data as returned in the manifest RSpec by !ListResources.
     
    12591260                      geni_expires: <dateTime.rfc3339 of individual sliver expiration>
    12601261                      geni_error: <string, eg ''>,
    1261                       [optional: others AM/resource specific]
    1262                     },
     1262                     },
    12631263                    { geni_sliver_urn: <sliver URN>
    12641264                      geni_allocation_status: <string, eg provisioned>
     
    12661266                      geni_expires: <dateTime.rfc3339 of individual sliver expiration>
    12671267                      geni_error: <string, eg ''>,
    1268                       [optional: others AM/resource specific]
    12691268                      }
    12701269                  ]
     
    12831282Where credentials is the standard argument defined above.
    12841283
    1285 Options include: {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
     1284Options include: {{{geni_best_effort}}}
    12861285
    12871286Return list of structs:
     
    12921291        geni_operational_status : <string>,
    12931292        geni_expires: <dateTime.rfc3339 of individual sliver expiration>
    1294         [optional: AM/resource specific]
    12951293        },
    12961294        ...
     
    13091307Where credentials is the standard argument defined above.
    13101308
    1311 Options include: {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
     1309Options include: {{{geni_best_effort}}}
    13121310
    13131311Return list of structs:
     
    13181316   geni_allocation_status: <string>,
    13191317   geni_expires: <dateTime.rfc3339 when the sliver expires from its current state>,
    1320    <others AM or method specific>
    13211318  },
    13221319  ...