Image Library & Images

You can use an image library to store and manage virtual machine images in your Private Cloud Director environment. An image captures the state of a virtual machine, including the operating system, applications, data, and configurations.

Before you provision virtual machines, you must import images into your image library. You can then use these images to create new virtual machines.

Prerequisites

Before configuring an image library, ensure that you meet the Image Library Prerequisites.

Supported Backends

The image library service supports the following storage backends:

  • File – Local file-based image storage.

  • Block storage – Private Cloud Director block storage service for image storage.

Configure an Image Library

Each cluster requires at least one image library to host virtual machine images. Configure an image library by assigning the image library role to one or more hosts in your cluster.

Hosts with the image library role store virtual machine images on local, block, or file storage. These hosts serve as the image library endpoint when providing images to hosts during VM provisioning.

For high availability in production environments, assign the image library role to at least two hosts in your virtualized cluster.

Storage capacity considerations

Hosts with the Image Library role must have sufficient storage capacity for their VM image catalog. These hosts experience significant network I/O when serving an image for the first time during VM provisioning. After the first provision, hypervisors maintain a local cache of images to reduce I/O.

Import Images

Before you create VMs, import images into your image library. You can import images using the Private Cloud Director UI or the pcdctl CLI.

The following steps show you how to import images using the CLI method.

Step 1: Download and install the pcdctl CLI client

Download the pcdctl CLI client on a machine that has network access to your hypervisor hosts and your image files.

To download and install pcdctl

For detailed installation instructions, see Installation

Step 2: Configure authentication with environment variables

Configure the CLI to authenticate with your Private Cloud Director account by setting the required environment variables. The Private Cloud Director UI provides pre-populated environment variables based on your current domain, region, and tenant.

To set environment variables perform the following steps:

  1. Sign in to your Private Cloud Director account and select Images.

  2. Choose Import With CLI.

  3. Copy the environment variables displayed in the UI. The variables are pre-populated with values for your current domain, region, and tenant.

  4. On your local machine, create a new .sh file (for example, openstack-rc.sh) and paste the copied variables.

  5. In the file, replace the value of OS_PASSWORD with your Private Cloud Director account password.

  6. Save the file.

  7. Run the following command to set the environment variables:

source <NAME_OF_YOUR_RC_FILE>.sh

Step 3: Upload your VM image to the Image Library

After you configure authentication, use the pcdctl command to upload your VM image to the image library.

To upload an image, perform the following steps.

  1. Run the following command:

pcdctl image create --insecure --container-format bare --disk-format qcow2 [--public | --private] [--protected | --unprotected] [--property <key=value>] --file <image-file-path> <image-name>

NOTE

The --insecure flag is required because the image library service uses self-signed certificates.

  1. (Optional) To make the image public and available to all tenants, include the --public flag:

pcdctl image create --insecure --container-format bare --disk-format qcow2 --public --file <image-file-path> <image-name>

After you upload an image, you can use it to create virtual machines.

Configure high availability

You can create a highly available image library by assigning the image library role to multiple hosts in your virtualized cluster. For production environments, we recommend configuring high availability for your image library.

For more information, see Image Library High Availability.

Manage the admin endpoint

The image library admin endpoint is the IP address of the image library service host used to upload images. Private Cloud Director automatically configures this endpoint when you assign the image library role to a host.

When you configure high availability with multiple image library hosts, the last host assigned the image library role becomes the admin endpoint.

Change the admin endpoint

In a highly available setup, if the host acting as the admin endpoint becomes unavailable, you must manually assign a different image library host as the admin endpoint. This change is required only for uploading images. VM provisioning continues to use any available image library host in a round-robin fashion.

For instructions to change the admin endpoint, see Image Library High Availability.

Control image visibility

You can control which tenants can access an image by setting its visibility. Images support the following visibility options:

  • Private – Available only within the tenant where the image was created.

  • Public – Available to all tenants in your domain (set using the --public option during CLI upload or in the UI)

  • Shared – Available to specific tenants in your domain (default option for CLI uploads)

Understand images and snapshots

You can use the image library to store both images and virtual machine snapshots.

For more information about VM snapshots, snapshot types, and behavior, see Virtual Machine Snapshot.

Supported image formats

Private Cloud Director supports the following image formats:

Format

Description

raw

An unstructured disk image format natively supported by the KVM hypervisor. A raw image is equivalent to a block device file created using the dd command (for example, copying /dev/sda to a file).

qcow2

QEMU copy-on-write version 2 format, commonly used with the KVM hypervisor. This format utilizes sparse representation, resulting in smaller image sizes compared to raw format files. The format supports dynamic expansion and copy-on-write. Files using this format typically have a .img extension. For more information, see QCOW2.

iso

A disk image formatted with the read-only ISO 9660 (ECMA-119) filesystem, commonly used for CDs and DVDs. For more information, see ISO.

Troubleshoot Image Library issues

If the Service Health dashboard shows that the image library service is unhealthy, the issue may be caused by one of the following:

  • You do not have certificate authorization to access the image library service.

  • The image library service is not responding on one or more hosts configured with the image library role.

To debug the issue, check the log files on the affected hosts.

Log files

The image library service logs are located at:

/var/log/pf9/glance-api.log

PreviousHost AggregateNextGet Images

Last updated

Was this helpful?