# 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 <code class="expression">space.vars.product\_name</code> environment. You can provision new virtual machines using images from the image library.

## Prerequisites

Ensure that the Image Library [prerequisites](https://docs.platform9.com/private-cloud-director/2025.2/getting-started/pre-requisites#image-library-prerequisites) are met before proceeding further..

{% hint style="info" %}
**Info**

The current implementation of the <code class="expression">space.vars.product\_name</code> Image service supports deploying the Image Library role on up to two hosts per virtualized cluster. Full multi-node support is coming soon.
{% endhint %}

### Supported Backends

The <code class="expression">space.vars.product\_name</code> Image Library service supports the following backends:

* File – For local file-based image storage.
* <code class="expression">space.vars.product\_name</code> Block storage service (cinder) – 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 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 designate 1 host in your cluster as the Image Library. For larger clusters, or environments with high VM provisioning rates, you can designate 2 or more hosts as the Image Library.

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 VM image is being served for the first time to a Hypervisor in your cluster (as part of 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 <code class="expression">space.vars.product\_name</code> UI or CLI. To import images into the Image Library, navigate to 'Images' in the Navigation Pane and choose your import method - CLI or via UI.

<figure><img src="https://475788898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1DPJ7Uj93hjTsfup8x4F%2Fuploads%2Fgit-blob-b4a1385baa52af35409dbc36318c302d771db6ab%2Fm8j87sz7autck6bzwsspiug57bav5tbgecq12f44zk92rig4xseueu0vt7yfyfuy.png?alt=media" alt=""><figcaption></figcaption></figure>

Note that importing **images larger than 1GB via the UI may cause timeouts or failures**. To make the import process more reliable, use the CLI for images greater than 1 GB in size.

{% hint style="warning" %}
**Important**

Importing images larger than 1GB via the UI may cause timeouts or failures. To make the import process more reliable, use the CLI for images greater than 1 GB in size.
{% endhint %}

### 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 OpenStack CLI Client

Download the OpenStack CLI client on your local machine by running the following command:

{% tabs %}
{% tab title="Bash" %}

```bash
apt install python3-openstackclient -y
```

{% endtab %}
{% endtabs %}

#### Step 2 - Export the Environment Variables

You need to set a number of environment variables to configure the OpenStack CLI to work with your <code class="expression">space.vars.product\_name</code> account. To help you with this process, the <code class="expression">space.vars.product\_name</code> **UI pre-populate these variables with appropriate values** based on the current <code class="expression">space.vars.product\_name</code> domain, region and tenant you are logged into.

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

1. Log in to your <code class="expression">space.vars.product\_name</code> account.
2. Navigate to **Images**, click the **Import With CLI** button, and copy the variables from Step 1, as shown in the image below.
3. Paste the copied variables into your environment file.
4. Replace the value of `OS_PASSWORD` with your account password.
5. Run the command to set the required environment variables.

{% tabs %}
{% tab title="Bash" %}

```bash
source <name-of-your-rc-file>.sh
```

{% endtab %}
{% endtabs %}

<figure><img src="https://475788898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1DPJ7Uj93hjTsfup8x4F%2Fuploads%2Fgit-blob-f758b6a32b2ab58edb1fed19ed370815c91cf5fd%2Fnivo99h56faj6vvikrjdjr5gd176o2y388gmelxsobrnnf4kt0qspisjsp2e6s7n.png?alt=media" alt=""><figcaption></figcaption></figure>

### Step 3 - Upload the Image

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

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

{% tabs %}
{% tab title="Bash" %}

```bash
openstack image create --insecure --container-format bare --disk-format qcow2 --public --file <path-to-your-image> <image-name>
```

{% endtab %}
{% endtabs %}

* The `--insecure` flag is required because the Glance node uses self-signed certificates.
* Ensure `OS_INTERFACE` env variable is set as `admin`.

And thats it. Now you are ready to use this image to create a new Virtual Machine.

## 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 <code class="expression">space.vars.product\_name</code> 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.

## Image Formats

<code class="expression">space.vars.product\_name</code> supports following image formats:

| **Format Type** | **Description**                                                                                                                                                                                                                                                                                                                                              |   |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - |
| raw             | <p>This is an unstructured disk image format.<br><br>The <code>raw</code> 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, <code>/dev/sda</code> to a file using the <strong>dd</strong> command.</p> |   |
| 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`.                                                 |   |
| 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.                                                                                                                                            |   |

## Log Files

See [Log Files](https://docs.platform9.com/private-cloud-director/2025.2/add-hosts-virtualized-cluster#log-files) for locations of various important log files including image library logs.