Image Manager

The OpenStack Image Manager is a tool for managing all machine images on an OpenStack environment.

There are two ways to use the OpenStack Image Manager:

Via the OSISM CLI with osism manage images. This is the preferred way for operators of an OSISM environment. No separate installation is required.
Standalone by installing the openstack-image-manager package directly. This is useful when the tool is used independent of OSISM.

Regardless of the path, the requirements on the OpenStack environment and the image definitions are the same.

Requirements

info

This information is only relevant for the operator of an OpenStack environment. You can skip this section if you want to use OpenStack Image Manager as a normal user and you are not an operator of an OpenStack environment.

The OpenStack Image Service (Glance) is required to upload and discover data assets that are used by other services.

Since this script stores many images in a single project, the Glance quota must be set accordingly high or to unlimited.

[DEFAULT]
user_storage_quota = 1TB

With most storage backends it makes sense to convert the imported images directly to RAW. So it is required for using Ceph and it's features too. Recited from the Ceph documentation QEMU and block devices and Block devices and OpenStack.

info

The raw data format is really the only sensible format option to use with RBD. Technically, you could use other QEMU-supported formats (such as qcow2 or vmdk), but doing so would add additional overhead, and would also render the volume unsafe for virtual machine live migration when caching (see below) is enabled.

Important Ceph doesn't support QCOW2 for hosting a virtual machine disk. Thus if you want to boot virtual machines in Ceph (ephemeral backend or boot from volume), the Glance image format must be RAW.

See the OpenStack Glance documentation for more details.

This requires the following parameter for the image import workflow.

[taskflow_executor]
conversion_format = raw

[image_import_opts]
image_import_plugins = ['image_decompression', 'image_conversion']

[image_conversion]
output_format = raw

Usage via the OSISM CLI

The OpenStack Image Manager can be used via the OSISM CLI. This is the preferred way to use it. No installation is then required. It is used via osism manage images.

The image definitions are read from /etc/images on the manager by default. This directory is provided by OSISM and contains the image definitions maintained in the osism/openstack-image-manager repository. To manage your own image definitions, point the command at a different directory or a single image file with the --filter and --images options.

By default the cloud profile with the name admin is used. The credentials of this profile must be allowed to create, update and delete images. Another profile can be selected with the --cloud parameter.

$ osism manage images --help

usage: osism manage images [-h] [--no-wait] [--dry-run] [--hide] [--delete]
                           [--latest] [--cloud CLOUD] [--filter FILTER]
                           [--images IMAGES]

options:
  -h, --help       show this help message and exit
  --no-wait        Do not wait until image management has been completed
  --dry-run        Do not perform any changes
  --hide           Hide images that should be deleted
  --delete         Delete images that should be deleted
  --latest         Only import the latest version for images of type multi
  --cloud CLOUD    Cloud name in clouds.yaml (default: admin)
  --filter FILTER  Filter images with a regex on their name
  --images IMAGES  Path to the directory containing all image files or path to
                   single image file (default: /etc/images)

To check which images from /etc/images would be managed by default, you can run:

osism manage images --dry-run

To manage all of those images, run:

osism manage images

To restrict the run to specific images, filter them with a regular expression on their name. For example, to only manage the Ubuntu 24.04 image:

osism manage images --filter 'Ubuntu 24.04$'

If you omit the $ at the end of the regex here, the filter would match Ubuntu 24.04, as well as Ubuntu 24.04 Minimal.

Before making any changes it is a good idea to check what the OpenStack Image Manager would do with --dry-run. No changes are applied in this mode:

osism manage images --dry-run --filter 'Ubuntu 24.04'

Images that are no longer required are hidden by default (their visibility is changed so that they are no longer offered to users). To actually delete images that should be removed, use the --delete parameter. Use this with care:

osism manage images --delete --filter 'Ubuntu 24.04'

For images of type multi (see Image with regular rebuilds), only the latest version can be imported with the --latest parameter instead of all versions listed in the definition:

osism manage images --latest --filter 'Ubuntu 24.04'

By default the command waits until the image management has been completed and streams the output. Use --no-wait to start the task in the background without waiting for it to finish.

Standalone usage

For use independently of OSISM, the OpenStack Image Manager can be installed and run directly. The following steps will upload a private image to your OpenStack environment with the help of the OpenStack Image Manager.

Install the openstack-image-manager package with pip.
```
pip3 install openstack-image-manager
```
The installation can also be done via pipenv.

A Pipfile file is created with this content. The latest version of openstack-image-manager is used.
```
[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]
openstack-image-manager = "==0.20250413.0"

[dev-packages]

[requires]
python_version = "3.10"
```
The dependencies are then installed and the shell is prepared for use:
```
pipenv install
pipenv shell
```

Create a image definition in the file getting-started.yml in the local directory images.

---
images:
  - name: MyCirros
    enable: true
    format: qcow2
    login: cirros
    password: gocubsgo
    min_disk: 1
    min_ram: 32
    status: active
    visibility: private
    multi: false
    meta:
      architecture: x86_64
      hw_disk_bus: scsi
      hw_rng_model: virtio
      hw_scsi_model: virtio-scsi
      hw_watchdog_action: reset
      hypervisor_type: qemu
      os_distro: cirros
      os_purpose: minimal
      replace_frequency: never
      uuid_validity: none
      provided_until: none
    tags: []
    versions:
      - version: '0.6.2'
        url: https://github.com/cirros-dev/cirros/releases/download/0.6.2/cirros-0.6.2-x86_64-disk.img
        checksum: "sha256:07e44a73e54c94d988028515403c1ed762055e01b83a767edf3c2b387f78ce00"
        build_date: 2023-05-30
      - version: '0.6.3'
        url: https://github.com/cirros-dev/cirros/releases/download/0.6.3/cirros-0.6.3-x86_64-disk.img
        checksum: "sha256:7d6355852aeb6dbcd191bcda7cd74f1536cfe5cbf8a10495a7283a8396e4b75b"
        build_date: 2024-09-26

Run the OpenStack Image Manager. It is assumed that a profile with the name openstack exists in the clouds.yaml.
```
openstack-image-manager --cloud openstack --filter ".*Cirr.*" --images images/
```

Image definitions

The configuration consists of different parameter settings, such as values for minimum RAM or the visibility of the image. Have a look at the examples below for all parameters. After a change to the configuration, validate it with tox -- --dry-run.

SCS image standard

The value of login is stored as image_original_user in the metadata of an image.
If image_description is not set as meta information, image_description is set to the name of the image.
The value of build_date of a specific version of an image is stored as image_build_date in the metadata of an image.
The value of url of a specific version of an image is stored as image_source in the metadata of an image.

Image with regular rebuilds

This type of image definition is used for images that are rebuilt at regular intervals. For example, this is the case for the daily builds of the Ubuntu images.

The attribute multi: true is set.

With this type of image definition, the version of the distribution (or product, whatever is contained in the image) used is already in the name of the image definition. The version properties from the definition's versions list are appended only to older iterations of the image as timestamp suffixes in parentheses upon each rotation (except for the latest entry).

images:
  - name: Ubuntu 24.04
    format: qcow2
    login: ubuntu
    min_disk: 8
    min_ram: 512
    status: active
    visibility: public
    multi: true
    meta:
      architecture: x86_64
      hw_disk_bus: scsi
      hw_scsi_model: virtio-scsi
      hw_watchdog_action: reset
      os_distro: ubuntu
      os_purpose: generic
      os_version: '24.04'
    tags: []
    versions:
      - version: '20240416'
        url: https://cloud-images.ubuntu.com/noble/20240416/noble-server-cloudimg-amd64.img
      - version: '20240422'
        url: https://cloud-images.ubuntu.com/noble/20240422/noble-server-cloudimg-amd64.img

This configuration creates the following images:

Ubuntu 24.04 (20240416)
Ubuntu 24.04

If a newer build is added, the following rotation takes place:

Ubuntu 24.04 (20240416) does not change
Ubuntu 24.04 becomes Ubuntu 24.04 (20240422)
the new image becomes Ubuntu 24.04

By default the last three images will be visible. When a fourth image is added, the visibility of the last image in the list is changed to community and the image can be deleted in the future.

Image without regular rebuild

This type of image definition is used for images that are not rebuilt. For example, this is the case for the flatcar images. For each release of Flatcar there is exactly one image which will not be rebuilt in the future.

The attribute multi: false is set.

With this type of image definition, the version of the distribution (or product, whatever is contained in the image) used is not in the name of the image definition. Instead, the version properties from the image definition's versions list are appended as static version suffixes to the images' names.

images:
  - name: RancherOS
    format: qcow2
    login: rancher
    min_disk: 8
    min_ram: 2048
    status: active
    visibility: public
    multi: false
    meta:
      architecture: x86_64
      hw_disk_bus: scsi
      hw_scsi_model: virtio-scsi
      hw_watchdog_action: reset
      os_purpose: k8snode
    tags: []
    versions:
      - version: '1.3.0'
        url: https://github.com/rancher/os/releases/download/v1.3.0/rancheros-openstack.img
      - version: '1.4.0'
        url: https://github.com/rancher/os/releases/download/v1.4.0/rancheros-openstack.img
      - version: '1.4.1'
        url: https://github.com/rancher/os/releases/download/v1.4.1/rancheros-openstack.img

This configuration creates the following images:

RancherOS 1.3.0
RancherOS 1.4.0
RancherOS 1.4.1

If a new version is added, no rotation takes place. The new version is added as RancherOS x.y.z. Here also the visibility of older images is not changed.

Other properties

Image properties

Removal of properties is not yet possible
URL, name and format can not be changed
Any keys can be added to meta, these will be added to the image
Existing keys in meta can be changed, the same applies to min_disk and min_ram

Image tags

image status

deactivation: change status to deactivated
reactivation: change status to active

Image visibility

A full documentation about the visibility of images can be found in the Image visibility section in the OpenStack Image Service API Documentation.

public: set visibility to public
community: set visibility to community
shared: set visibility to shared
private: set visibility to private

Requirements​

Usage via the OSISM CLI​

Standalone usage​

Image definitions​

SCS image standard​

Image with regular rebuilds​

Image without regular rebuild​

Other properties​

Image properties​

Image tags​

image status​

Image visibility​