ceph/doc/radosgw/compression.rst

   1 ===========
   2 Compression
   3 ===========
   4
   5 .. versionadded:: Kraken
   6
   7 The Ceph Object Gateway supports server-side compression of uploaded objects,
   8 using any of Ceph's existing compression plugins.
   9
  10
  11 Configuration
  12 =============
  13
  14 Compression can be enabled on a storage class in the Zone's placement target
  15 by providing the ``--compression=<type>`` option to the command
  16 ``radosgw-admin zone placement modify``.
  17
  18 The compression ``type`` refers to the name of the compression plugin to use
  19 when writing new object data. Each compressed object remembers which plugin
  20 was used, so changing this setting does not hinder the ability to decompress
  21 existing objects, nor does it force existing objects to be recompressed.
  22
  23 This compression setting applies to all new objects uploaded to buckets using
  24 this placement target. Compression can be disabled by setting the ``type`` to
  25 an empty string or ``none``.
  26
  27 For example::
  28
  29   $ radosgw-admin zone placement modify \
  30         --rgw-zone default \
  31         --placement-id default-placement \
  32         --storage-class STANDARD \
  33         --compression zlib
  34   {
  35   ...
  36       "placement_pools": [
  37           {
  38               "key": "default-placement",
  39               "val": {
  40                   "index_pool": "default.rgw.buckets.index",
  41                   "storage_classes": {
  42                       "STANDARD": {
  43                           "data_pool": "default.rgw.buckets.data",
  44                           "compression_type": "zlib"
  45                       }
  46                   },
  47                   "data_extra_pool": "default.rgw.buckets.non-ec",
  48                   "index_type": 0,
  49               }
  50           }
  51       ],
  52   ...
  53   }
  54
  55 .. note:: A ``default`` zone is created for you if you have not done any
  56    previous `Multisite Configuration`_.
  57
  58
  59 Statistics
  60 ==========
  61
  62 While all existing commands and APIs continue to report object and bucket
  63 sizes based their uncompressed data, compression statistics for a given bucket
  64 are included in its ``bucket stats``::
  65
  66   $ radosgw-admin bucket stats --bucket=<name>
  67   {
  68   ...
  69       "usage": {
  70           "rgw.main": {
  71               "size": 1075028,
  72               "size_actual": 1331200,
  73               "size_utilized": 592035,
  74               "size_kb": 1050,
  75               "size_kb_actual": 1300,
  76               "size_kb_utilized": 579,
  77               "num_objects": 104
  78           }
  79       },
  80   ...
  81   }
  82
  83 The ``size_utilized`` and ``size_kb_utilized`` fields represent the total
  84 size of compressed data, in bytes and kilobytes respectively.
  85
  86
  87 .. _`Multisite Configuration`: ../multisite