Changes between Version 32 and Version 33 of AaronHelsinger/GAPI_AM_API_DRAFT
- Timestamp:
- 03/30/12 10:26:16 (12 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
AaronHelsinger/GAPI_AM_API_DRAFT
v32 v33 949 949 }}} 950 950 951 === `geni_end_time` === 952 The `geni_end_time` argument requests an expiration of the specified slivers. It is in dateTime.rfc3339 format (defined above). 953 When an explicit argument, it is required, and aggregates must honor the request to the extent local policy permits. 954 When 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)>}}} 958 Clients 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 963 Clients 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 951 977 == !GetVersion == 952 978 Query static configuration information about this aggregate manager implementation, such as API and RSpec versions supported. … … 954 980 struct GetVersion([optional: struct options]) 955 981 }}} 982 983 The `options` argument may be omitted entirely by clients. 956 984 957 985 Return struct: … … 995 1023 {{{ 996 1024 { 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>; 1001 1029 struct geni_rspec_version { 1002 1030 string type; 1003 1031 string version; 1004 1032 }; 1005 dateTime.rfc3339 geni_end_time; 1006 } 1007 }}} 1008 1009 Where credentials is the standard argument defined above. 1033 } 1034 }}} 1035 1036 Note that all options may be omitted by the client, exception `geni_rspec_version` which is required. The aggregate must honor all supplied options. 1037 1038 Where `credentials` is the standard argument defined above. 1010 1039 1011 1040 Where 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. … … 1064 1093 ... 1065 1094 ] 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 1098 The manifest is a manifest of only newly allocated slivers. 1071 1099 1072 1100 == Renew == … … 1082 1110 Where credentials is the standard argument defined above. 1083 1111 1084 Options include {{{geni_best_effort : <XML-RPC boolean 1 or 0, default false (0)>}}}1112 Options include {{{geni_best_effort}}} 1085 1113 1086 1114 Return list of structs: … … 1092 1120 geni_operational_status: <string>, 1093 1121 geni_expires: <dateTime.rfc3339 when the sliver expires from its current state>, 1094 <others AM or method specific>1095 1122 }, 1096 1123 ... … … 1115 1142 Where credentials is the standard argument defined above. 1116 1143 1117 Options include {{{geni_end_time}}} and {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}} 1144 Options include: 1145 - {{{geni_end_time}}}: 1146 - {{{geni_best_effort}}} 1118 1147 1119 1148 Return struct: … … 1129 1158 ... 1130 1159 ] 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 1163 The manifest is a manifest of only referenced allocated slivers. 1136 1164 1137 1165 FIXME: Split Update(slice) from Update(slivers) … … 1149 1177 1150 1178 Options include: 1151 - {{{geni_best_effort = XML-RPC boolean 1 or 0, default false (0)}}}1179 - {{{geni_best_effort}}} 1152 1180 - {{{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[]` 1166 1182 1167 1183 Return struct: … … 1175 1191 geni_operational_status: <string>, 1176 1192 geni_expires <dateTime.rfc3339 when the sliver expires from its current state>, 1177 <others AM or resource specific>1178 1193 }, 1179 1194 ... 1180 1195 ], 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 }}} 1185 1197 1186 1198 FIXME: Is the returned manifest only for newly provisioned slivers? Or all slivers at this AM for this slice? … … 1203 1215 Options include: 1204 1216 - {{{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[]` 1219 1219 1220 1220 Return struct: … … 1235 1235 1236 1236 The 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.1237 The manifest is a manifest of only referenced provisioned slivers. 1238 1238 1239 1239 FIXME: Split Update(slice) from Update(slivers) … … 1241 1241 FIXME: Return both a manifest and a delta RSpec? 1242 1242 }}} 1243 1243 1244 == !SliversStatus == 1244 1245 Retrieve status information about the named slivers. This should be relatively dynamic data, not descriptive data as returned in the manifest RSpec by !ListResources. … … 1259 1260 geni_expires: <dateTime.rfc3339 of individual sliver expiration> 1260 1261 geni_error: <string, eg ''>, 1261 [optional: others AM/resource specific] 1262 }, 1262 }, 1263 1263 { geni_sliver_urn: <sliver URN> 1264 1264 geni_allocation_status: <string, eg provisioned> … … 1266 1266 geni_expires: <dateTime.rfc3339 of individual sliver expiration> 1267 1267 geni_error: <string, eg ''>, 1268 [optional: others AM/resource specific]1269 1268 } 1270 1269 ] … … 1283 1282 Where credentials is the standard argument defined above. 1284 1283 1285 Options include: {{{geni_best_effort : <XML-RPC boolean 1 or 0, default false (0)>}}}1284 Options include: {{{geni_best_effort}}} 1286 1285 1287 1286 Return list of structs: … … 1292 1291 geni_operational_status : <string>, 1293 1292 geni_expires: <dateTime.rfc3339 of individual sliver expiration> 1294 [optional: AM/resource specific]1295 1293 }, 1296 1294 ... … … 1309 1307 Where credentials is the standard argument defined above. 1310 1308 1311 Options include: {{{geni_best_effort : <XML-RPC boolean 1 or 0, default false (0)>}}}1309 Options include: {{{geni_best_effort}}} 1312 1310 1313 1311 Return list of structs: … … 1318 1316 geni_allocation_status: <string>, 1319 1317 geni_expires: <dateTime.rfc3339 when the sliver expires from its current state>, 1320 <others AM or method specific>1321 1318 }, 1322 1319 ...