# Instance lifecycle

The states an instance passes through, what each one allows, and what it costs.

## States

| State           | Meaning                                                                     |
| --------------- | --------------------------------------------------------------------------- |
| `pending`       | The machine is being created or started.                                    |
| `running`       | Booted. Start, stop, shutdown and reboot change it from here.               |
| `rebooting`     | A reboot is in flight.                                                      |
| `stopping`      | A stop or shutdown is in flight.                                            |
| `stopped`       | Powered off; the machine, its disk, its addresses and its volumes are kept. |
| `shutting-down` | Termination is in flight: the machine is being deleted.                     |
| `terminated`    | The machine is gone. The record stays in the list until you delete it.      |

The console shows the transitions as **Starting…**, **Stopping…**, **Rebooting…** and
**Terminating…**.

## What each state allows

| Action                 | Allowed in                                                       |
| ---------------------- | ---------------------------------------------------------------- |
| Start                  | `stopped`                                                        |
| Stop, shutdown, reboot | `running`                                                        |
| Resize                 | `stopped`                                                        |
| Create a machine image | `running` or `stopped`                                           |
| Attach a volume        | any state but `terminated`, once the machine exists              |
| Terminate              | any state; a second terminate on `terminated` removes the record |

A request in another state is refused with `400`, for example "Cannot start instance in state:
running", "Cannot stop instance in state: …", "Instance must be stopped before resizing (current
state: …)" or "Cannot snapshot instance in state: …". If a start, stop, shutdown or reboot fails
at the provider, the instance goes back to the state it had and its page shows the error. If a
termination fails, the instance stays `stopping` with the error.

## Wait for a state

```sh
dcloud ec2 instances wait i-3f9a2c07 --state stopped --timeout-seconds 300
```

`wait` (`GET /ec2/api/instances/{id}/wait`) answers as soon as the instance is in the state
(`running` by default; `running` also means the machine exists at the provider), `408` after
`timeoutSeconds` (default 120, at most 300; call again to keep waiting), or `409` at once if the
instance terminated first.

## Cost by state

An instance is billed only while it is `running`: for every started hour it runs, at most its
type's monthly price per calendar month. Its root disk and its public IPv4 address are part of that
price. A stopped instance is not billed at all. What belongs to it is billed on its own, in every
state, for as long as it exists: volumes (by size, attached or not), elastic IPs (allocated,
associated or not), and volume snapshots and machine images (by storage).

## Related

- [Stop, start or reboot an instance](stop-start-or-reboot.md)
- [Terminate an instance](terminate-an-instance.md)
