Merge "Doc:Multiple stores support"

8 files changed, 178 insertions, 2 deletions

diff --git a/api-ref/source/v2/discovery-parameters.yaml b/api-ref/source/v2/discovery-parameters.yaml
new file mode 100644
index 000000000..197409645
--- /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 000000000..f2ab7e070
--- /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 <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 257c0d0ae..453955002 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 <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
 
 
diff --git a/api-ref/source/v2/images-images-v2.inc b/api-ref/source/v2/images-images-v2.inc
index aead71e21..d10c796e0 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 6f1a91c2d..94481b799 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 <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
 
diff --git a/api-ref/source/v2/images-parameters.yaml b/api-ref/source/v2/images-parameters.yaml
index 060f6f9b1..113e4a54f 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 <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:
diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst
index e3a015835..34e1ec74f 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 000000000..75c372d54
--- /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