| 1 | | [[PageOutline]] |
| 2 | | |
| 3 | | = GENI Aggregate Manager API Version 1 = |
| 4 | | |
| 5 | | The GENI Aggregate Manager API allows aggregates to advertise resources and to allocate resources to Slices in the form of Slivers. |
| 6 | | |
| 7 | | This is the GENI AM API Version '''1'''. |
| 8 | | |
| 9 | | See Also: |
| 10 | | * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf Slice-based Facility Architecture (SFA) specification] |
| 11 | | * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa-impl.pdf PlanetLab Implementation of the Slice-Based Facility Architecture] |
| 12 | | * [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2 ProtoGENI Component Manager API revision 2] |
| 13 | | * [wiki:GeniApi GENI API] implementation status |
| 14 | | * [wiki:GAPI_AM_API Latest] revision of this API |
| 15 | | * [wiki:DRAFT_GAPI_AM_API_DRAFT Draft API Revisions] proposed for future versions of this API |
| 16 | | |
| 17 | | == Versions == |
| 18 | | |
| 19 | | * Latest: Always available on [wiki:GAPI_AM_API the main AM API page] |
| 20 | | * As of this writing, that is [wiki:DRAFT_GAPI_AM_API_V2 version 2] |
| 21 | | * Previous: Version 1 - Documented on this page |
| 22 | | * [wiki:DRAFT_GAPI_AM_API_DRAFT Draft Changes] |
| 23 | | * As of this writing, those will be for version 3 of the API |
| 24 | | * Documents proposed changes for future versions of the API |
| 25 | | |
| 26 | | ----- |
| 27 | | == !GetVersion == |
| 28 | | |
| 29 | | Return the version of the GENI Aggregate API supported by this aggregate. |
| 30 | | |
| 31 | | {{{ |
| 32 | | struct GetVersion() |
| 33 | | }}} |
| 34 | | |
| 35 | | The result is an [http://www.xmlrpc.com/spec XML-RPC] struct with at least the following members: |
| 36 | | |
| 37 | | {{{ |
| 38 | | { |
| 39 | | int geni_api; |
| 40 | | } |
| 41 | | }}} |
| 42 | | |
| 43 | | `geni_api`:: |
| 44 | | An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This page documents version 1 of the API. |
| 45 | | |
| 46 | | Implementations can add additional members to the struct as desired. The prefix {{{geni_}}} is reserved for members that are part of this API specification. Implementation should choose an appropriate prefix to avoid conflicts. |
| 47 | | |
| 48 | | This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetVersion GetVersion] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation. |
| 49 | | |
| 50 | | ----- |
| 51 | | == !ListResources == |
| 52 | | |
| 53 | | Return information about available resources or resources allocated to a slice. |
| 54 | | |
| 55 | | {{{ |
| 56 | | string ListResources(string credentials[], struct options) |
| 57 | | }}} |
| 58 | | |
| 59 | | `credentials[]`:: |
| 60 | | An array of credentials. At least one credential must be valid for this operation (signed by a valid GENI certificate authority either directly or by chain, and not expired). Note that the semantics of this argument is not clear. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions. |
| 61 | | |
| 62 | | `options`:: |
| 63 | | An [http://www.xmlrpc.com/spec XML-RPC] struct containing members indicating the set of resources the caller is interested in or the format of the result. In addition to the members specified below, callers can pass additional members that specific aggregate manager implementations might honor. The prefix {{{geni_}}} is reserved for members that are part of this API specification. Implementations should choose an appropriate prefix to avoid conflicts. |
| 64 | | |
| 65 | | The following members are available for use in the options parameter. All aggregate managers are required to implement these options. |
| 66 | | |
| 67 | | {{{ |
| 68 | | { |
| 69 | | boolean geni_available; |
| 70 | | boolean geni_compressed; |
| 71 | | string geni_slice_urn; |
| 72 | | } |
| 73 | | }}} |
| 74 | | |
| 75 | | `geni_available`:: |
| 76 | | An [http://www.xmlrpc.com/spec XML-RPC] boolean value indicating whether the caller is interested in all resources or available resources. If this value is true, the result should contain only available resources. If this value is false both available and allocated resources should be returned. The Aggregate Manager is free to limit visibility of certain resources based on the credentials parameter. |
| 77 | | |
| 78 | | `geni_compressed`:: |
| 79 | | An [http://www.xmlrpc.com/spec XML-RPC] boolean value indicating whether the caller would like the result to be compressed. If the value is true, the returned resource list will be compressed according to [http://www.ietf.org/rfc/rfc1950.txt RFC 1950]. |
| 80 | | |
| 81 | | `geni_slice_urn`:: |
| 82 | | An [http://www.xmlrpc.com/spec XML-RPC] string indicating that the caller is interested in the set of resources allocated to the slice named by this URN. If no resources are allocated to the indicated slice by this aggregate, an empty RSPEC should be returned. |
| 83 | | |
| 84 | | |
| 85 | | The return value is an RSPEC in text format if geni_compressed is unspecified or set to false. The return value will be a base 64 encoded if geni_compressed is specified and set to true. |
| 86 | | |
| 87 | | This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DiscoverResources DiscoverResources] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !GetResources operation (sec. 6.2.4). |
| 88 | | |
| 89 | | |
| 90 | | ----- |
| 91 | | == !CreateSliver == |
| 92 | | |
| 93 | | Allocate resources to a slice. This operation is expected to start the allocated resources asynchronously after the operation has successfully completed. Callers can check on the status of the resources using [wiki:GAPI_AM_API#SliverStatus SliverStatus]. |
| 94 | | |
| 95 | | {{{ |
| 96 | | string CreateSliver(string slice_urn, |
| 97 | | string credentials[], |
| 98 | | string rspec, |
| 99 | | struct users[]) |
| 100 | | }}} |
| 101 | | |
| 102 | | `slice_urn`:: |
| 103 | | The URN of the slice to which the resources specified in {{{rspec}}} will be allocated. |
| 104 | | |
| 105 | | `credentials`:: |
| 106 | | An array of credentials. At least one credential must be a valid slice credential for the slice specified in {{{slice_urn}}}. Note that the semantics of this argument is not clear. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions. Aggregates should ensure that the expiration time of the slice does not exceed the expiration time of the slice credential used to perform this operation. |
| 107 | | |
| 108 | | `rspec`:: |
| 109 | | An RSPEC containing the resources that the caller is requesting for allocation to the slice specified in {{{slice_urn}}}. These are expected to be based on resources returned by a previous invocation of [#ListResources ListResources]. |
| 110 | | |
| 111 | | `users`:: |
| 112 | | 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: |
| 113 | | {{{ |
| 114 | | [ |
| 115 | | { |
| 116 | | urn: urn:publicid:IDN+geni.net:gcf+user+alice |
| 117 | | keys: [<ssh key>, <ssh key>] |
| 118 | | }, |
| 119 | | { |
| 120 | | urn: urn:publicid:IDN+geni.net:gcf+user+bob |
| 121 | | keys: [<ssh key>] |
| 122 | | } |
| 123 | | ] |
| 124 | | }}} |
| 125 | | The return value is an RSPEC indicating the resources that were allocated to the slice. The result RSPEC may contain additional information about the allocated resources. |
| 126 | | |
| 127 | | This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#CreateSliver CreateSliver] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !CreateSlice operation (sec. 6.2.1). |
| 128 | | |
| 129 | | |
| 130 | | ----- |
| 131 | | == !DeleteSliver == |
| 132 | | |
| 133 | | Delete a sliver by stopping it if it is still running, and then deallocating the resources associated with it. This call will stop and deallocate all resources associated with the given slice URN. |
| 134 | | |
| 135 | | {{{ |
| 136 | | boolean DeleteSliver(string slice_urn, string credentials[]) |
| 137 | | }}} |
| 138 | | |
| 139 | | `slice_urn`:: |
| 140 | | The URN of the slice whose sliver should be deleted. |
| 141 | | |
| 142 | | `credentials`:: |
| 143 | | An array of credentials. At least one credential must be a valid slice credential for the slice specified in {{{slice_urn}}}. Note that the semantics of this argument is not clear. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions. |
| 144 | | |
| 145 | | Returns true on success and false on failure. |
| 146 | | |
| 147 | | This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DeleteSliver DeleteSliver] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !DeleteSlice operation (sec. 6.2.3). |
| 148 | | |
| 149 | | |
| 150 | | ----- |
| 151 | | == !SliverStatus == |
| 152 | | |
| 153 | | Get the status of a sliver. |
| 154 | | |
| 155 | | {{{ |
| 156 | | struct SliverStatus(string slice_urn, string credentials[]) |
| 157 | | }}} |
| 158 | | |
| 159 | | `slice_urn`:: |
| 160 | | The URN of the slice for which the sliver status is requested. |
| 161 | | |
| 162 | | `credentials`:: |
| 163 | | An array of credentials. At least one credential must be a valid slice credential for the slice specified in {{{slice_urn}}}. Note that the semantics of this argument is not clear. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions. |
| 164 | | |
| 165 | | Returns an XML-RPC struct upon successful completion. The struct is of the following form: |
| 166 | | |
| 167 | | {{{ |
| 168 | | { |
| 169 | | geni_urn: <sliver URN> |
| 170 | | geni_status: ready |
| 171 | | geni_resources: [ { geni_urn: <resource URN> |
| 172 | | geni_status: ready |
| 173 | | geni_error: ''}, |
| 174 | | { geni_urn: <resource URN> |
| 175 | | geni_status: ready |
| 176 | | geni_error: ''} |
| 177 | | ] |
| 178 | | } |
| 179 | | }}} |
| 180 | | |
| 181 | | The top level members of the returned struct pertain to the sliver as a whole. These members are: |
| 182 | | |
| 183 | | `geni_urn`:: |
| 184 | | The URN of the sliver as a string. This is the ''sliver'' and not the ''slice'', and should be selected by the aggregate manager. |
| 185 | | |
| 186 | | `geni_status`:: |
| 187 | | A string indicating the status of the sliver. Possible values are: {{{configuring}}}, {{{ready}}}, {{{failed}}}, and {{{unknown}}}. Configuring indicates that at least one resource is being configured and none have failed. Ready indicates that all resources in the sliver are ready. Failed indicates that at least one resource in the sliver has failed. Unknown indicates that the state of the sliver is not one of the known states. More detailed information can be found in the value of the geni_resources member. |
| 188 | | |
| 189 | | `geni_resources`:: |
| 190 | | An array of structs. Each struct in the array gives the status of each resource in the sliver. The members of these structs are described below. |
| 191 | | |
| 192 | | The members of the resource struct(s) are as follows: |
| 193 | | |
| 194 | | `geni_urn`:: |
| 195 | | The URN of the resource as a string. This is specific to the ''sliver'', and should be selected by the aggregate manager to allow status reporting and control at the finest level supported at that aggregate. It may be a sliver URN if there is only 1 resource in the sliver. |
| 196 | | |
| 197 | | `geni_status`:: |
| 198 | | A string indicating the status of the resource. Possible values are: {{{configuring}}}, {{{ready}}}, {{{failed}}}, and {{{unknown}}}. Configuring indicates that the resources is being configured and is not yet ready for use. Ready indicates that the resource is ready. Failed indicates that the resource has failed. Unknown indicates that the state of the resource is not one of the known states. |
| 199 | | |
| 200 | | `geni_error`:: |
| 201 | | A free form string. The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the resource if its status is {{{failed}}}. |
| 202 | | |
| 203 | | |
| 204 | | This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#SliverStatus,WaitForStatus SliverStatus] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation. |
| 205 | | |
| 206 | | |
| 207 | | ----- |
| 208 | | == !RenewSliver == |
| 209 | | |
| 210 | | Renews the resources in a sliver, extending the lifetime of the slice. |
| 211 | | |
| 212 | | {{{ |
| 213 | | boolean RenewSliver(string slice_urn, |
| 214 | | string credentials[], |
| 215 | | string expiration_time) |
| 216 | | }}} |
| 217 | | |
| 218 | | `slice_urn`:: |
| 219 | | The URN of the slice that is to have its sliver renewed. |
| 220 | | |
| 221 | | `credentials`:: |
| 222 | | An array of credentials. At least one credential must be a valid slice credential for the slice specified in {{{slice_urn}}}. Note that the semantics of this argument is not clear. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions. |
| 223 | | |
| 224 | | `expiration_time`:: |
| 225 | | A string in [http://tools.ietf.org/html/rfc3339 RFC 3339] format indicating the expiration_time desired by the caller. Note these times, per the RFC, must be in or relative to UTC. This time must be less than or equal to the slice duration in the slice credential. In other words, at least one supplied (slice) credential must still be valid at the desired new expiration time for this call to succeed. |
| 226 | | |
| 227 | | |
| 228 | | Returns true on successful completion, false otherwise. It is assumed that the caller will have already extended the lifetime of the slice credential with the appropriate slice authority prior to calling !RenewSliver. |
| 229 | | |
| 230 | | This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#RenewSlice RenewSlice] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation. |
| 231 | | |
| 232 | | |
| 233 | | ----- |
| 234 | | == Shutdown == |
| 235 | | |
| 236 | | Perform an emergency shut down of a sliver. This operation is intended for administrative use. The sliver is shut down but remains available for further forensics. |
| 237 | | |
| 238 | | {{{ |
| 239 | | boolean Shutdown(string slice_urn, string credentials[]) |
| 240 | | }}} |
| 241 | | |
| 242 | | `slice_urn`:: |
| 243 | | The URN of the slice is to have its sliver shut down. |
| 244 | | |
| 245 | | `credentials`:: |
| 246 | | An array of credentials. At least one credential must be a valid slice credential for the slice specified in {{{slice_urn}}} or a valid administrative credential with sufficient privileges. Note that the semantics of this argument is not clear. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions. |
| 247 | | |
| 248 | | Returns true on success, false otherwise. |
| 249 | | |
| 250 | | This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Shutdown Shutdown] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation. |
| | 1 | See wiki:GAPI_AM_API_V1 |
