doc/rados: update "Pools" material

Remove mentions of default pools (which no longer exist) and improve the
syntax of the Pools front matter.

Signed-off-by: Zac Dover <zac.dover@gmail.com>
(cherry picked from commit 956507270465de7d2847f085da22054c42fa3fad)

diff --git a/doc/rados/operations/pools.rst b/doc/rados/operations/pools.rst
index 92e98561ef2491c611c064e6490ae2aca4f50259..524953998b12077c8ae6ed5f3f24229cc78b3558 100644 (file)
--- a/doc/rados/operations/pools.rst
+++ b/doc/rados/operations/pools.rst
@@ -1,34 +1,41 @@
 =======
  Pools
 =======
-Pools are logical partitions for storing objects.
-
-When you first deploy a cluster without creating a pool, Ceph uses the default
-pools for storing data. A pool provides you with:
-
-- **Resilience**: You can set how many OSD are allowed to fail without losing data.
-  For replicated pools, it is the desired number of copies/replicas of an object.
-  A typical configuration stores an object and one additional copy
-  (i.e., ``size = 2``), but you can determine the number of copies/replicas.
-  For `erasure coded pools <../erasure-code>`_, it is the number of coding chunks
-  (i.e. ``m=2`` in the **erasure code profile**)
-
-- **Placement Groups**: You can set the number of placement groups for the pool.
-  A typical configuration uses approximately 100 placement groups per OSD to
-  provide optimal balancing without using up too many computing resources. When
-  setting up multiple pools, be careful to ensure you set a reasonable number of
-  placement groups for both the pool and the cluster as a whole.
-
-- **CRUSH Rules**: When you store data in a pool, placement of the object
-  and its replicas (or chunks for erasure coded pools) in your cluster is governed
-  by CRUSH rules. You can create a custom CRUSH rule for your pool if the default
-  rule is not appropriate for your use case.
-
-- **Snapshots**: When you create snapshots with ``ceph osd pool mksnap``,
-  you effectively take a snapshot of a particular pool.
-
-To organize data into pools, you can list, create, and remove pools.
-You can also view the utilization statistics for each pool.
+Pools are logical partitions that are used to store objects.
+
+Pools provide:
+
+- **Resilience**: It is possible to set the number of OSDs that are allowed to
+  fail without any data in the cluster being lost. If your cluster uses
+  replicated pools, the number of OSDs that can fail without data loss is the
+  number of replicas of an object. For example: a typical configuration stores
+  an object and two additional copies (that is: ``size = 3``), but you can
+  configure the number of replicas on a per-pool basis. For `erasure coded
+  pools <../erasure-code>`_, resilience is defined as the number of coding
+  chunks (for example, ``m = 2`` in the **erasure code profile**).
+
+- **Placement Groups**: You can set the number of placement groups for the
+  pool. A typical configuration targets approximately 100 placement groups per
+  OSD, providing optimal balancing without consuming many computing resources.
+  When setting up multiple pools, be careful to set a reasonable number of
+  placement groups for each pool and for the cluster as a whole. Note that each
+  PG belongs to a specific pool: when multiple pools use the same OSDs, make
+  sure that the **sum** of PG replicas per OSD is in the desired PG per OSD
+  target range.
+
+- **CRUSH Rules**: When data is stored in a pool, the placement of the object
+  and its replicas (or chunks, in the case of erasure-coded pools) in your
+  cluster is governed by CRUSH rules. Custom CRUSH rules can be created for a
+  pool if the default rule does not fit your use case.
+
+- **Snapshots**: The command ``ceph osd pool mksnap`` creates a snapshot of a
+  pool. 
+
+Pool Names
+==========
+
+Pool names beginning with ``.`` are reserved for use by Ceph's internal
+operations. Please do not create or manipulate pools with these names.
 
 List Pools
 ==========