diff --git a/api-ref/source/v2/discovery-parameters.yaml b/api-ref/source/v2/discovery-parameters.yaml new file mode 100644 index 0000000000..1974096455 --- /dev/null +++ b/api-ref/source/v2/discovery-parameters.yaml @@ -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 diff --git a/api-ref/source/v2/discovery.inc b/api-ref/source/v2/discovery.inc new file mode 100644 index 0000000000..f2ab7e0708 --- /dev/null +++ b/api-ref/source/v2/discovery.inc @@ -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 ` 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 diff --git a/api-ref/source/v2/images-data.inc b/api-ref/source/v2/images-data.inc index 257c0d0ae0..4539550024 100644 --- a/api-ref/source/v2/images-data.inc +++ b/api-ref/source/v2/images-data.inc @@ -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 ` call to determine what + stores are available in a particular cloud. +* The default store may be determined from the :ref:`Store + Discovery ` 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 diff --git a/api-ref/source/v2/images-images-v2.inc b/api-ref/source/v2/images-images-v2.inc index aead71e217..d10c796e02 100644 --- a/api-ref/source/v2/images-images-v2.inc +++ b/api-ref/source/v2/images-images-v2.inc @@ -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 diff --git a/api-ref/source/v2/images-import.inc b/api-ref/source/v2/images-import.inc index 6f1a91c2d1..94481b799c 100644 --- a/api-ref/source/v2/images-import.inc +++ b/api-ref/source/v2/images-import.inc @@ -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 ` call. + In a cloud in which multiple storage backends are available, the + :ref:`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 + ` 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 ` call to determine what + stores are available in a particular cloud. +* The default store may be determined from the :ref:`Store + Discovery ` 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 diff --git a/api-ref/source/v2/images-parameters.yaml b/api-ref/source/v2/images-parameters.yaml index 060f6f9b1e..113e4a54f5 100644 --- a/api-ref/source/v2/images-parameters.yaml +++ b/api-ref/source/v2/images-parameters.yaml @@ -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 ` 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: diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index e3a0158359..34e1ec74f0 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -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 diff --git a/api-ref/source/v2/samples/stores-list-response.json b/api-ref/source/v2/samples/stores-list-response.json new file mode 100644 index 0000000000..75c372d544 --- /dev/null +++ b/api-ref/source/v2/samples/stores-list-response.json @@ -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" + } + ] +} \ No newline at end of file diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index d0b656252f..5f719baa0f 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -15,6 +15,7 @@ Glance Administration Guide controllingservers flows interoperable-image-import + multistores db db-sqlalchemy-migrate zero-downtime-db-upgrade diff --git a/doc/source/admin/multistores.rst b/doc/source/admin/multistores.rst new file mode 100644 index 0000000000..c6d9a8e3dd --- /dev/null +++ b/doc/source/admin/multistores.rst @@ -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"