| 28 | | Clients (experimenters) use the AM API to discover resources (!ListResources), request resources (Allocate), provision reserved resources (Provision), start resources (!PerformOperationalAction), check the status of resources as they are started (!Status), extend their reservation (Renew), and then return the resources when done (Delete). Client tools may use !GetVersion to ensure aggregates speak a compatible version of the AM API and known formats for RSpecs. Administrators may call Shutdown to stop the resources of a slice at this aggregate, perhaps if that slice is misbehaving. |
| 29 | | |
| 30 | | !ListResources returns to the client an advertisement RSpec - a detailed listing of the resources available at that aggregate. From this information, the experimenter may determine which resources to reserve for their use. The RSpec should also have enough information to help the experimenter set the initial configuration for their resources. |
| 31 | | |
| 32 | | Once the experimenter has selected the resources they want and how to configure them, they produce a request RSpec, detailing the resources they want and how they should be configured. They separately contact their slice authority to obtain a slice credential, granting them rights to reserve resources for that slice. The experimenter then calls Allocate on this API, passing in both the slice credential and the request RSpec. The aggregate then attempts to satisfy the experimenter's resource request. If the aggregate can satisfy the request, the aggregate reserves the resources for the experimenter. The resources have not been provisioned yet, giving the experimenter a chance to verify the reservation. If it is acceptable, the experimenter calls Provision to set up the resources. The aggregate then starts the process of instantiating the resources and configuring them as requested in the request RSpec. Once that process has started, the !CreateSliver call returns with a manifest RSpec, listing the resources as reserved and initially configured for the experimenter. |
| 33 | | |
| 34 | | The experimenter can then poll the aggregate manager to watch as the resources are configured and become ready for use, by calling Status. Once the resources are ready for use, the experimenter will call !PerformOperationalAction(geni_start) to start the resources (e.g. boot a machine). The experimenter will also call Renew to request that their reservation lasts as long as they require the resources for. When the experimenter is done using the resources, they call Delete to end their reservation. The aggregate then stops and clears the resources, freeing them for use by other clients. |
| | 28 | Clients (experimenters) use the AM API to discover resources (`!ListResources`), request resources (`Allocate`), provision reserved resources (`Provision`), start resources (`!PerformOperationalAction`), check the status of resources as they are started (`Status`), extend their reservation (`Renew`), and then return the resources when done (`Delete`). Client tools may use !`GetVersion` to ensure aggregates speak a compatible version of the AM API and known formats for RSpecs. Administrators may call `Shutdown` to stop the resources of a slice at this aggregate, perhaps if that slice is misbehaving. |
| | 29 | |
| | 30 | `!ListResources` returns to the client an advertisement RSpec - a detailed listing of the resources available at that aggregate. From this information, the experimenter may determine which resources to reserve for their use. The RSpec should also have enough information to help the experimenter set the initial configuration for their resources. |
| | 31 | |
| | 32 | Once the experimenter has selected the resources they want and how to configure them, they produce a request RSpec, detailing the resources they want and how they should be configured. They separately contact their slice authority to obtain a slice credential (or set of credentials), granting them rights to reserve resources for that slice. The experimenter then calls `Allocate` on this API, passing in both the slice credential and the request RSpec. The aggregate then attempts to satisfy the experimenter's resource request. If the aggregate can satisfy the request, the aggregate reserves the resources for the experimenter. The resources have not been provisioned yet, giving the experimenter a chance to verify the reservation, or check for corresponding resource availability in another aggregate. If it is acceptable, the experimenter calls `Provision` to set up the resources. The aggregate then starts the process of instantiating the resources and configuring them as requested in the request RSpec. Once that process has started, the `Provision` call returns with a manifest RSpec, listing the resources as reserved and initially configured for the experimenter. |
| | 33 | |
| | 34 | The experimenter can then poll the aggregate manager to watch as the resources are configured and become ready for use, by calling `Status` (FIXME: allocation state is geni_provisioned immediately. Is Operational State not yet geni_notready?). Once the resources are ready for use, the experimenter will call `!PerformOperationalAction(geni_start)` to start the resources (e.g. boot a machine). The experimenter will also call `Renew` to request that their reservation lasts as long as they require the resources for. When the experimenter is done using the resources, they call `Delete` to end their reservation. The aggregate then stops and clears the resources, freeing them for use by other clients. |
| 49 | | 8. {{{Status(<slice URN or sliver URNs>, <slice credential>, <new time>, {})}}} to check that resources have started |
| 50 | | 9. {{{Renew(<slice URN or sliver URNs>, <slice credential>, |
| | 50 | 8. {{{Status(<slice URN or sliver URNs>, <slice credential>, {})}}} to check that resources have started |
| | 51 | 9. {{{Renew(<slice URN or sliver URNs>, <slice credential>, newtime, {})}}} to extend reservation |
| 55 | | '''FIXME: Highlight changes in usage, etc ''' |
| | 56 | This version of the AM API includes multiple changes since version 2 of the AM API. For experimenters, a few things are worth noting: |
| | 57 | - The old` !CreateSliver` operation has now been broken into 3 steps: |
| | 58 | - `Allocate` to reserve the resources |
| | 59 | - `Provision` to instantiate the resources, which may take time to complete |
| | 60 | - `PerformOperationalAction(geni_start)` to start (e.g. boot) the resources, which also may take time to complete |
| | 61 | - Use the intermediate `geni_allocated` state to coordinate reservations across aggregates, e.g. to ensure another aggregate can give you nodes to be the other end of a requested link |
| | 62 | - Multiple methods have been renamed, typically be removing the `Sliver` term from method names. |
| | 63 | - Sliver expiration is available in the return from multiple other methods, like `Provision` |
| | 64 | - You no longer use `!ListResources` to see the contents of your slice - use `Describe` instead. `!ListResources` is only for the AM's Ad RSpec. |
| | 65 | - SSH login names and keys should be available in manifest RSpecs in a standard format. |
| | 66 | - Slice name restrictions have been codified and standardized. |
| | 67 | - Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): `'^[a-zA-Z0-9][-a-zA-Z0-9]+$'` |
| | 68 | |
| | 69 | Tool developers should also be aware: |
| | 70 | - The `credentials` argument to methods is now a struct, including a type and version for each credential. AMs should advertise which credential types they accept. SAs should advertise which type they provide. |
| | 71 | - Aggregates may have their own operational states and actions. The Ad RSpec should define these, probably by `sliver_type`. |
