doc: add docs for rgw compression

Signed-off-by: Casey Bodley <cbodley@redhat.com>
ceph · Nov 22, 2016 · 83888f7 · 83888f7
1 parent cf617f4
commit 83888f7
Show file tree

Hide file tree

Showing 3 changed files with 60 additions and 10 deletions.
diff --git a/doc/radosgw/compression.rst b/doc/radosgw/compression.rst
@@ -0,0 +1,59 @@
+===========
+Compression
+===========
+
+.. versionadded:: Kraken
+
+The Ceph Object Gateway supports server-side compression of uploaded objects,
+using any of Ceph's existing compression plugins.
+
+
+Configuration
+=============
+
+Compression can be enabled on a Zone as part of `Multisite Configuration`_::
+
+  $ radosgw-admin zone modify --rgw-zone=default --rgw-zonegroup=default --compression=<type>
+
+The compression ``type`` refers to the name of the compression plugin to use
+when writing new object data. Each compressed object remembers which plugin
+was used, so changing this setting does not hinder the ability to decompress
+existing objects, not does it force existing objects to be recompressed.
+
+This compression setting applies globally to all new objects uploaded,
+regardless of their bucket or user. Compression can be disabled by setting
+the ``type`` to an empty string or ``none``.
+
+.. note:: A ``default`` zone and zonegroup are created for you if you have
+   not done any previous Multisite Configuration.
+
+
+Statistics
+==========
+
+While all existing commands and APIs continue to report object and bucket
+sizes based their uncompressed data, compression statistics for a given bucket
+are included in its `bucket stats`::
+
+  $ radosgw-admin bucket stats --bucket=<name>
+  {
+  ...
+      "usage": {
+          "rgw.main": {
+              "size": 1075028,
+              "size_actual": 1331200,
+              "size_utilized": 592035,
+              "size_kb": 1050,
+              "size_kb_actual": 1300,
+              "size_kb_utilized": 579,
+              "num_objects": 104
+          }
+      },
+  ...
+  }
+
+The ``size_utilized`` and ``size_kb_utilized`` fields represent the total
+size of compressed data, in bytes and kilobytes respectively.
+
+
+.. _`Multisite Configuration`: ../../multisite
diff --git a/doc/radosgw/config-ref.rst b/doc/radosgw/config-ref.rst
@@ -380,16 +380,6 @@ Ceph configuration file, the default value will be set automatically.
 :Default: ``-1``
 
 
-``rgw compression type``
-
-:Description: The compression plugin to use when writing object data. Each
-              compressed object remembers which plugin was used, so changing
-              this setting does not hinder the ability to decompress existing
-              objects, not does it force existing objects to be recompressed.
-:Type: String
-:Default: ``none``
-
-
 Regions
 =======
 

diff --git a/doc/radosgw/index.rst b/doc/radosgw/index.rst
@@ -47,6 +47,7 @@ you may write data with one API and retrieve it with the other.
 	Admin Ops API <adminops>
 	OpenStack Keystone Integration <keystone>
 	Multi-tenancy <multitenancy>
+	Compression <compression>
 	troubleshooting
 	Manpage radosgw <../../man/8/radosgw>
 	Manpage radosgw-admin <../../man/8/radosgw-admin>