Changes between Version 31 and Version 32 of GAPI_AM_API_DRAFT


Ignore:
Timestamp:
02/29/12 05:53:16 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_DRAFT

    v31 v32  
    227227  - They must be redeemed by a specified time, {{{redeem_before}}}, after which the aggregate is free to assign the resources elsewhere.
    228228   - Aggregates determine {{{redeem_before}}}, which is some epsilon in the near future.
    229    - Aggregates may accept a new option {{{geni_reserve_until}}} which is a request for a particular {{{redeem_before}}}, but are not required to support this.
     229   - Aggregates may accept a new option {{{geni_reserve_until}}} which is a request for a particular {{{redeem_before}}}, but are not required to support this (they may ignore the option).
    230230  - Tickets specify when the resources will be available from ({{{starts}}}, typically essentially now), and when they will be available until (typically now plus the aggregate-local default sliver expiration time).
    231231    - The resources may be available even longer, but that would require a separate !RenewSlivers call.
     
    317317 string geni_start_time=<optional (may be omitted altogether): now if not specified>,
    318318 string geni_expires=<RFC3339 sliver expiration>,
    319  string geni_status=<sliver state - allocated or changing or ready>,
     319 string geni_status=<sliver state - allocated (or optionally changing or ready)>,
    320320 string geni_state_guarantee=<promise from AM of what experimenter state will be lost on trying to 'start' this allocation>,
    321321 <others that are AM specific>
     
    323323}}}
    324324 - Begin allocating the resources promised in the ticket.
    325  - Option {{{geni_donotstart}}}:
    326   - If supplied and true (boolean: 0 or 1 in XML-RPC), final state is {{{allocated}}}, and experimenter must explicitly start or restart resources using !ActOnSlivers
    327   - If omitted, AM automatically starts/restarts resources, and state will be {{{changing}}} and then {{{ready}}}
     325 - Option {{{geni_auto_start}}}:
     326  - If supplied and true (boolean: 0 or 1 in XML-RPC), the aggregate automatically start/restarts resources as necessary, as though the experimenter called !ActOnSlivers(start).
     327   - State will be {{{changing}}} and then {{{ready}}}
     328  - If omitted the aggregate does not start resources (default behavior). The final state is {{{allocated}}}, and the experimenter must explicitly start or restart resources using !ActOnSlivers
     329  - Note that resources which do not require a 'start' may already be {{{ready}}} on normal return from !RedeemTicket.
    328330 - Omitting the ticket causes the aggregate to redeem the outstanding ticket for this slice if any. If none, return an error code.
    329331
     
    423425 - {{{uninitialized}}}: This is the state before any AM-local operation for this slice.
    424426 - {{{ticketed}}}: The resources are reserved for the slice, but not currently provisioned for the slice. Slivers are {{{ticketed}}} after !GetTicket, !UpdateTicket, or after !UpdateSlivers. Note in particular that a slice may have some resources that are {{{ready}}} and others which are {{{ticketed}}} after an !UpdateSlivers call: we call the whole slice {{{ticketed}}} in this case.
    425  - {{{allocated}}}: The sliver(s) are currently provisioned for the slice, but not necessarily fully ready for experimental use (eg, not booted). This is the state after !RedeemTicket, or after !CreateSlivers with the {{{geni_donotstart}}} option.   
     427 - {{{allocated}}}: The sliver(s) are currently provisioned for the slice, but not necessarily fully ready for experimental use (eg, not booted). This is the state after !RedeemTicket, or after !CreateSlivers with the {{{geni_donotstart}}} option.
    426428 - {{{ready}}}: The resources are ready for experimental use, as in after !CreateSlivers completes any booting or starting. Similarly after !ActOnSlivers with the {{{start}}} command. Note that each of those methods starts a process that may take significant time to complete. During that time the sliver will not yet be {{{ready}}}.
    427429 - {{{closed}}}: When the slice was previously provisioned resources, which have now expired or been de-allocated with !DeleteSlivers, we call the sliver {{{closed}}}. Note that this state is rarely seen in practice - aggregates do not respond in this API to queries about slices that do not currently have outstanding allocations or tickets.
     
    469471}}}
    470472
     473Note: some resources may not require an explicit 'start' operation. In this case !CreateSlivers may leave some slivers {{{ready}}}, skipping right past {{{allocated}}}.
     474
    471475Summary of changes:
    472476 - {{{configuring}}} becomes {{{changing}}}, which can be used in many other cases, in returns from !SliversStatus
     
    481485!ActOnSlivers takes a {{{command}}}, {{{urn}}}, {{{state}}}, and {{{options}}}. The method return is a struct that includes the {{{urn}}}, {{{geni_status}}} of the sliver(s), and any other AM and operation specific options. The URN may be a slice urn, meaning all slivers in that slice at this AM are effected. Or the URN may be a particular sliver URN. The {{{state}}} argument is one of the {{{geni_status}}} values, or an AM-specific value. The {{{state}}} meaning depends on the {{{command}}}, but typically indicates the desired or resulting new state of the sliver(s). If the AM wishes to return an aggregate specific sliver status, it should still return a valid {{{geni_status}}}, and use an additional entry to also return the aggregate specific state. The {{{command}}} argument is aggregate defined. This API does not specify how aggregates advertise valid commands.
    482486
    483 Three particular commands are specified however: {{{start}}}, {{{stop}}}, and {{{restart}}} (case insensitive). If an aggregate provides resources which require an explicit action to make {{{allocated}}} resources {{{ready}}} for experimenter use (booting, applying a configuration change) then the aggregate must make that operation available using these commands. These commands are used when the {{{geni_donotstart}}} option is supplied to !CreateSlivers for example.
     487Three particular commands are specified however: {{{start}}}, {{{stop}}}, and {{{restart}}} (case insensitive). If an aggregate provides resources which require an explicit action to make {{{allocated}}} resources {{{ready}}} for experimenter use (booting, applying a configuration change) then the aggregate must make that operation available using these commands. These commands are used after !RedeemSlivers or when the {{{geni_donotstart}}} option is supplied to !CreateSlivers for example.
    484488
    485489For example, to start allocated resources:
     
    808812}}}
    809813
    810 Options include {{{geni_donotstart}}}
     814Options include {{{geni_auto_start}}}
    811815
    812816Return struct: