doc: Added commentary to configure pg defaults. Clarified size commentary.

Signed-off-by: John Wilkins <john.wilkins@inktank.com>

diff --git a/doc/rados/operations/pools.rst b/doc/rados/operations/pools.rst
index 62623b491ba6cea483b6dc51033eadda2a267c25..fc82510fa4b9c5bf84b25edf9a6439cbb1be86a9 100644 (file)
--- a/doc/rados/operations/pools.rst
+++ b/doc/rados/operations/pools.rst
@@ -50,6 +50,14 @@ The default pools include:
 Create a Pool
 =============
 
+Before creating pools, refer to the `Pool, PG and CRUSH Config Reference`_.
+Ideally, you should override the default value for the number of placement
+groups in you Ceph configuration file, as the default is NOT ideal. 
+For example:: 
+
+       osd pool default pg num = 100
+       osd pool default pgp num = 100
+
 To create a pool, execute:: 
 
        ceph osd pool create {pool-name} {pg-num} [{pgp-num}]
@@ -60,7 +68,7 @@ Where:
 
 :Description: The name of the pool. It must be unique.
 :Type: String
-:Required: Yes
+:Required: Yes. Picks up default or Ceph configuration value if not specified.
 
 ``{pg-num}``
 
@@ -79,9 +87,10 @@ Where:
               for placement group splitting scenarios.
 
 :Type: Integer
-:Required: Yes
+:Required: Yes. Picks up default or Ceph configuration value if not specified.
 :Default: 8
 
+
 When you create a pool, set the number of placement groups to a reasonable value
 (e.g., ``100``). Consider the total number of placement groups per OSD too.
 Placement groups are computationally expensive, so performance will degrade when
@@ -230,19 +239,15 @@ For example::
 
        ceph osd pool set data size 3
 
-You may execute this command for each pool. 
-
-Note, however, that pool size is more of a best-effort setting: an object
-might accept ios in degraded mode with fewer than size replicas.  To
-set a minimum number of required replicas for io, you should use the
-min_size setting.
-
+You may execute this command for each pool. **Note:** An object might accept 
+I/Os in degraded mode with fewer than ``pool size`` replicas.  To set a minimum
+number of required replicas for I/O, you should use the ``min_size`` setting.
 For example::
 
   ceph osd pool set data min_size 2
 
-This ensures that no object in the data pool will receive io with fewer than
-min_size replicas.
+This ensures that no object in the data pool will receive I/O with fewer than
+``min_size`` replicas.
 
 
 Get the Number of Object Replicas
@@ -253,4 +258,9 @@ To get the number of object replicas, execute the following::
        ceph osd dump | grep 'rep size'
        
 Ceph will list the pools, with the ``rep size`` attribute highlighted.
-By default, Ceph creates two replicas of an object (two copies).
+By default, ceph Creates one replica of an object (a total of two copies, or 
+a size of 2).
+
+
+
+.. _Pool, PG and CRUSH Config Reference: ../../configuration/pool-pg-config-ref