Import a disk image as a volume

Import a disk image when you’ve built one yourself and want it as a volume’s initial content. The platform downloads the image from an HTTP(S) URL, converts it to raw format, and writes it into a new volume. To launch instances from the result, snapshot and protect the volume, then create an image from the snapshot.

Before you begin

The URN of the project to create the volume in.
Permission pvs.volume.create on the project, the same permission as creating a volume. See Roles.
An active organization, a billing account that can pay, and enough volume storage quota for the full size you ask for. See Create a volume.
A disk image at an HTTP(S) URL. The platform sends a plain GET request with no credentials, so the URL itself must grant access.
The image’s virtual size. This is the size of the disk the image represents, not the size of the file you download. For a compressed or sparse image the file is much smaller. For a qcow2 image, qemu-img info shows it as virtual size.

Choose the image and size

The platform detects the image format and converts it. Common disk image formats are accepted, including qcow2 (also compressed qcow2) and raw. Host the image file itself, not an archive of it such as .gz or .xz.

sizeInGib is the size of the volume you get. It’s what the disk becomes, what counts against your quota, and what you’re billed for:

An image whose virtual size is smaller than sizeInGib leaves you the extra space.
An image whose virtual size is larger than sizeInGib is refused. The import fails and the volume ends in ERROR, because the platform can’t shrink your image without destroying part of it.

Import the image

Start the import with a size of at least the image’s virtual size.

terminal

origin storage import-volume --project-urn <project-urn> \
  --size-in-gib 20 \
  --source-url https://example.com/images/my-image.qcow2

With the API, use the importVolume mutation:

GraphQL

mutation {
  pvs {
    importVolume(input: {
      projectUrn: "<project-urn>"
      sizeInGib: 20
      sourceUrl: "https://example.com/images/my-image.qcow2"
    }) {
      urn
      status
    }
  }
}

Add --storage-class or storageClass to choose a class other than the default. See Storage classes.

Check the volume’s status until it leaves CREATING.
terminal
```
origin storage get-volume --volume-urn <volume-urn>
```
AVAILABLE means the import succeeded and the volume holds your image.

Time limits

An import must finish within 25 minutes, including downloading, converting, and writing the image. The import fails with ERR_IMPORT when:

it takes longer than 25 minutes, for example a very large image or a slow source,
the source answers with an HTTP error status,
the source sends no data for 60 seconds.

If the import fails

A failed import leaves the volume in ERROR, and statusReason names the cause:

`statusReason`	Cause and fix
`the operation failed (ERR_IMPORT_IMAGE_TOO_LARGE)`	The image’s virtual size is larger than `sizeInGib`. Delete the volume and import again with a larger size.
`the operation failed (ERR_IMPORT)`	The download, conversion, or write failed, or the import ran out of time. Delete the volume and import again, from a faster source if time was the problem.

No data from a failed import is kept, but the ERROR volume counts against your quota until you delete it. See Delete a volume.

Before you begin

Choose the image and size

Import the image

Time limits

If the import fails

Next steps

Related