doc/rgw: document storage class configuration

Fixes: http://tracker.ceph.com/issues/38008
Signed-off-by: Casey Bodley <cbodley@redhat.com>

diff --git a/doc/radosgw/compression.rst b/doc/radosgw/compression.rst
index 41e535e1f83346eeaeca00e8fe4dba513ce14bf3..0fb366d5b555d2076604a1b13d1f1c8d8cb89ca8 100644 (file)
--- a/doc/radosgw/compression.rst
+++ b/doc/radosgw/compression.rst
@@ -11,9 +11,9 @@ using any of Ceph's existing compression plugins.
 Configuration
 =============
 
-Compression can be enabled on a Zone's placement target by providing the
-``--compression=<type>`` option to the ``radosgw-admin zone placement modify``
-command.
+Compression can be enabled on a storage class in the Zone's placement target
+by providing the ``--compression=<type>`` option to the command
+``radosgw-admin zone placement modify``.
 
 The compression ``type`` refers to the name of the compression plugin to use
 when writing new object data. Each compressed object remembers which plugin
@@ -26,7 +26,11 @@ an empty string or ``none``.
 
 For example::
 
-  $ radosgw-admin zone placement modify --rgw-zone=default --placement-id=default-placement --compression=zlib
+  $ radosgw-admin zone placement modify \
+        --rgw-zone default \
+        --placement-id default-placement \
+        --storage-class STANDARD \
+        --compression zlib
   {
   ...
       "placement_pools": [
@@ -34,10 +38,14 @@ For example::
               "key": "default-placement",
               "val": {
                   "index_pool": "default.rgw.buckets.index",
-                  "data_pool": "default.rgw.buckets.data",
+                  "storage_classes": {
+                      "STANDARD": {
+                          "data_pool": "default.rgw.buckets.data",
+                          "compression_type": "zlib"
+                      }
+                  },
                   "data_extra_pool": "default.rgw.buckets.non-ec",
                   "index_type": 0,
-                  "compression": "zlib"
               }
           }
       ],

diff --git a/doc/radosgw/index.rst b/doc/radosgw/index.rst
index a064733a6429b731c3f374b737cbe5baf3efb6e7..453b56ca777bf7062c41be128175b27d95ecb67e 100644 (file)
--- a/doc/radosgw/index.rst
+++ b/doc/radosgw/index.rst
@@ -40,7 +40,7 @@ you may write data with one API and retrieve it with the other.
 
    Manual Install w/Civetweb <../../install/install-ceph-gateway>
    HTTP Frontends <frontends>
-   Pool Placement <placement>
+   Pool Placement and Storage Classes <placement>
    Multisite Configuration <multisite>
    Configuring Pools <pools>
    Config Reference <config-ref>

diff --git a/doc/radosgw/placement.rst b/doc/radosgw/placement.rst
index ce9ecbc2e084dcb3b15f3f122c6832d2ec106f3c..bd164daf8de884d377a0e0709ef79b95b0ebb970 100644 (file)
--- a/doc/radosgw/placement.rst
+++ b/doc/radosgw/placement.rst
@@ -1,6 +1,6 @@
-==============
-Pool Placement
-==============
+==================================
+Pool Placement and Storage Classes
+==================================
 
 .. contents::
 
@@ -19,7 +19,22 @@ initial target named ``default-placement``. The zone configuration then maps
 each zonegroup placement target name onto its local storage. This zone
 placement information includes the ``index_pool`` name for the bucket index,
 the ``data_extra_pool`` name for metadata about incomplete multipart uploads,
-and a ``data_pool`` name for object data.
+and a ``data_pool`` name for each storage class.
+
+.. _storage_classes:
+
+Storage Classes
+===============
+
+.. versionadded:: Nautilus
+
+Storage classes are used to customize the placement of object data. S3 Bucket
+Lifecycle rules can automate the transition of objects between storage classes.
+
+Storage classes are defined in terms of placement targets. Each zonegroup
+placement target lists its available storage classes with an initial class
+named ``STANDARD``. The zone configuration is responsible for providing a
+``data_pool`` pool name for each of the zonegroup's storage classes.
 
 Zonegroup/Zone Configuration
 ============================
@@ -41,6 +56,9 @@ The zonegroup placement configuration can be queried with:
           {
               "name": "default-placement",
               "tags": [],
+              "storage_classes": [
+                  "STANDARD"
+              ]
           }
       ],
       "default_placement": "default-placement",
@@ -62,7 +80,11 @@ The zone placement configuration can be queried with:
               "key": "default-placement",
               "val": {
                   "index_pool": "default.rgw.buckets.index",
-                  "data_pool": "default.rgw.buckets.data",
+                  "storage_classes": {
+                      "STANDARD": {
+                          "data_pool": "default.rgw.buckets.data"
+                      }
+                  },
                   "data_extra_pool": "default.rgw.buckets.non-ec",
                   "index_type": 0
               }
@@ -99,7 +121,30 @@ Then provide the zone placement info for that target:
         --placement-id temporary \
         --data-pool default.rgw.temporary.data \
         --index-pool default.rgw.temporary.index \
-        --data-extra-pool default.rgw.temporary.non-ec \
+        --data-extra-pool default.rgw.temporary.non-ec
+
+Adding a Storage Class
+----------------------
+
+To add a new storage class named ``COLD`` to the ``default-placement`` target,
+start by adding it to the zonegroup:
+
+::
+
+  $ radosgw-admin zonegroup placement add \
+        --rgw-zonegroup default \
+        --placement-id default-placement \
+        --storage-class COLD
+
+Then provide the zone placement info for that storage class:
+
+::
+
+  $ radosgw-admin zone placement add \
+        --rgw-zone default \
+        --placement-id default-placement \
+        --storage-class COLD \
+        --data-pool default.rgw.cold.data \
         --compression lz4
 
 Customizing Placement
@@ -122,6 +167,8 @@ User Placement
 
 A Ceph Object Gateway user can override the zonegroup's default placement
 target by setting a non-empty ``default_placement`` field in the user info.
+Similarly, the ``default_storage_class`` can override the ``STANDARD``
+storage class applied to objects by default.
 
 ::
 
@@ -129,6 +176,7 @@ target by setting a non-empty ``default_placement`` field in the user info.
   {
       ...
       "default_placement": "",
+      "default_storage_class": "",
       "placement_tags": [],
       ...
   }
@@ -176,5 +224,20 @@ provided in the HTTP header ``X-Storage-Policy``:
 
   X-Storage-Policy: new-placement
 
+Using Storage Classes
+=====================
+
+All placement targets have a ``STANDARD`` storage class which is applied to
+new objects by default. The user can override this default with its
+``default_storage_class``.
+
+To create an object in a non-default storage class, provide that storage class
+name in an HTTP header with the request. The S3 protocol uses the
+``X-Amz-Storage-Class`` header, while the Swift protocol uses the
+``X-Object-Storage-Class`` header.
+
+S3 Object Lifecycle Management can then be used to move object data between
+storage classes using ``Transition`` actions.
+
 .. _`Pools`: ../pools
 .. _`Multisite Configuration`: ../multisite

diff --git a/doc/radosgw/s3.rst b/doc/radosgw/s3.rst
index cb859fd0919c56d00528e27a8dbe43724721e6a2..cf6eaba7fa4da55997919f8b8e6353348bb56f07 100644 (file)
--- a/doc/radosgw/s3.rst
+++ b/doc/radosgw/s3.rst
@@ -38,7 +38,7 @@ The following table describes the support status for current Amazon S3 functiona
 +---------------------------------+-----------------+----------------------------------------+
 | **Create Bucket**               | Supported       | Different set of canned ACLs           |
 +---------------------------------+-----------------+----------------------------------------+
-| **Bucket Lifecycle**            | Supported       | Removing expired files is supported    |
+| **Bucket Lifecycle**            | Supported       |                                        |
 +---------------------------------+-----------------+----------------------------------------+
 | **Policy (Buckets, Objects)**   | Supported       | ACLs & bucket policies are supported   |
 +---------------------------------+-----------------+----------------------------------------+
@@ -74,8 +74,8 @@ The following table describes the support status for current Amazon S3 functiona
 +---------------------------------+-----------------+----------------------------------------+
 | **Object Tagging**              | Supported       | See :ref:`tag_policy` for Policy verbs |
 +---------------------------------+-----------------+----------------------------------------+
-| **Storage Class**               | Not Supported   | Use **Bucket Location** as alternative |
-+--------------------------------------------------------------------------------------------+
+| **Storage Class**               | Supported       | See :ref:`storage_classes`             |
++---------------------------------+-----------------+----------------------------------------+
 
 
 Unsupported Header Fields