Skip to content
Origin Cloud Docs

Compute / Task

Create an image

Updated · 4 min read

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.

On this page7 sections

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

Prepare the instance

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

    terminal
    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.

  2. Stop the instance, so the snapshot captures a cleanly shut-down file system. See Stop and start an instance.

Snapshot the root disk

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

    terminal
    origin compute get-instance --instance-urn <instance-urn>

  2. Create a snapshot of that volume:

    terminal
    origin storage create-snapshot --volume-urn <volume-urn>

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

    terminal
    origin storage get-snapshot --snapshot-urn <snapshot-urn>

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

    terminal
    origin storage protect-snapshot --snapshot-urn <snapshot-urn>

  5. Run get-snapshot until protectionStatus reads PROTECTED.

For more about snapshot states, see Create and protect a snapshot.

Create the image

terminal
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.
  • --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:

    terminal
    origin compute get-image --image-urn <image-urn>

  2. Launch an instance from it to test it. See Launch an instance.

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

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 for the rates.

Update or delete an image

The description is the only field you can change:

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

To delete an image:

terminal
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.

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