| | 1 | [[TOC]] |
| | 2 | |
| | 3 | = DETER Containers API = |
| | 4 | |
| | 5 | The containers API is a set of simple and extensible operations to control testbed elements. It is primarily a way for the testbed control to communicate with experiment elements. As such it is not usually visible to users. For power users we do supply a passtrough interface so that they can access specializations of containers. |
| | 6 | |
| | 7 | == Testbed to Containers Operations == |
| | 8 | |
| | 9 | Each of these is sent to a container controller with a distinct address. A controller is often responsible for more than one container. In general we attempt to scale the number of controllers with the number of physical resources so that the testbed can communicate with them directly. In very large testbeds, there may be interconnected controllers acting as relays. |
| | 10 | |
| | 11 | The operations in this section are all exported from the container controller. The testbed discovers container controllers when they report in using the operation in the following section. |
| | 12 | |
| | 13 | All the control commands can be applied to multiple containers simultaneously. |
| | 14 | |
| | 15 | There are only a few things all containers can do: |
| | 16 | |
| | 17 | Begin operating as an experiment element. For a computer, boot; for a flux capacitor, begin travelling in time: |
| | 18 | |
| | 19 | * '''Service:''' Containers |
| | 20 | * '''Operation:''' start |
| | 21 | * '''Input Parameters:''' |
| | 22 | * NameRE - an optional list of regular expressions to match against container names |
| | 23 | * Types - a list of container types to restrict the operations to |
| | 24 | * '''Return Values:''' |
| | 25 | * None |
| | 26 | |
| | 27 | Become quiescent. Only containers API requests will work on a stopped container |
| | 28 | |
| | 29 | * '''Service:''' Containers |
| | 30 | * '''Operation:''' stop |
| | 31 | * '''Input Parameters:''' |
| | 32 | * NameRE - an optional list of regular expressions to match against container names |
| | 33 | * Types - a list of container types to restrict the operations to |
| | 34 | * '''Return Values:''' |
| | 35 | * None |
| | 36 | |
| | 37 | Set up the container's internal state. (For a computer, establish accounts and mount filesystems; for a flux capacitor, set travel rate and destination date). Configuration can be a multi-step process to facilitate configuring many containers at once. A base configuration can be distributed broadly and sub-configurations passes to specialized elements. The semantics of combining configurations can vary per-container-type, but are generally a sequential application of configurations. |
| | 38 | |
| | 39 | * '''Service:''' Containers |
| | 40 | * '''Operation:''' configure |
| | 41 | * '''Input Parameters:''' |
| | 42 | * NameRE - an optional list of regular expressions to match against container names |
| | 43 | * Types - a list of container types to restrict the operations to |
| | 44 | * ConfigData - an opaque field used to configure the container |
| | 45 | * Commit - a flag indicating that this is the configuration is complete and the container can begin applying it |
| | 46 | * '''Return Values:''' |
| | 47 | * None |
| | 48 | |
| | 49 | Containers can describe themselves. Again, controllers can collapse multiple like containers into one operation. |
| | 50 | |
| | 51 | * '''Service:''' Containers |
| | 52 | * '''Operation:''' describe |
| | 53 | * '''Input Parameters:''' |
| | 54 | * NameRE - an optional list of regular expressions to match against container names |
| | 55 | * Types - a list of container types to restrict the operations to |
| | 56 | * '''Return Values:''' |
| | 57 | * An array of structures with the following fields |
| | 58 | * Names - an array of strings naming containers |
| | 59 | * Type - a string giving the container type |
| | 60 | * ConfigFormat - the configuration format that the container supports |
| | 61 | * Interfaces - a list of pre-defined extension interfaces supported by the container. If "custom" is given ExtendedOps is required |
| | 62 | * ExtendedOps - an optional list of URIs from which the WSDL for custom extended operations can be gathered |
| | 63 | |
| | 64 | Get the state of containers |
| | 65 | |
| | 66 | * '''Service:''' Containers |
| | 67 | * '''Operation:''' state |
| | 68 | * '''Input Parameters:''' |
| | 69 | * NameRE - an optional list of regular expressions to match against container names |
| | 70 | * Types - a list of container types to restrict the operations to |
| | 71 | * '''Return Values:''' |
| | 72 | * a list of fields of the form |
| | 73 | * Names - an array of container names |
| | 74 | * State - a string giving the state |
| | 75 | * Down - The container is in communication with the testbed, but not yet configured to act as an experiment element |
| | 76 | * Configured - The container is set up to act as an experiment element but is not yet doing so |
| | 77 | * Pinned - The container is not acting as an experiment element, but is carrying out an operation that renders it otherwise unusable. For example, a container that is capturing its state may be in this state. |
| | 78 | * Up - The container is acting as an experiment element |
| | 79 | * None - Nothing is known about the container. is is (as yet) unresponsive. |
| | 80 | |
| | 81 | == Containers to Testbed Operations == |
| | 82 | |
| | 83 | A container controller can report a state change to the testbed using the call |
| | 84 | |
| | 85 | * '''Service:''' Containers |
| | 86 | * '''Operation:''' newState |
| | 87 | * '''Input Parameters:''' |
| | 88 | * Controller - the URI of the container controller reporting |
| | 89 | * Names - an array of container names |
| | 90 | * State - a string giving the state, as in state above |
| | 91 | |
| | 92 | As containers are initialized, controllers will check in with the testbed using this call. |
