openstack
/
glance
Code Issues Proposed changes

Doc:Multiple stores support 

Added documentation and modified api-ref documents to
reflect multiple stores support changes.

Related to blueprint multi-store
Change-Id: I932297df8149968d31a5367a9ca71a5629045445
This commit is contained in:
Abhishek Kekane 2018-06-18 09:55:26 +00:00 committed by Erno Kuvaja
parent cb45edf5c8
commit d6ac7460ca
10 changed files with 298 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
api-ref/source/v2/discovery-parameters.yaml Normal file
View File

@ -0,0 +1,11 @@
stores:
description: |
A list of store objects, where each store object may contain the
following fields:
- ``id``
- ``description``
- ``default``
in: body
required: true
type: array

55
api-ref/source/v2/discovery.inc Normal file
View File

@ -0,0 +1,55 @@
.. -*- rst -*-
Stores
******
A multiple store backend support is introduced in the Rocky release
as a part of the EXPERIMENTAL Image API v2.8.
.. note:: The Multi Store feature is introduced as EXPERIMENTAL in Rocky and
its use in production systems is currently **not supported**.
However we encourage people to use this feature for testing
purposes and report the issues so that we can make it stable and
fully supported in Stein release.
In version 2.7 of the API, this call will return a 404 (Not Found).
Use the :ref:`API versions call <versions-call>` to determine
what API verisons are available in your cloud.
List of available store backends for glance.
.. _store-discovery-call:
List stores
~~~~~~~~~~~
.. rest_method:: GET /v2/info/stores
Lists stores.
Normal response codes: 200
Error response codes: 404
Request
-------
There are no request parameters.
This call does not allow a request body.
Response Parameters
-------------------
.. rest_parameters:: discovery-parameters.yaml
- stores: stores
Response Example
----------------
.. literalinclude:: samples/stores-list-response.json
:language: json

29
api-ref/source/v2/images-data.inc
View File

@ -21,11 +21,39 @@ Uploads binary image data.
Set the ``Content-Type`` request header to ``application/octet-stream``.
A multiple store backend support is introduced in the Rocky release
as a part of the EXPERIMENTAL Image API v2.8.
Beginning with API version 2.8, an optional ``X-Image-Meta-Store``
header may be added to the request. When present, the image data will be
placed into the backing store whose identifier is the value of this
header. If the store identifier specified is not recognized, a 400 (Bad
Request) response is returned. When the header is not present, the image
data is placed into the default backing store.
.. note:: The Multi Store feature is introduced as EXPERIMENTAL in Rocky and
its use in production systems is currently **not supported**.
However we encourage people to use this feature for testing
purposes and report the issues so that we can make it stable and
fully supported in Stein release.
* Store identifiers are site-specific. Use the :ref:`Store
Discovery <store-discovery-call>` call to determine what
stores are available in a particular cloud.
* The default store may be determined from the :ref:`Store
Discovery <store-discovery-call>` response.
* A default store is always defined, so if you do not have a need
to use a particular store, simply omit this header and the default store
will be used.
* For API versions before version 2.8, this header is silently
ignored.
Example call:
::
curl -i -X PUT -H "X-Auth-Token: $token" \
-H "X-Image-Meta-Store: {store_identifier}" \
-H "Content-Type: application/octet-stream" \
-d @/home/glance/ubuntu-12.10.qcow2 \
$image_url/v2/images/{image_id}/file
@ -75,6 +103,7 @@ Request
.. rest_parameters:: images-parameters.yaml
- Content-type: Content-Type-data
- X-Image-Meta-Store: store-header
- image_id: image_id-in-path

14
api-ref/source/v2/images-images-v2.inc
View File

@ -148,6 +148,19 @@ Creates a catalog record for an operating system disk image.
*(Since Image API v2.0)*
The ``Location`` response header contains the URI for the image.
A multiple store backend support is introduced in the Rocky release
as a part of the EXPERIMENTAL Image API v2.8. Since Image API v2.8 a
new header ``OpenStack-image-store-ids`` which contains the list of
available stores will be included in response. This header is only
included if multiple backend stores are supported.
.. note:: The Multi Store feature is introduced as EXPERIMENTAL in Rocky and
its use in production systems is currently **not supported**.
However we encourage people to use this feature for testing
purposes and report the issues so that we can make it stable and
fully supported in Stein release.
The response body contains the new image entity.
Synchronous Postconditions
@ -193,6 +206,7 @@ Response Parameters
- Location: Location
- OpenStack-image-import-methods: import-header
- OpenStack-image-store-ids: stores-header
- checksum: checksum
- container_format: container_format
- created_at: created_at

36
api-ref/source/v2/images-import.inc
View File

@ -44,6 +44,19 @@ Thus, the first step is:
methods may be determined independently of creating an image by making
the :ref:`Import Method Discovery <import-discovery-call>` call.
In a cloud in which multiple storage backends are available, the
:ref:`Image Create <image-create>` response will include a
``OpenStack-image-store-ids`` header listing the stores available in
that cloud. Alternatively, these stores may be determined independently
of creating an image by making the :ref:`Stores Discovery
<store-discovery-call>` call.
.. note:: The Multi Store feature is introduced as EXPERIMENTAL in Rocky and
its use in production systems is currently **not supported**.
However we encourage people to use this feature for testing
purposes and report the issues so that we can make it stable and
fully supported in Stein release.
The glance-direct import method
-------------------------------
@ -158,8 +171,26 @@ call.
In the ``web-download`` workflow, the data is made available to the Image
service by being posted to an accessible location with a URL that you know.
Example call: ``curl -i -X POST -H "X-Auth-Token: $token"
$image_url/v2/images/{image_id}/import``
Beginning with API version 2.8, an optional ``X-Image-Meta-Store``
header may be added to the request. When present, the image data will be
placed into the backing store whose identifier is the value of this
header. If the store identifier specified is not recognized, a 409 (Conflict)
response is returned. When the header is not present, the image
data is placed into the default backing store.
* Store identifiers are site-specific. Use the :ref:`Store
Discovery <store-discovery-call>` call to determine what
stores are available in a particular cloud.
* The default store may be determined from the :ref:`Store
Discovery <store-discovery-call>` response.
* A default store is always defined, so if you do not have a need
to use a particular store, simply omit this header and the default store
will be used.
* For API versions before version 2.8, this header is silently
ignored.
Example call: ``curl -i -X POST -H "X-Image-Meta-Store: {store_identifier}"
-H "X-Auth-Token: $token" $image_url/v2/images/{image_id}/import``
The JSON request body specifies what import method you wish to use
for this image request.
@ -225,6 +256,7 @@ Request
.. rest_parameters:: images-parameters.yaml
- Content-type: Content-Type-json
- X-Image-Meta-Store: store-header
- image_id: image_id-in-path
- method: method-in-request

17
api-ref/source/v2/images-parameters.yaml
View File

@ -72,6 +72,23 @@ Range:
in: header
required: false
type: string
store-header:
description: |
A store identifier to upload or import image data. Should only be included
when making a request to a cloud that supports multiple backing stores. Use
the :ref:`Store Discovery <store-discovery-call>` call to determine an
appropriate store identifier. Simply omit this header to use the default
store. *(Since Image API v2.8)*
in: header
required: false
type: string
stores-header:
description: |
A comma separated list of available store identifiers. If this header
is missing the cloud does not support multiple backend stores.
in: header
required: false
type: string
# variables in path
image_id-in-path:

1
api-ref/source/v2/index.rst
View File

@ -29,5 +29,6 @@ Image Service API v2 (CURRENT)
.. include:: images-schemas.inc
.. include:: images-data.inc
.. include:: images-import.inc
.. include:: discovery.inc
.. include:: tasks.inc
.. include:: tasks-schemas.inc

17
api-ref/source/v2/samples/stores-list-response.json Normal file
View File

@ -0,0 +1,17 @@
{
"stores": [
{
"id":"reliable",
"description": "Reliable filesystem store"
},
{
"id":"fast",
"description": "Fast access to rbd store",
"default": true
},
{
"id":"cheap",
"description": "Less expensive rbd store"
}
]
}

1
doc/source/admin/index.rst
View File

@ -15,6 +15,7 @@ Glance Administration Guide
controllingservers
flows
interoperable-image-import
multistores
db
db-sqlalchemy-migrate
zero-downtime-db-upgrade

119
doc/source/admin/multistores.rst Normal file
View File

@ -0,0 +1,119 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _multi_stores:
Multi Store Support
===================
.. note:: The Multi Store feature is introduced as EXPERIMENTAL in Rocky and
its use in production systems is currently **not supported**.
However we encourage people to use this feature for testing
purposes and report the issues so that we can make it stable and
fully supported in Stein release.
Scope of this document
----------------------
This page describes how to enable multiple stores in glance.
Prerequisites
-------------
* Glance version 17.0.0 or Later
* Glance Store Library 0.25.0 or Later
* Glance not using the Glance Registry
* Available backends
Procedure
---------
In this section, we discuss what configuration options are available to
operators to enable multiple stores support.
* in the ``[DEFAULT]`` options group:
* ``enabled_backends`` must be set as a key:value pair where key
represents the identifier for the store and value will be the type
of the store. Valid values are one of ``file``, ``http``, ``rbd``,
``swift``, ``cinder``, ``sheepdog`` or ``vmware``. In order to have
multiple stores operator can specify multiple key:value separated by comma.
.. code-block:: ini
[DEFAULT]
enabled_backends = fast:rbd, cheap:rbd, shared:file, reliable:file
.. note:: Due to the special read only nature and characteristics of the
http store we do not encourage nor support configuring multiple
instances of http store even though it's possible.
* in the ``[glance_store]`` options group:
* ``default_backend`` must be set to one of the identifier which are defined
using ``enabled_backends`` option. If ``default_backend`` is not set or if
it is not representing one of the valid store drivers then it will prevent
glance api service from starting.
.. code-block:: ini
[DEFAULT]
default_backend = fast
* For each of the store identifier defined in ``enabled_backends`` section
operator needs to add a new config group which will define config options
related to that particular store.
.. code-block:: ini
[shared]
filesystem_store_datadir = /opt/stack/data/glance/shared_images/
store_description = "Shared filesystem store"
[reliable]
filesystem_store_datadir = /opt/stack/data/glance/reliable
store_description = "Reliable filesystem backend"
[fast]
store_description = "Fast rbd backend"
rbd_store_chunk_size = 8
rbd_store_pool = images
rbd_store_user = admin
rbd_store_ceph_conf = /etc/ceph/ceph.conf
rados_connect_timeout = 0
[cheap]
store_description = "Cheap rbd backend"
rbd_store_chunk_size = 8
rbd_store_pool = images
rbd_store_user = admin
rbd_store_ceph_conf = /etc/ceph/ceph1.conf
rados_connect_timeout = 0
.. note ::
``store_description`` is a new config option added to each store where
operator can add meaningful description about that store. This description
is displayed in the GET /v2/info/stores response.
* For new image import workflow glance will reserve a ``os_staging`` file
store identifier for staging the images data during staging operation. This
should be added by default in ``glance-api.conf`` as shown below:
.. code-block:: ini
[os_staging]
filesystem_store_datadir = /opt/stack/data/glance/os_staging/
store_description = "Filesystem store for staging purpose"