Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Managing images, image properties, and image formats

Manage images and the properties and formats of images that you upload, import, or store in the Red Hat OpenStack Platform (RHOSP) Image service (glance).

3.1. Uploading images to the Image service

You can upload an image to the Red Hat OpenStack Platform (RHOSP) Image service (glance) by using the glance image-create command with the --property option.

For a list of glance image-create command options, see Image service command options. For a list of property keys, see Image configuration parameters.

Procedure

  • Use the glance image-create command with the property option to upload an image.

    For example: 

    $ glance image-create --name <name> \
    --is-public true --disk-format <qcow2> \
    --container-format <bare> \
    --file </path/to/image> \
    --property <os_version>=<11.10>
    • Replace <name> with a descriptive name for your image.
    • Replace <disk-format> with one of the following disk formats: None, ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, iso, ploop.
    • Replace <container-format> with one of the following container formats: None, ami, ari, aki, bare, ovf, ova, docker.
    • Replace </path/to/image> with the file path to your image file.
    • Replace <os_version> and <11.10> with the key-value pair of the property you want to associate to your image. You can use the --property option multiple times with different key-value pairs you want to associate to your image.

3.2. Image service image import methods

You can import images to the Red Hat OpenStack Platform (RHOSP) Image service (glance) by using the following methods:

  • Use the web-download (default) method to import images from a URI.
  • Use the glance-direct method to import images from a local file system.
  • Use the copy-image method to copy an existing image to other Image service back ends that are in your deployment. Use this import method only if multiple Image service back ends are enabled in your deployment.

The web-download method is enabled by default, but the cloud administrator configures other import methods. You can run the glance import-info command to list available import options.

3.2.1. Importing an image from a remote URI

You can use the web-download image import method to copy an image from a remote URI to the Red Hat OpenStack Platform (RHOSP) Image service (glance).

The Image service web-download method uses a two-stage process to perform the import:

  1. The web-download method creates an image record.
  2. The web-download method retrieves the image from the specified URI.

The URI is subject to optional denylist and allowlist filtering.

The image property injection plugin may inject metadata properties to the image. These injected properties determine which Compute nodes the image instances are launched on.

Procedure

  • Create an image and specify the URI of the image to import: 

    $ glance image-create-via-import \
    --container-format <container-format> \
    --disk-format <disk-format> \
    --name <name> \
    --import-method web-download \
    --uri <uri>
    • Replace <container-format> with one of the following container formats: None, ami, ari, aki, bare, ovf, ova, docker
    • Replace <disk-format> with one of the following disk formats: None, ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, iso, ploop.
    • Replace <name> with a descriptive name for your image.
    • Replace <uri> with the URI of your image.

Verification

  • Check the availability of the image: 

    $ glance image-show <image-id>
    • Replace <image-id> with the image ID you provided during image creation.

3.2.2. Importing an image from a local volume

The glance-direct image import method creates an image record, which generates an image ID. When you upload an image to the Image service (glance) from a local volume, the image is stored in a staging area and becomes active when it passes any configured checks.

Note

The glance-direct method requires a shared staging area when used in a highly available (HA) configuration. If you upload images by using the glance-direct import method, the upload can fail in a HA environment if a shared staging area is not present. In a HA active-active environment, API calls are distributed to the Image service controllers. The download API call can be sent to a different controller than the API call to upload the image.

The glance-direct image import method uses three different calls to import an image:

  • glance image-create
  • glance image-stage
  • glance image-import

You can use the glance image-create-via-import command to perform all three of the glance-direct calls in one command.

Procedure

  1. Source your credentials file.

  2. Use the glance image-create-via-import command to import a local image: 

    $ glance image-create-via-import \
    --container-format <container-format> \
    --disk-format <disk-format> \
    --name <name> \
    --file </path/to/image>
    • Replace <container-format> with one of the following container formats: None, ami, ari, aki, bare, ovf, ova, docker
    • Replace <disk-format> with one of the following disk formats: None, ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, iso, ploop.
    • Replace <name> with a descriptive name for your image.

    • Replace </path/to/image> with the file path to your image file.

      When the image moves from the staging area to the back-end storage location, the image is listed. However, it might take some time for the image to become active.

Verification

  • Check the availability of the image: 

    $ glance image-show <image-id>
    • Replace <image-id> with the image ID you provided during image creation.

3.3. Updating image properties

Update the properties of images that you have stored in the Red Hat OpenStack Platform (RHOSP) Image service (glance).

Procedure

3.4. Enabling image conversion

You can upload a QCOW2 image to the Image service (glance) by enabling the GlanceImageImportPlugins parameter. You can then convert the QCOW2 image to RAW format.

Note

Image conversion is automatically enabled when you use Red Hat Ceph Storage RADOS Block Device (RBD) to store images and boot Nova instances.

To enable image conversion, create an environment file that contains the following parameter value. Include the new environment file with the -e option in the openstack overcloud deploy command: 

parameter_defaults:
  GlanceImageImportPlugins:'image_conversion'

Use the Image service command-line client for image management.

3.4.1. Converting an image to RAW format

Red Hat Ceph Storage can store, but does not support using, QCOW2 images to host virtual machine (VM) disks.

When you upload a QCOW2 image and create a VM from it, the compute node downloads the image, converts the image to RAW, and uploads it back into Ceph, which can then use it. This process affects the time it takes to create VMs, especially during parallel VM creation.

For example, when you create multiple VMs simultaneously, uploading the converted image to the Ceph cluster might impact already running workloads. The upload process can starve those workloads of IOPS and impede storage responsiveness.

To boot VMs in Ceph more efficiently (ephemeral back end or boot from volume), the glance image format must be RAW.

Procedure

  1. Converting an image to RAW might yield an image that is larger in size than the original QCOW2 image file. Run the following command before the conversion to determine the final RAW image size: 

    $ qemu-img info <image>.qcow2

  2. Convert an image from QCOW2 to RAW format: 

    $ qemu-img convert -p -f qcow2 -O raw <original qcow2 image>.qcow2 <new raw image>.raw

3.4.2. Configuring disk formats with the GlanceDiskFormats parameter

You can the configure the Image service (glance) to enable or reject disk formats by using the GlanceDiskFormats parameter.

Procedure

  1. Log in to the undercloud host as the stack user.

  2. Source the undercloud credentials file: 

    $ source ~/stackrc

  3. Include the GlanceDiskFormats parameter in an environment file, for example, glance_disk_formats.yaml: 

    parameter_defaults:
  GlanceDiskFormats:
    - <disk_format>

    • For example, use the following configuration to enable only RAW and ISO disk formats: 

      parameter_defaults:
  GlanceDiskFormats:
  - raw
  - iso

    • Use the following example configuration to reject QCOW2 disk images: 

      parameter_defaults:
  GlanceDiskFormats:
  - raw
  - iso
  - aki
  - ari
  - ami

  4. Include the environment file that contains your new configuration in the openstack overcloud deploy command with any other environment files that are relevant to your environment: 

    $ openstack overcloud deploy --templates \
  -e <overcloud_environment_files> \
  -e <new_environment_file> \
  …
    • Replace <overcloud_environment_files> with the list of environment files that are part of your deployment.
    • Replace <new_environment_file> with the environment file that contains your new configuration.

For more information about the disk formats available in RHOSP, see Image configuration parameters.

3.4.3. Storing an image in RAW format

With the GlanceImageImportPlugins parameter enabled, run the following command to store a previously created image in RAW format: 

$ glance image-create-via-import \
    --disk-format qcow2 \
    --container-format bare \
    --name <name> \
    --visibility public \
    --import-method web-download \
    --uri <http://server/image.qcow2>
  • Replace <name> with the name of the image; this is the name that will appear in glance image-list.
  • Replace <http://server/image.qcow2> with the location and file name of the QCOW2 image.
Note

This command example creates the image record and imports it by using the web-download method. The glance-api downloads the image from the --uri location during the import process. If web-download is not available, glanceclient cannot automatically download the image data. Run the glance import-info command to list the available image import methods.

3.5. Hiding or unhiding images

You can hide public images from normal listings presented to users. For example, you can hide obsolete CentOS 7 images and show only the latest version to simplify the user experience. Users can discover and use hidden images.

To create a hidden image, add the --hidden argument to the glance image-create command.

Procedure

  • Hide an image: 

    $ glance image-update <image_id> --hidden 'true'

  • Unhide an image: 

    $ glance image-update <image_id> --hidden 'false'

  • List hidden images: 

    $ glance image-list --hidden 'true'

3.6. Deleting images from the Image service

Use the glance image-delete command to delete one or more images that you do not need to store in the Image service (glance).

Procedure

  • Delete one or more images: 

    $ glance image-delete <image-id> [<image-id> ...]

    • Replace <image-id> with the ID of the image you want to delete.

      Warning

      The glance image-delete command permanently deletes the image and all copies of the image, as well as the image instance and metadata.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.