Changes between Version 17 and Version 18 of GAPI_AM_API_V3_DETAILS


Ignore:
Timestamp:
07/13/12 13:53:02 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_V3_DETAILS

    v17 v18  
    151151-----
    152152== `Describe` Details ==
    153 `Describe` is used to list the resources belonging to a particular reservation. The return is always a single manifest RSpec, describing the resources in the set of slivers whose URNs were supplied, or describing the entire single slice whose URN was supplied as an argument.
     153`Describe` is used to list the resources belonging to a particular reservation. The return is the standard AM API struct, whose value is a struct that always includes a single manifest RSpec, describing the resources in the set of slivers whose URNs were supplied, or describing the entire single slice whose URN was supplied as an argument.
    154154
    155155The manifest RSpec should contain all necessary details about resource identity, configuration, and access information necessary for experimenters to use the resources. As that configuration information may change as the resource becomes operationally `geni_ready`, this information may change. Otherwise, the manifest is mostly static.
    156156
    157 Additionally, `Describe` returns basic state and expiration information for all queried slivers.
     157Additionally, `Describe` returns basic state and expiration information for all queried slivers. Valid values for `geni_allocation_status` and `geni_operational_status` are described on the Common Concepts page.
    158158
    159159For details on options to `Describe`, see `ListResources` above, and the Common Concepts page.
     
    172172              geni_expires: "2012-06-06T12:00:00Z",
    173173              geni_allocation_status: "geni_allocated"
    174           },
     174              geni_operational_status: "geni_pending_allocation",
     175         },
    175176          {
    176177              geni_sliver_urn: "urn:publicid:IDN+pgenigpolabbbncom+sliver+123457",
    177178              geni_expires: "2012-06-16T12:00:00Z",
    178179              geni_allocation_status: "geni_provisioned"
     180              geni_operational_status: "geni_ready",
     181              geni_error: ""
    179182          }
    180183    ]
     
    217220
    218221== `Renew` Details ==
    219 `Renew` requests a changed expiration for one or more slivers in a slice. At some aggregates, this expiration may be shorter. This method applies both to slivers that are `geni_allocated` and to those that are already `geni_provisioned`. Depending on local aggregate configuration, the aggregate may only support `Renew` on all current slivers in the slice, or may permit renewing only some slivers. Local policy will dictate maximum expiration times. These times are typically quite short (~ 10 minutes initially, ~120 minutes maximum) for reservations (`geni_allocated`), and longer for provisioned slivers (~ 5-8 days initially). Since these expiration times are different, typically `Renew` is used only for slivers in the same allocation state.
     222`Renew` requests a changed expiration for one or more slivers in a slice. At some aggregates, this expiration may be shorter. This method applies both to slivers that are `geni_allocated` and to those that are already `geni_provisioned`. Depending on local aggregate configuration, the aggregate may only support `Renew` on all current slivers in the slice, or may permit renewing only some slivers. Local policy will dictate maximum expiration times. These times are typically quite short (~ 10 minutes initially, ~120 minutes maximum) for reservations (`geni_allocated`), and longer for provisioned (`geni_provisioned`) slivers (~ 5-8 days initially). Since these expiration times are different, typically `Renew` is used only for slivers in the same allocation state.
    220223
    221224Sample Return `value`:
     
    252255Redeem a reservation, requesting that the listed slivers move from `geni_allocated` to `geni_provisioned`. Only when slivers are provisioned are the resources 'instantiated' and made ready for operational use. Note that at some aggregates and for some resource types, this operation may be a no-op. At other aggregates, this operation starts a long running process (e.g. loading an image on a machine and booting it). Tools should monitor the sliver status (by calling `Status`), looking for an operational state other than `geni_pending_allocation`. Depending on the resource type, that next state may differ. See the advertisement RSpec for the resource type specific operational states and actions.
    253256
    254 As with the `Allocate` method, some aggregates may not support provisioning only some reserved resources. Also as with the `Allocate` method, experimenters may request a sliver expiration time; aggregates may succeed the operation while ignoring the requested expiration time or granting a different expiration time.
     257As with the `Allocate` method, some aggregates may not support provisioning only some reserved resources. Also as with the `Allocate` method, experimenters may request a sliver expiration time; aggregates may allow the operation while ignoring the requested expiration time or granting a different expiration time.
    255258
    256259Some resource types allow experimenter access. The `geni_users` option allows specifying login key material to be installed on the resources (e.g. SSH public keys).
     
    314317Operational actions, and the states that result, are resource type and aggregate specific. Aggregates advertise these in the advertisement RSpec.
    315318
    316 Example actions include `geni_start` (boot a computer) and `geni_stop` (power down a computer).
     319Example actions include `geni_start` (boot a computer), `geni_restart` (reboot a computer), and `geni_stop` (power down a computer).
    317320
    318321 `geni_error`::