Skip to main content

​
Overview

The Image Import API provides advanced upload mechanisms beyond the basic PUT endpoint. Web download allows server-side fetching directly from a URL — no local staging needed. Chunked upload supports resumable large-image transfers. Both methods are available to users, but administrators configure the allowed import methods and staging area at the platform level.
Administrator Access Required — This operation requires the admin role. Contact your Xloud administrator if you do not have sufficient permissions.

​
Allowed Import Methods

Configure which import methods are available to users via XDeploy globals:
Enable import methods
glance_enabled_import_methods: "web-download,glance-direct"
MethodDescriptionBest For
web-downloadImage Service fetches data from a URL server-sideImporting from public cloud image registries
glance-directClient uploads in chunks via staging areaLarge files (>5 GB) requiring resumable upload
copy-imageCopy image between storesMulti-store deployments

​
Web Download Import

The web download method imports images directly from a public URL. The Image Service downloads the file server-side — no local disk space required on the client.

Create the image record

Create image record for web-download
openstack image create \
  --disk-format qcow2 \
  --container-format bare \
  --import-method web-download \
  ubuntu-24.04-noble
Note the image id from the output.

Trigger the import

Import from Ubuntu cloud images
openstack image import \
  --method web-download \
  --uri https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img \
  <IMAGE_ID>

Monitor import progress

Poll import status
watch -n 5 "openstack image show <IMAGE_ID> -c status"
Status transitions from importing to active when complete.

​
Chunked Upload (Glance Direct)

Chunked upload allows large images to be uploaded in parts, with the ability to resume if the connection is interrupted.

Create the image record

Create image record
openstack image create \
  --disk-format qcow2 \
  --container-format bare \
  large-windows-image
Note the image id.

Stage data to the import queue

Stage image data via the v2 import API. The staging area is temporary and managed by the Image Service:
Stage image data
TOKEN=$(openstack token issue -f value -c id)

curl -X PUT \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @/path/to/large-image.qcow2 \
  "https://api.<your-domain>:9292/v2/images/<IMAGE_ID>/stage"

Trigger import from staging

Import from staging area
openstack image import \
  --method glance-direct \
  <IMAGE_ID>
Image transitions to active after import completes from the staging area.

​
Staging Area Configuration

The staging area is a temporary directory used by the glance-direct import method. Configure its location and size limits:
Staging area configuration
glance_image_import_plugins: "image_conversion,inject_image_metadata"
glance_staging_store_uri: "file:///var/lib/glance/staging"
The staging area should be on fast local storage (SSD) with sufficient capacity for your largest expected image. Staging data is deleted after successful import.

​
Next Steps

Storage Backends

Configure where imported images are stored after the import completes.

Metadata

Define metadata namespaces for consistent property schemas on imported images.

Admin Troubleshooting

Resolve web-download timeouts and staging area failures.

Upload an Image

Standard upload workflow for user-facing image ingestion.