Image Templates and Catalogs

Overview

An image in Xloud serves as more than a boot disk — it is the authoritative template for instance provisioning. A well-managed image catalog ensures consistent deployments, enforces approved operating system versions, and supports multi-project sharing with access control. This guide covers using images as templates, organizing a catalog, publishing community images, exporting images for external use, and managing versions.

Using Images as Templates

Every instance launch derives from an image. Treating images as immutable, versioned templates — rather than ad-hoc uploads — produces consistent, repeatable deployments. Template design principles:

One image per OS version and configuration profile (e.g., ubuntu-24.04-base, ubuntu-24.04-nginx)
Images are never modified after publishing — create a new version instead
Customization at launch time uses cloud-init user data, not image-level changes
Golden images include security hardening, required packages, and licensing pre-applied

Dashboard
CLI

Upload or build the template image

Navigate to Project → Images → Images and click Create Image.Set Visibility to Private while the image is being validated, then promote to Shared or Community when ready.

Add template metadata

After uploading, click the image name and select Update Metadata. Use standard image properties to communicate template purpose:

Property	Example Value
`os_distro`	`ubuntu`
`os_version`	`24.04`
`hw_disk_bus`	`virtio`
`hw_vif_model`	`virtio`
`description`	`Ubuntu 24.04 LTS base template v1.2`

Launch from the template

When creating an instance, select the image from the Source step. The instance inherits all hardware properties defined in the image metadata.

Template in use — instances launched from this image receive consistent hardware configuration.

Source your credentials file to authenticate with the Xloud platform:

Load credentials

source admin-openrc.sh

Download the OpenRC file from Xloud Dashboard → Project → API Access → Download OpenStack RC File.

Upload a template image

openstack image create \
  --disk-format qcow2 \
  --container-format bare \
  --file ubuntu-24.04-server-cloudimg-amd64.img \
  --property os_distro=ubuntu \
  --property os_version=24.04 \
  --property hw_disk_bus=virtio \
  --property hw_vif_model=virtio \
  --property description="Ubuntu 24.04 LTS base template v1.0" \
  --visibility private \
  ubuntu-24.04-base-v1.0

Launch an instance from the template

openstack server create \
  --image ubuntu-24.04-base-v1.0 \
  --flavor m1.medium \
  --network internal-net \
  my-vm-01

Image Catalog Management

A catalog is the set of approved, maintained images available to tenants. Administrators control what appears in the catalog by managing image visibility and metadata.

Visibility Levels

Visibility	Who Can See	Use Case
`private`	Owner project only	Development, staging images not ready for sharing
`shared`	Owner + explicitly shared projects	Controlled sharing with specific teams
`community`	All tenants (read-only for non-admin)	Approved OS catalog available platform-wide
`public`	All tenants (admin-controlled)	Platform-wide golden images

Only users with the admin role can set image visibility to public or community. You can set your own images to shared and add project members to the sharing list.

Promote an Image to the Catalog

Dashboard
CLI

Navigate to Admin → Image → Images, find the image, click Edit Image, and set Visibility to Community or Public.

Promote image to community visibility

openstack image set \
  --community \
  ubuntu-24.04-base-v1.0

List all community images

openstack image list \
  --community \
  --long

Community Images

Community images are images made available to all tenants without requiring explicit sharing grants. They are managed by administrators and appear in every project’s image list.

Create a community image

openstack image create \
  --disk-format qcow2 \
  --container-format bare \
  --file rocky-linux-9.qcow2 \
  --property os_distro=rocky \
  --property os_version=9 \
  --community \
  rocky-linux-9-v1.0

Decommission a community image (hide from catalog)

openstack image set \
  --private \
  rocky-linux-9-v1.0

Setting an image back to private does not delete running instances that were launched from it. Only future launches are affected.

Image Export

Images can be exported for use outside the platform — for migration to another environment, backup archiving, or external distribution.

Dashboard
CLI

Navigate to Admin → Image → Images, select the image, and click Actions → Download. The image file is downloaded in its native format (QCOW2 or RAW depending on upload format).

Download an image to local disk

openstack image save \
  --file ubuntu-24.04-export.qcow2 \
  ubuntu-24.04-base-v1.0

Export and convert format (requires qemu-img)

openstack image save --file /tmp/image.raw ubuntu-24.04-base-v1.0
qemu-img convert -f raw -O qcow2 /tmp/image.raw ubuntu-24.04-export.qcow2

Verify exported image integrity

qemu-img check ubuntu-24.04-export.qcow2

For large images, use the Glance image import deactivate/reactivate API to pause an image before export to ensure consistency:

Deactivate image before export (prevents modification)

openstack image deactivate <image-id>
openstack image save --file large-image.qcow2 <image-id>
openstack image reactivate <image-id>

Image Versioning

Xloud Image Service does not enforce versioning natively — version tracking is implemented through naming conventions and image properties. The recommended approach: Naming convention: <os>-<version>-<profile>-v<major>.<minor> Examples:

ubuntu-24.04-base-v1.0
ubuntu-24.04-base-v1.1
ubuntu-24.04-nginx-v2.0

Deprecation workflow:

Mark old version as deprecated

openstack image set \
  --deactivated \
  --property deprecated=true \
  --property replacement=ubuntu-24.04-base-v1.1 \
  ubuntu-24.04-base-v1.0

Hide deprecated image from tenant catalog

openstack image set \
  --private \
  ubuntu-24.04-base-v1.0

Keep deprecated images in private visibility (not deleted) until you verify no instances are running from them. Check with: openstack server list --all-projects --image <image-id>

Dashboard
CLI

Navigate to Project → Images → Images, click the image name, select Share Image, and enter the target project ID.The target project administrator must accept the share from Project → Images → Images → Shared with Me.

Share image with another project

openstack image add project \
  ubuntu-24.04-base-v1.0 \
  <target-project-id>

Target project accepts the shared image

openstack image set \
  --accept \
  ubuntu-24.04-base-v1.0

Verify shared image is visible in target project

openstack image list --shared

Next Steps

Storage Backends

Configure RBD, Swift, S3, or file store as the image storage backend

Image Properties

Set hardware and scheduler properties on images to control instance behavior

Image Security

Sign images and enforce signature verification at launch time

Upload Image

Upload custom images from ISO, QCOW2, RAW, or VMDK formats

Core Services

Other Services

Image Templates and Catalogs

Overview

Using Images as Templates

Upload or build the template image

Add template metadata

Launch from the template

Image Catalog Management

Visibility Levels

Promote an Image to the Catalog

Community Images

Image Export

Image Versioning

Next Steps

Storage Backends

Image Properties

Image Security

Upload Image

Core Services

Other Services

​Overview

​Using Images as Templates

Upload or build the template image

Add template metadata

Launch from the template

​Image Catalog Management

​Visibility Levels

​Promote an Image to the Catalog

​Community Images

​Image Export

​Image Versioning

​Sharing Images Between Projects

​Next Steps

Storage Backends

Image Properties

Image Security

Upload Image

Overview

Using Images as Templates

Image Catalog Management

Visibility Levels

Promote an Image to the Catalog

Community Images

Image Export

Image Versioning

Sharing Images Between Projects

Next Steps