# Create an image

Turn an instance's root disk into your own image - clear its machine-id, snapshot and protect the volume, create the image - and update or delete it later.

Create your own image to launch more instances with the same software and configuration as one you’ve already set up. You snapshot the instance’s root disk, protect the snapshot, and create an image from it.

## Before you begin [#before-you-begin]

<BeforeYouBegin>

- An instance whose root disk holds what you want in the image.
- The `origin` CLI, signed in. See [CLI access](/docs/platform/access/cli).

</BeforeYouBegin>

## Prepare the instance [#prepare-the-instance]

1. Log in to the instance and clear its machine-id, so every instance launched from the image generates its own:

   ```sh
   sudo truncate -s 0 /etc/machine-id
   sudo rm -f /var/lib/dbus/machine-id
   ```

   If you skip this, every instance from the image shares one machine-id, which breaks VXLAN networking between them. See [Guest environment](/docs/compute/instances/guest-environment).

1. Stop the instance, so the snapshot captures a cleanly shut-down file system. See [Stop and start an instance](/docs/compute/instances/stop-start).

## Snapshot the root disk [#snapshot-the-root-disk]

1. Find the root disk’s volume URN. In `volumeAttachments`, it’s the entry with `isRootDevice` set to `true`:

   ```sh
   origin compute get-instance --instance-urn <instance-urn>
   ```

1. Create a snapshot of that volume:

   ```sh
   origin storage create-snapshot --volume-urn <volume-urn>
   ```

1. Run `get-snapshot` until `status` reads `COMPLETED`. Note its `volumeSizeInGib`:

   ```sh
   origin storage get-snapshot --snapshot-urn <snapshot-urn>
   ```

1. Protect the snapshot. Only a protected snapshot can back an image:

   ```sh
   origin storage protect-snapshot --snapshot-urn <snapshot-urn>
   ```

1. Run `get-snapshot` until `protectionStatus` reads `PROTECTED`.

For more about snapshot states, see [Create and protect a snapshot](/docs/storage/snapshots/create-and-protect).

## Create the image [#create-the-image]

```sh
origin compute create-image \
  --project-urn <project-urn> \
  --root-device-snapshot-urn <snapshot-urn> \
  --root-device-size <size-gib> \
  --description "Web server base"
```

- The snapshot must be in the project you create the image in. A snapshot of another project is refused as not found.
- `--root-device-size` must be at least the snapshot’s `volumeSizeInGib`. It defaults to 8 GiB, so set it when the volume was larger. Instances launched from the image get a root disk of at least this size.
- `--default-user` sets the account instances log in as. Omitted, it’s `cloud`. See [Guest environment](/docs/compute/instances/guest-environment).
- `--root-device-name` sets the guest device name of the root disk. It defaults to `vda`. Names run from `vda` to `vdz`, without `/dev/`, and `vdc` is reserved. Any other value is refused, naming the field.

Then check the result:

1. Verify the image. It reads `status: AVAILABLE`:

   ```sh
   origin compute get-image --image-urn <image-urn>
   ```

1. Launch an instance from it to test it. See [Launch an instance](/docs/compute/instances/launch).

With the API, `createImage` takes the root device as one of a list of `blockDeviceSpecs`, each with a `deviceName`, `snapshotUrn` and `sizeInGib`. `rootDeviceName` must name one of them.

## What keeping an image costs [#what-keeping-an-image-costs]

An image keeps two billed resources alive for as long as you use it:

- **The snapshot behind it.** Completed snapshots are billed for the size of the volume they were taken from, and the snapshot must stay protected for the image’s whole life. Once you unprotect or delete it, launches from the image are refused, although the image still reads `AVAILABLE`.
- **The source volume.** A volume can’t be deleted while any of its snapshots exists, so the root disk you snapshotted stays billed too.

To remove everything, work in this order: delete the image, unprotect and delete the snapshot, then delete the volume. See [Pricing](/docs/pricing) for the rates.

## Update or delete an image [#update-or-delete-an-image]

The description is the only field you can change:

```sh
origin compute update-image \
  --image-urn <image-urn> \
  --description "Web server base, hardened"
```

To delete an image:

```sh
origin compute delete-image --image-urn <image-urn>
```

Deleting an image doesn’t affect instances already launched from it, because each has its own copy on its root disk. The snapshot behind the image isn’t deleted. Unprotect and delete it separately when you no longer need it. See [Delete a snapshot](/docs/storage/snapshots/delete).

You can update and delete only your own images, not platform-provided ones.

## Related [#related]

- [`create-image` reference](/docs/compute/reference/cli#create-image)
- [Images](/docs/compute/images)
- [Snapshots](/docs/storage/snapshots)