# Create a machine image

Snapshot an instance's root disk into a machine image you can launch copies from.

A machine image covers the root disk only; volumes are snapshotted separately (see
[Snapshot a volume](snapshot-a-volume.md)). An image of a running instance is crash-consistent:
what was written to disk is in it, what an application still held in memory is not. Stop the
instance first, or flush the application, for a consistent copy. Replace the ids with your own.

**Important:**
An image is metered as snapshot storage, for the size the provider reports for it, from the moment
it is `pending` until you delete it. Where snapshot storage is not charged yet, the cost shows as
"metered, not charged yet" and is not on your invoice.

## Prerequisites

- Permission for `ec2:CreateImage`.
- In the console, also `ec2:DescribeImages` to open **Images** (without it the page says "Access
  denied").
- The instance is `running` or `stopped`. Any other state is refused with `400` "Cannot snapshot
  instance in state: …"; an unknown instance with `404` "Instance not found".
- Room in the **Machine images** quota (`ec2.images`, images that are not deleted or failed, per
  region). A full quota is refused with `409` "Quota exceeded: Machine images (ec2.images) — …".

## Create the image

**Console**
1. Open **Compute**, then **Images**, and choose **Create image**. (From an instance's page, the
   **Create image** item of its **⋯** menu opens the same dialog with the instance already chosen.)
2. For **Source instance**, choose the instance. Only running and stopped instances can be chosen.
3. For **Name**, enter web-base.
4. (Optional) For **Description**, enter what is in the image.
5. Choose **Create image**. The image appears in the list as **Pending**.

**CLI**
```sh
dcloud ec2 machine-images create --instance-id i-3f9a2c07 --name web-base
```

**API**
```http
POST /ec2/api/machine-images
{ "instanceId": "i-3f9a2c07", "name": "web-base" }
```

**Terraform**
```hcl
resource "dcloud_machine_image" "web_base" {
  instance_id = dcloud_instance.web.id
  name        = "web-base"
}
```

## Result

The answer is `201` with the image (`ewi-…`) in state `pending`; it turns `available` once the copy
is done. If the copy fails, or does not finish within an hour, the image ends `failed`: it cannot
launch anything and is not billed; delete it to clear it from the list. When the provider refuses
the snapshot at once, the request answers `502` "The provider refused the snapshot: …" and the
image is listed as `failed`.

The image records the instance it was taken from and its operating system, architecture and disk
size. **Compute → Images** lists your images; `GET /ec2/api/machine-images` lists them oldest first.

## Related

- [Launch from a machine image](launch-from-an-image.md)
- [Schedule snapshots](schedule-snapshots.md)
- `ec2.machine-images.create` · `dcloud ec2 machine-images create` · `dcloud_machine_image`
