# 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](/private-cloud-director/2025.8/getting-started/pre-requisites.md#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](/private-cloud-director/2025.8/reference/pcdctl-command-line.md#installation) 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. {% tabs %} {% tab title="Bash" %} ```bash source .sh ``` {% endtab %} {% endtabs %} ### Step 3 - Upload the Image Now that your CLI is configured, run the pcdctl command to upload your VM image to the image library. {% tabs %} {% tab title="Bash" %} ```bash pcdctl image create --insecure --container-format bare --disk-format qcow2 [--public | --private] [--protected | --unprotected] [--property ] --file ``` {% endtab %} {% endtabs %} Following command uploads a `qcow2` image to the image library and makes it `public`. {% tabs %} {% tab title="Bash" %} ```bash pcdctl image create --insecure --container-format bare --disk-format qcow2 --public --file ``` {% endtab %} {% endtabs %} * 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`. {% hint style="info" %} **Info** The `OS_INTERFACE` environment variable must be set to `admin` for the image upload to work. {% endhint %} 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](/private-cloud-director/2025.8/virtualized-clusters/image-library---images/image-library-high-availability.md) 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](https://github.com/platform9/pcd-docs-gitbook/blob/main/private-cloud-director/2025.8/deploying-workloads/virtual-machine-snapshot.md) 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](http://en.wikibooks.org/wiki/QEMU/Images) (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](http://www.ecma-international.org/publications/standards/Ecma-119.htm) 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](#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` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.platform9.com/private-cloud-director/2025.8/virtualized-clusters/image-library---images.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.