doc: update ec docs for overwrite support

Signed-off-by: Josh Durgin <jdurgin@redhat.com>

diff --git a/doc/rados/operations/erasure-code.rst b/doc/rados/operations/erasure-code.rst
index 43a97c57caa8758b55bde53a03a30986e49bb8cd..6878777ac721829b7d913a25d717bab9685a9c14 100644 (file)
--- a/doc/rados/operations/erasure-code.rst
+++ b/doc/rados/operations/erasure-code.rst
@@ -113,12 +113,41 @@ no two *chunks* are stored in the same rack.
 More information can be found in the `erasure code profiles
 <../erasure-code-profile>`_ documentation.
 
+
+Erasure Coding with Overwrites
+------------------------------
+
+By default, erasure coded pools only work with uses like RGW that
+perform full object writes and appends.
+
+Since Luminous, partial writes for an erasure coded pool may be
+enabled with a per-pool setting. This lets RBD and Cephfs store their
+data in an erasure coded pool::
+
+    ceph osd pool set ec_pool allow_ec_overwrites true
+
+This can only be enabled on a pool residing on bluestore OSDs, since
+bluestore's checksumming is used to detect bitrot or other corruption
+during deep-scrub. In addition to being unsafe, using filestore with
+ec overwrites yields low performance compared to bluestore.
+
+Erasure coded pools do not support omap, so to use them with RBD and
+Cephfs you must instruct them to store their data in an ec pool, and
+their metadata in a replicated pool. For RBD, this means using the
+erasure coded pool as the ``--data-pool`` during image creation::
+
+    rbd create --size 1G --data-pool ec_pool replicated_pool/image_name
+
+For Cephfs, using an erasure coded pool means setting that pool in
+a `file layout<../../cephfs/file-layouts>`_.
+
+
 Erasure coded pool and cache tiering
 ------------------------------------
 
 Erasure coded pools require more resources than replicated pools and
-lack some functionalities such as partial writes. To overcome these
-limitations, it is recommended to set a `cache tier <../cache-tiering>`_
+lack some functionalities such as omap. To overcome these
+limitations, one can set up a `cache tier <../cache-tiering>`_
 before the erasure coded pool.
 
 For instance, if the pool *hot-storage* is made of fast storage::
@@ -131,13 +160,6 @@ will place the *hot-storage* pool as tier of *ecpool* in *writeback*
 mode so that every write and read to the *ecpool* are actually using
 the *hot-storage* and benefit from its flexibility and speed.
 
-It is not possible to create an RBD image on an erasure coded pool
-because it requires partial writes. It is however possible to create
-an RBD image on an erasure coded pools when a replicated pool tier set
-a cache tier::
-
-    $ rbd create --size 10G ecpool/myvolume
-
 More information can be found in the `cache tiering
 <../cache-tiering>`_ documentation.
 

diff --git a/doc/rados/operations/pools.rst b/doc/rados/operations/pools.rst
index d370677b1bb2e96bdff8517a835d3e67935ef5d0..7db41d6364abb599935c77b31b66331e10f38fe5 100644 (file)
--- a/doc/rados/operations/pools.rst
+++ b/doc/rados/operations/pools.rst
@@ -301,6 +301,16 @@ You may set values for the following keys:
 :Description: The ruleset to use for mapping object placement in the cluster.
 :Type: Integer
 
+.. _allow_ec_overwrites:
+
+``allow_ec_overwrites``
+
+:Description: Whether writes to an erasure coded pool can update part
+              of an object, so cephfs and rbd can use it. See
+              `Erasure Coding with Overwrites`_ for more details.
+:Type: Boolean
+:Version: ``12.2.0`` and above
+
 .. _hashpspool:
 
 ``hashpspool``
@@ -731,3 +741,4 @@ a size of 3).
 .. _Pool, PG and CRUSH Config Reference: ../../configuration/pool-pg-config-ref
 .. _Bloom Filter: http://en.wikipedia.org/wiki/Bloom_filter
 .. _setting the number of placement groups: ../placement-groups#set-the-number-of-placement-groups
+.. _Erasure Coding with Overwrites: ../erasure-code#erasure-coding-with-overwrites