Merge "Doc:Multiple stores support"

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

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 <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

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 <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
 
 

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

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 <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
 

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 <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:

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

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"
+        }
+    ]
+}

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

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"