Doc: Improve docs for Glance Cinder Store
This patch improves the documentation for Cinder as a backend for Glance by including: 1. Configuration changes with the New location API 2. Details about how the optimizations are performed vs the generic path 3. Pre-conditions for the optimizations to work 4. Recommendations regarding the internal/service project while uploading volume Change-Id: I6f3035178b2b43145b34fbeb14bac22d0b52bc27 Signed-off-by: Rajat Dhasmana <rajatdhasmana@gmail.com>
This commit is contained in:
Rajat Dhasmana
@@ -1,89 +1,104 @@
|
||||
.. _volume_backed_image:
|
||||
|
||||
|
||||
===================
|
||||
Volume-backed image
|
||||
===================
|
||||
==============================
|
||||
Cinder as a backend for Glance
|
||||
==============================
|
||||
|
||||
OpenStack Block Storage can quickly create a volume from an image that refers
|
||||
to a volume storing image data (Image-Volume). Compared to the other stores
|
||||
such as file and swift, creating a volume from a Volume-backed image performs
|
||||
better when the block storage driver supports efficient volume cloning.
|
||||
OpenStack Block Storage (Cinder) provides the ability to be configured
|
||||
as a backend for Glance. This configuration offers various optimizations
|
||||
between Glance Cinder interaction and also allows a common storage strategy
|
||||
where Cinder volumes are used to store Glance images.
|
||||
|
||||
If the image is set to public in the Image service, the volume data can be
|
||||
shared among projects.
|
||||
Configure Cinder backend for Glance
|
||||
===================================
|
||||
|
||||
Configure the Volume-backed image
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
To configure Cinder as a backend for Glance, refer to the detailed guide
|
||||
in the Glance documentation `configuring-the-cinder-storage-backend`_.
|
||||
Note that Glance has deprecated support for single store and recommends
|
||||
configuring multi store deployment.
|
||||
|
||||
Volume-backed image feature requires locations information from the cinder
|
||||
store of the Image service. To enable the Image service to use the cinder
|
||||
store, add ``cinder`` to the ``stores`` option in the ``glance_store`` section
|
||||
of the ``glance-api.conf`` file:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
stores = file, http, swift, cinder
|
||||
|
||||
To expose locations information, set the following options in the ``DEFAULT``
|
||||
section of the ``glance-api.conf`` file:
|
||||
Optimization
|
||||
============
|
||||
|
||||
Cinder requires location information from Glance to be able to perform
|
||||
optimizations in the operations that involve Glance Cinder interaction.
|
||||
Following are the operations that benefit from the optimzations:
|
||||
|
||||
- Create a bootable volume from image
|
||||
- Upload a volume to Image Service
|
||||
|
||||
Starting with the 2025.2 (Flamingo) release, Cinder supports the `New
|
||||
Location APIs`_ which allows Cinder to **Add** and **Get** the location from
|
||||
the Image service without allowing the exploit of OSSN-0090 and OSSN-0065.
|
||||
If you are running a version of Cinder prior to the 2025.2 (Flamingo)
|
||||
release, read through OSSN-0090 and then configure the following parameters
|
||||
in the Glance configuration file to allow Glance to expose the image location
|
||||
that can be consumed by Cinder.
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[DEFAULT]
|
||||
show_image_direct_url = True
|
||||
show_multiple_locations = True
|
||||
|
||||
To enable the Block Storage services to create a new volume by cloning Image-
|
||||
Volume, set the following options in the ``DEFAULT`` section of the
|
||||
``cinder.conf`` file. For example:
|
||||
Creating a bootable volume from image
|
||||
--------------------------------------
|
||||
|
||||
Cinder provides an optimized path for creating bootable volume from images
|
||||
where the images are stored in volumes called Image-Volume. There are two
|
||||
pre-conditions that needs to be satisfied for this optimization to work:
|
||||
|
||||
1. Image format should be 'raw' and container format should be 'bare'
|
||||
2. The user requested volume should be in the same project as the image
|
||||
|
||||
To enable this optimization, configure the following parameter in the Cinder
|
||||
configuration file:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[DEFAULT]
|
||||
allowed_direct_url_schemes = cinder
|
||||
|
||||
To enable the :command:`openstack image create --volume <volume>` command to
|
||||
create an image that refers an ``Image-Volume``, set the following options in
|
||||
each back-end section of the ``cinder.conf`` file:
|
||||
This optimization allows efficient cloning of the Image-Volume to the user
|
||||
requested volume which skips the generic path of downloading the image to
|
||||
the image conversion directory and writing it into the volume hence saving
|
||||
space and increasing performance for single or bulk operations.
|
||||
|
||||
Uploading a volume to Image Service
|
||||
-----------------------------------
|
||||
|
||||
When uploading a volume to the Image service, the data is copied chunk by
|
||||
chunk resulting in long wait time for the completion of the operation.
|
||||
With this optimization, Cinder clones the source volume to an Image-Volume
|
||||
and registers the location in Glance which is a significant performance
|
||||
improvement over the generic path.
|
||||
The pre-condition to enable this optimization is:
|
||||
|
||||
1. Image format should be 'raw' and container format should be 'bare'
|
||||
|
||||
Add the following configuration parameter in your Cinder configuration file
|
||||
in the respective backend section. Here we've used ``lvmdriver-1`` as an
|
||||
example.
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[lvmdriver-1]
|
||||
image_upload_use_cinder_backend = True
|
||||
|
||||
By default, the :command:`openstack image create --volume <volume>` command
|
||||
creates the Image-Volume in the current project. To store the Image-Volume into
|
||||
the internal project, set the following options in each back-end section of the
|
||||
``cinder.conf`` file:
|
||||
To avoid creating the Image-Volume in the user project, it is recommended to
|
||||
configure the internal tenant so the Image-Volumes are always stored in the
|
||||
service project. The ``image_upload_use_internal_tenant`` configuration should
|
||||
be done in the backend section, Here we've used ``lvmdriver-1`` as an example.
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[DEFAULT]
|
||||
cinder_internal_tenant_project_id = <UUID of the service project>
|
||||
cinder_internal_tenant_user_id = <UUID of the Cinder user>
|
||||
[lvmdriver-1]
|
||||
image_upload_use_internal_tenant = True
|
||||
|
||||
To make the Image-Volume in the internal project accessible from the Image
|
||||
service, set the following options in the ``glance_store`` section of
|
||||
the ``glance-api.conf`` file:
|
||||
.. _configuring-the-cinder-storage-backend: https://docs.openstack.org/glance/latest/configuration/configuring.html#configuring-the-cinder-storage-backend
|
||||
|
||||
- ``cinder_store_auth_address``
|
||||
- ``cinder_store_user_name``
|
||||
- ``cinder_store_password``
|
||||
- ``cinder_store_project_name``
|
||||
|
||||
Creating a Volume-backed image
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To register an existing volume as a new Volume-backed image, use the following
|
||||
commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack image create --disk-format raw --container-format bare IMAGE_NAME
|
||||
|
||||
$ glance location-add <image-uuid> --url cinder://<volume-uuid>
|
||||
|
||||
If the ``image_upload_use_cinder_backend`` option is enabled, the following
|
||||
command creates a new Image-Volume by cloning the specified volume and then
|
||||
registers its location to a new image. The disk format and the container format
|
||||
must be raw and bare (default). Otherwise, the image is uploaded to the default
|
||||
store of the Image service.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack image create --volume SOURCE_VOLUME IMAGE_NAME
|
||||
.. _New Location APIs: https://docs.openstack.org/glance/latest/admin/new-location-apis.html
|
||||
|
||||
Reference in New Issue
Block a user