Perform the named operational action on the named slivers, possibly changing the :operational_status of the named slivers. E.G. 'start' a VM. For valid operations and expected states, consult the state diagram advertised in the aggregate’s advertisement RSpec. See also the [SliverOperationalActions Sliver Operational Actions] section.
Operational actions modify the running state of the resource, not the nature of the resources in the reservation. To add or remove resources from the reservation, use [Delete] and [Allocate]. Operational actions, and the states that result, are resource type and aggregate specific. Aggregates advertise these in the advertisement RSpec. Example actions include :start (boot a computer), :restart (reboot a computer), and :stop (power down a computer).
PerformOperationalAction (string urns[], struct credentials[], string action,
struct options={})Aggregate Managers SHOULD return an error code of 13 (UNSUPPORTED) if they do not support a given action for a given resource. An AM SHOULD constrain actions based on the current operational state of the resource. This is a fast synchronous operation, and MAY start long-running sliver transitions whose status can be queried using [Status]. This method should only be called, and is only valid, when the sliver is fully allocated (operational status is not :pending_allocation).
While the action argument may be aggregate and sliver type specific (none are required for all aggregates and sliver types), this API does define three common actions that AMs should support if possible: :start, :stop, and :restart.
See the urns argument for details.
The standard authorization argument. See the Credentials section.
| Supported by the server |
Mandatory |
| Included by client |
Mandatory |
| XML-RPC type |
string |
The operational action to perform.
A struct containing optional arguments, indexed by name. See General Options Argument Section.
See :best_effort option for details.
Default is false (action applies to all slivers equally or none; the method returns an error code without changing the operational state if any sliver fails).
| XML-RPC type |
struct |
See the sliver info list return for details.
On success, the value field of the return struct will contain a list of structs:
| XML-RPC type |
[ {
":sliver_urn" : <string>,
":allocation_status": <string: eg :provisioned>,
":operational_status": <string>,
":expires": <string.dateTime.rfc3339: date of individual sliver expiration>,
[optional: ":resource_status" : string with resource-specific status in more detail than operational_status; may be omitted],
[optional: ":error": string explanation of operation failure for this sliver. The field may be omitted but if present may not be null/None.]
},
...
]Expired, deleted and unknown slivers, or slices without valid slivers, will cause this call to return SEARCHFAILED. See the urns argument for more details on this error code and return value.
The optional :resource_status field MAY be returned for each sliver which contains a resource-specific status that may be more nuanced than the options for :operational_status.
The PerformOperationalAction call can return the usual error codes: BADARGS, ERROR, SERVERERROR and UNAVAILABLE. See Error Codes for general errors.
Additionally, the PerformOperationalAction call can return the following error codes:
| FORBIDDEN |
Credential does not grant permission to a slice or sliver specified in the urns argument. Or the slice has been shut down. |
| UNSUPPORTED |
The aggregate does not support the given operation for the given resource(s) in their current state |
| EXPIRED |
The sliver has expired. |
| SEARCHFAILED |
The slice or sliver does not exist at this AM. |
| BUSY |
Slice or sliver is temporarily locked, try again later |
| INPROGRESS |
Requested operation is already in progress |