Image Properties

Overview

Image properties are key-value metadata attached to images that influence how the compute service launches instances from that image. Properties communicate the OS type to the hypervisor, set minimum hardware requirements, configure boot firmware, and define the virtual hardware model. Well-configured properties improve compatibility and prevent launch failures from under-resourced flavors.

Prerequisites

An active Polystack account with appropriate permissions
Access to the Polystack Dashboard or CLI configured with credentials
API credentials sourced (source openrc.sh)

Essential Properties Reference

Property Key	Example Value	Purpose
`os_type`	`linux`	Informs the hypervisor of the guest OS family
`os_distro`	`ubuntu`	OS distribution for Ironcore Guest Agent configuration
`os_version`	`24.04`	OS version string
`hw_machine_type`	`q35`	Sets the emulated chipset (q35 for UEFI, i440fx for legacy BIOS)
`hw_firmware_type`	`uefi`	Boot firmware — `uefi` or `bios`
`hw_disk_bus`	`virtio`	Disk controller — `virtio` (best performance) or `ide`
`hw_scsi_model`	`virtio-scsi`	SCSI controller model when `hw_disk_bus=scsi`
`hw_vif_model`	`virtio`	Network interface model
`hw_tpm_model`	`tpm-crb`	Enable virtual TPM device (requires platform support)

Set Properties

Dashboard
CLI

Open image details

Navigate to Compute > Images and click the image name.

Edit basic properties

Click Edit (the first row action) to open the Edit Image dialog. You can modify:

Field	Type	Description
Name	Text	Image display name
OS	Dropdown	Operating system distribution
OS Version	Text	Version string
OS Admin	Text	Default admin username
Min System Disk (GiB)	Number	Minimum root disk (if block storage enabled)
Min Memory (GiB)	Number	Minimum RAM
Public	Checkbox (admin only)	Toggle public visibility
Protected	Checkbox	Prevent accidental deletion
Description	Text area	Optional notes

Click Advanced Options to edit qemu_guest_agent, CPU Policy, and CPU Thread Policy.Click Confirm to save.

The Edit form does NOT include metadata key-value editing. To manage custom metadata properties, administrators use the Manage Metadata action from the More dropdown (admin view only).

Manage custom metadata (admin only)

In the admin view, click the More dropdown on the image row and select Manage Metadata. This opens a dialog where you can add, edit, or remove custom key-value metadata properties and system metadata definitions.

Properties are saved and immediately active for new instance launches.

Authenticate

Source your credentials file to authenticate with the Polystack platform:

Load credentials

source openrc.sh

Your administrator provides the RC (credentials) file for your project. See CLI Setup for configuration details.

Set multiple properties at once

Set OS and hardware properties

openstack image set \
  --property os_type=linux \
  --property os_distro=ubuntu \
  --property os_version=24.04 \
  --property hw_firmware_type=uefi \
  --property hw_machine_type=q35 \
  --property hw_disk_bus=virtio \
  ubuntu-24.04-lts

Verify properties were applied

Show image properties

openstack image show ubuntu-24.04-lts -c properties

All configured properties appear in the output.

Hardware Configuration Examples

Modern Linux with UEFI boot

Ubuntu 24.04 / RHEL 9 UEFI configuration

openstack image set \
  --property hw_firmware_type=uefi \
  --property hw_machine_type=q35 \
  --property hw_disk_bus=virtio \
  --property hw_vif_model=virtio \
  --property os_type=linux \
  ubuntu-24.04-lts

Windows Server with VirtIO drivers

Windows Server 2022 configuration

openstack image set \
  --property hw_firmware_type=uefi \
  --property hw_machine_type=q35 \
  --property hw_disk_bus=virtio \
  --property hw_vif_model=virtio \
  --property os_type=windows \
  --property os_distro=windows \
  --property os_version=2022 \
  windows-server-2022

Windows instances require VirtIO drivers installed in the guest before setting hw_disk_bus=virtio. Without drivers, Windows will fail to boot from a VirtIO disk.

Legacy BIOS compatibility

Legacy BIOS configuration for older OS images

openstack image set \
  --property hw_firmware_type=bios \
  --property hw_machine_type=i440fx \
  --property hw_disk_bus=ide \
  legacy-centos7

Image Metadata & Tags

Beyond hardware properties, images support two additional metadata mechanisms: arbitrary key-value properties for any custom annotation, and tags — simple string labels for filtering and searching across the image catalog.

Arbitrary Properties

Any --property key=value pair is valid. Properties not recognized by the hypervisor are stored and returned but have no behavioral effect. Use them for operational metadata:

Set operational metadata properties

openstack image set \
  --property os_lifecycle=lts \
  --property os_support_until=2029-04-30 \
  --property polystack_base_image=true \
  --property os_security_patch_date=2026-03-01 \
  --property data_classification=public \
  --property compliance=pci-dss \
  ubuntu-24.04-lts

Custom Property Key	Example Value	Purpose
`os_lifecycle`	`lts`, `standard`, `eol`	OS support status
`os_support_until`	`2029-04-30`	End-of-support date for filtering
`polystack_base_image`	`true`	Marks Polystack-maintained base images
`os_security_patch_date`	`2026-03-01`	Last security patch applied
`data_classification`	`public`, `confidential`	Data handling tag
`compliance`	`pci-dss`, `hipaa`, `iso27001`	Regulatory compliance designation
`build_version`	`20260301-001`	CI/CD build identifier
`min_kernel_version`	`5.15`	Minimum kernel required by the OS

Image Tags

Tags are plain string labels — no key, just a value. They enable fast catalog filtering in the Dashboard and CLI without requiring exact property key lookups.

Dashboard
CLI

Edit the image

Navigate to Compute > Images, click Edit (the first row action).

Add tags

In the Edit Image dialog, locate the Tags field. Type a tag and press Enter to add it. Add multiple tags.Useful tags: ubuntu, lts, production-ready, gpu-compatible, windows, pci-dss, baseline-2026, no-cloud-init

Save

Click Confirm. Tags are immediately searchable in the image list.

Add tags to an image

openstack image set \
  --tag ubuntu \
  --tag lts \
  --tag production-ready \
  ubuntu-24.04-lts

Remove a tag

openstack image unset \
  --tag production-ready \
  ubuntu-24.04-lts

List all images with a specific tag

openstack image list --tag lts

Filter by multiple tags

openstack image list --tag lts --tag production-ready

Show all tags on an image

openstack image show ubuntu-24.04-lts -c tags

Tags vs Properties

Feature	Tags	Properties
Format	Simple strings (no key)	Key-value pairs
Use for	Catalog filtering, search, grouping	Hypervisor hints, operational metadata
Filtering	`openstack image list --tag <tag>`	`openstack image list --property key=value`
Hypervisor-aware	Never	Some keys are (`hw_`, `os_`)

Remove Properties

Remove a specific property

openstack image unset \
  --property hw_tpm_model \
  ubuntu-24.04-lts

Next Steps

Image Formats

Choose the right disk format to match your property configuration.

Upload an Image

Upload images and set properties at upload time using CLI flags.

Image Admin Guide — Metadata

Define structured metadata namespaces for consistent property schemas.

Troubleshooting

Resolve launch failures caused by incorrect image property values.

Core Services

Other Services

Overview

Essential Properties Reference

Set Properties

Open image details

Edit basic properties

Manage custom metadata (admin only)

Authenticate

Set multiple properties at once

Verify properties were applied

Hardware Configuration Examples

Image Metadata & Tags

Arbitrary Properties

Image Tags

Edit the image

Add tags

Save

Tags vs Properties

Remove Properties

Next Steps

Image Formats

Upload an Image

Image Admin Guide — Metadata

Troubleshooting

​Overview

​Essential Properties Reference

​Set Properties

Open image details

Edit basic properties

Manage custom metadata (admin only)

Authenticate

Set multiple properties at once

Verify properties were applied

​Hardware Configuration Examples

​Image Metadata & Tags

​Arbitrary Properties

​Image Tags

Edit the image

Add tags

Save

​Tags vs Properties

​Remove Properties

​Next Steps

Image Formats

Upload an Image

Image Admin Guide — Metadata

Troubleshooting

Overview

Essential Properties Reference

Set Properties

Hardware Configuration Examples

Image Metadata & Tags

Arbitrary Properties

Image Tags

Tags vs Properties

Remove Properties

Next Steps