Image Library & Images

An Image is a file that captures the state of a virtual machine at a specific point in time. It contains the operating system, applications, data, and virtual machine configurations.

An Image Library stores one or more virtual machine images for your Private Cloud Director environment. You can provision new virtual machines using images from the image library.

Prerequisites

Ensure that the Image Library prerequisites are met before proceeding further.

Supported Backends

The Private Cloud Director image library service supports the following backends:

• File – For local file-based image storage.

• Private Cloud Director block storage service – For block storage-based image storage.

Configuration

Every cluster needs to have at least one 'image library', which will host the cluster copy of virtual machine source images from which new VMs can be provisioned. You can do this by assigning the image library role to one or more of your hosts. These hosts will then store the virtual machine image content on local / block / file storage available to them and will serve as Image Library endpoint when serving images to hosts where VMs are getting provisioned.

Typically, you will assign the image library role to at least two host in your virtualized cluster for high availability.

Hosts with Image Library role enabled need to have adequate storage capacity to store your catalog of VM images; and will often experience significant network I/O when a VM image is being served for the first time to a hypervisor in your cluster during VM provisioning. Hypervisors maintain a local cache of images to avoid repeated I/O for the same image.

Import Images into Image Library

Before you can start creating VMs, you need to first populate your image library with virtual machine images. You can import images either using Private Cloud Director UI or the pcdctl CLI. To import images into the image library, navigate to 'Images' menu in the UI left side navigation and choose your image import method - CLI or via UI.

Importing Images via the CLI

To import images via the CLI, you need to first download the OpenStack CLI on your local machine that has access to the images. Follow the steps outlined in the UI to setup the OpenStack python client on your machine.

Step 1 - Download the PCDCTL CLI Client

Follow the instructions here to download and install pcdctl CLI client on the machine that you will use to upload the images. Make sure that the machine has network access to your hypervisor hosts that are configured with the image library role.

Step 2 - Export the Environment Variables

You need to set a number of environment variables to configure the CLI to work with your Private Cloud Director account. To help you with this process, the Private Cloud Director UI pre-populate these variables with appropriate values based on the current Private Cloud Director domain, region and tenant you are logged into.

Simply copy the variables from the UI by following these steps.

1. Log in to your Private Cloud Director account.

2. Navigate to Images in the left side menu, then click the Import With CLI button.

3. Copy the environment variables provided in the UI.

4. Create a new .sh file, (eg openstack-rc.sh) and paste the copied variables into the file.

5. Replace the value of OS_PASSWORD with your Private Cloud Director account password.

6. Run the command to set the required environment variables.

Bash

source <NAME_OF_YOUR_RC_FILE>.sh

Step 3 - Upload the Image

Now that your CLI is configured, run the pcdctl command to upload your VM image to the image library.

Bash

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

Following command uploads a qcow2 image to the image library and makes it public.

Bash

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

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

• Ensure that the OS_INTERFACE environment variable is set to admin.

Info

The OS_INTERFACE environment variable must be set to admin for the image upload to work.

And thats it. Now you are ready to use this image to create a new virtual machine.

Image Library High Availability

You can create a highly available setup of the image library by assigning the image library role to multiple hosts in your virtualized cluster. For production environments, creating a highly available setup of image library is recommended. Read Image Library High Availability to learn more.

Image Library Admin Endpoint

The image library admin endpoint is the IP address of the image library service host that can be used to upload images. This endpoint is configured automatically when you assign image library role to a host.

Image Visibility

An image in the image library can be private, public or shared.

Private: Available only to the tenant that created the image.

Public: Available to every tenant in your domain. Can be made public when uploaded via the Private Cloud Director UI or by using the "--public" option when uploading using the CLI.

Shared: Available to a specific subset of tenants in your domain. This is the default option when uploading an image via CLI.

Images vs VM Snapshots

You can use the Image Library to store Images as well as Virtual Machine Snapshots.

Read Virtual Machine Snapshot for more info on VM snapshots, VM snapshot types and associated behavior.

Image Formats

Private Cloud Director supports following image formats:

Format Type	Description
raw	This is an unstructured disk image format. The raw image format is the simplest one, and is natively supported by KVM hypervisor. You can think of a raw image as being the bit-equivalent of a block device file, created as if somebody had copied, say, /dev/sda to a file using the dd command.
qcow2	The QCOW2 (QEMU copy-on-write version 2) format is commonly used with the KVM hypervisor. It uses a sparse representation, so the image size is smaller than a raw format file of the same virtual disk. It can expand dynamically and supports Copy on Write. The files using this format are usually available with .img extension,
iso	The ISO format is a disk image formatted with the read-only ISO 9660 (also known as ECMA-119) filesystem commonly used for CDs and DVDs.

Debugging Image Library Service Issues

If your Private Cloud Director Service Health dashboard is showing that the Image Library Service is unhealthy, this may be because:

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

2. The image library service is not responding on one or more hosts that are configured with Image Library role.

Refer to the Log Files section to locate the image library log files on the hosts to debug the issue.

Log Files

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