Each cloud defines a slightly different lifecycle model for instances. In some clouds, instances start running immediately after creation, in others, they enter a pending state and you need to start them explicitly.
Differences between clouds are modelled by expressing the lifecycle of an instance as a finite state machine and capturing it in an instance states entity.The API defines the following states for an instance:
| State | Meaning |
|---|---|
| start | an instance state before creation of an instance |
| pending | creation of an instance is in progress |
| running | an instance is running |
| shutting-down | an instance is stopped |
| stopped | an instance is stopped |
| finished | all resources for an instance have now been freed |
The details of a particular instance describes also the actions (state transitions) which can be performed on the instance. If the state transition is marked as auto, the transition from one state to another is done automatically. The possible instance actions are:
| Action | Meaning |
|---|---|
| start | starts the instance |
| stop | stops (and for some providers shutdown) the instance |
| reboot | reboots the instance |
| destroy | stops the instance and completely destroys it |
To retrieve the instance states entity for a back-end cloud use call GET /api/instance_states. The instance states entity defines possible transitions between various states of an instance, specific for each back-end cloud. As a result, instance states defines the finite state machine for instances from the given cloud.
Example request:
GET /api/instance_states?format=xml HTTP/1.1 Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) Host: localhost:3002 Accept: */*
Server response:
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 583
<states>
<state name='start'>
<transition action='create' to='pending'></transition>
</state>
<state name='pending'>
<transition auto='true' to='running'></transition>
</state>
<state name='running'>
<transition action='reboot' to='running'></transition>
<transition action='stop' to='shutting_down'></transition>
</state>
<state name='shutting_down'>
<transition auto='true' to='stopped'></transition>
</state>
<state name='stopped'>
<transition auto='true' to='finish'></transition>
</state>
<state name='finish'>
</state>
</states>