> For the complete documentation index, see [llms.txt](https://docs.platform9.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform9.com/private-cloud-director/images-and-image-library/image-library-multiple-storage-backends.md).

# Image Library with Multiple Storage Backends

The <code class="expression">space.vars.product\_name</code> Image Library Service can use more than one storage backend within a region. Each storage backend is a store that holds image data, and you designate one backend as the default. Configuring multiple storage backends lets you keep images on more than one backend, such as a shared filesystem together with one or more block storage volume types.

## How It Works

* You configure the storage backends, and the default backend, as part of the cluster blueprint image library configuration.
* Each storage backend is either a shared filesystem store or a block storage store that is identified by its volume type name.
* When you upload an image, the Image Library Service writes it to every configured storage backend, so the image is available from all of them.
* The Compute Service and the Persistent Storage Service fetch an image from a storage backend where the image is present.

## Supported Storage Backends

| Storage backend type                 | Support for multiple backends                                                                             |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| Shared filesystem (for example, NFS) | Only one shared filesystem store is supported.                                                            |
| Block storage volume type            | Multiple block storage backends are supported. Each backend is identified by a distinct volume type name. |

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

Multiple storage backends require shared storage. You cannot use multiple storage backends with a local (non-shared) filesystem.
{% endhint %}

For details on configuring a block storage backend and the shared storage requirement, see [Image Library High Availability](/private-cloud-director/images-and-image-library/image-library-high-availability.md).

## Configure Multiple Storage Backends

You configure the storage backends, and the default backend, in the cluster blueprint image library configuration. Provide each block storage backend by its volume type name, and designate one of the configured backends as the default backend.

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

You can edit the storage backend configuration only when the Image Library role is deauthorized from the hosts. To add or change storage backends, deauthorize the Image Library role from the hosts, edit the configuration, and then re-authorize the role.
{% endhint %}

## Upload Images

When multiple storage backends are configured, upload images using the `pcdctl` CLI. An image is written to all configured storage backends so that it is available from each one.

### Prerequisites

Install the `pcdctl` CLI if it is not already installed:

```bash
bash <(curl -s https://pcdctl.s3.us-west-2.amazonaws.com/pcdctl-setup)
```

For credential setup, see the [Overview](/private-cloud-director/images-and-image-library/image-library---images.md).

### Upload an image to all storage backends

Run the following command to upload an image and copy it to every configured storage backend:

```bash
pcdctl image upload --insecure --name <image-name> --file <image-file-path> --disk-format qcow2 [--public | --private] --all-stores [-- --property os_type=<os-type> --protected]
```

The `--all-stores` option copies the image to every configured storage backend after upload.

## Manage Storage Backends from the UI

In addition to the cluster blueprint and the `pcdctl` CLI, you can configure storage backends, upload images, and monitor image replication from the <code class="expression">space.vars.product\_name</code> UI.

### Configure Storage Backends in the Cluster Blueprint

In the cluster blueprint, open **Cluster Defaults** and go to the **Image Library** configuration. Each storage backend appears as a store row.

1. For each store, select a **Location**: **Local File System**, **Shared File System**, or **Volume Type**.
2. Provide the value for that location: a **Volume Type** for a block storage backend, or a **File System Path** for a filesystem backend.
3. Select **Default** on the store that receives the initial upload.
4. To add another backend, select **Add store**. To remove a backend, select the remove icon on that store row.
5. Save the blueprint.

The store editor enforces the requirements described under Constraints and Limitations. In particular, each volume type can be used by only one store, at most one filesystem store (shared or local) can be configured, and a **Local File System** store can only be used as a single store. When a local filesystem store is selected, you cannot add more stores.

{% hint style="info" %}
**Editing existing stores**

Existing stores cannot be changed or removed while an Image Library role is assigned or images already exist. You can still add new stores at any time.
{% endhint %}

When you save a blueprint that adds a new store and images already exist, the UI prompts you to copy the existing images to all stores. See [Copy Existing Images to All Storage Backends](#copy-existing-images-to-all-storage-backends) below.

### Monitor Image Replication

The **Images** list includes a **Stores** column that shows where each image is stored. Each configured store appears with a colored status indicator:

* **Green:** the image is stored in that store.
* **Yellow:** the image is currently being copied to that store.
* **Red:** the copy to that store failed.

The column updates automatically while a copy is in progress, so you can watch an image populate additional stores without refreshing the page. If a copy fails, a notification reports the image and the stores it could not reach so that you can retry.

### Upload Images from the UI

When you upload an image file from the UI on a site with more than one storage backend, the image is uploaded to the default backend and then copied automatically to all configured backends. You do not select stores and you do not run a separate copy step. If the copy cannot be started, the UI keeps the uploaded image and shows a warning so that you can retry the copy later.

The UI also provides the `pcdctl` command for uploading from the command line. When more than one storage backend is configured, the command dialog shows both a single-store command and a multi-store command that uses `--all-stores`. For the interactive upload steps, see [Upload an Image Using the UI](/private-cloud-director/images-and-image-library/image-upload-via-ui.md).

### Copy Existing Images to All Storage Backends

You can replicate images that are not yet present in every store without re-uploading them.

1. In the **Images** list, select one or more images that are missing from a store or that failed to copy.
2. Select **Copy to all stores**.
3. Confirm the copy. The copies run in the background, and the **Stores** column updates as each copy completes.

The **Copy to all stores** action is available only when more than one storage backend is configured and at least one selected image is missing from a store or previously failed to copy. If a copy cannot be started for some images, the UI lists those images so that you can retry them later.

## Image Copy Permissions

Copying an image to additional storage backends is a privileged action. The role you hold in the tenant that owns the image determines whether the **Copy to all stores** action succeeds.

* **Admin:** can copy any image in the tenant to all configured storage backends.
* **Self-Service User:** can copy images that their own tenant owns. Copying an image that another tenant owns and shares into the tenant is not permitted.
* **ReadOnly:** cannot copy images.

{% hint style="warning" %}
Under granular RBAC, copying an image is available to **Platform Admin**, **Service Provider Domain Admin**, and **Customer Domain Admin**.
{% endhint %}

If your role does not permit the copy, the request is rejected and the image remains in the storage backends where it is already present.

## Constraints and Limitations

* **Multiple storage backends require shared storage.** You cannot use multiple storage backends with a local filesystem store.
* **Only one shared filesystem store is supported.** You can configure multiple block storage backends, but at most one shared filesystem backend.
* **The default backend must be one of the configured backends.**
* **Editing requires the Image Library role to be deauthorized.** To add or change storage backends, deauthorize the Image Library role from the hosts first, and then re-authorize the role after the change.
* **An image is uploaded to all configured backends.** Image data is written to every configured storage backend, not to a single backend.
* **Storage backends apply within a single region.** Image data is not replicated across regions.

## Related Topics

* [Overview](/private-cloud-director/images-and-image-library/image-library---images.md)
* [Image Library High Availability](/private-cloud-director/images-and-image-library/image-library-high-availability.md)
* [Restrict the Image Library Service to a Specific Cluster](/private-cloud-director/images-and-image-library/restrict-image-library-to-cluster.md)
* [RBAC Roles and Permissions](/private-cloud-director/identity-and-multi-tenancy/rbac-roles-and-permissions.md): what each role can do with images


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.platform9.com/private-cloud-director/images-and-image-library/image-library-multiple-storage-backends.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.