From: Zac Dover Date: Wed, 14 Sep 2022 05:19:44 +0000 (+1000) Subject: doc/rados: update prompts in crush-map-edits.rst X-Git-Tag: v16.2.11~283^2 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=431b706069a685fb25fefa8106dfb6ef362f2cd3;p=ceph.git doc/rados: update prompts in crush-map-edits.rst This PR updates the prompts in crush-map-edits.rst to make them unselectable. There remains no good known way to render parts of a file if the first line of that file begins with a hash (#). Sphinx italicizes such a first line, which is not what I want. Two examples of this are present in the file crush-maps-rst under the section called "CRUSH Map Bucket Types". I set this down here for my own records, in case it is helpful in finding a way to make these sections render as I would prefer. Signed-off-by: Zac Dover (cherry picked from commit 7484b7c10a3f762e6649fb304fd0f7a5da5e418f) --- diff --git a/doc/rados/operations/crush-map-edits.rst b/doc/rados/operations/crush-map-edits.rst index aea48ae7d5bf..7fd9b42f5b3d 100644 --- a/doc/rados/operations/crush-map-edits.rst +++ b/doc/rados/operations/crush-map-edits.rst @@ -35,7 +35,9 @@ Pool Values`_. Get a CRUSH Map --------------- -To get the CRUSH map for your cluster, execute the following:: +To get the CRUSH map for your cluster, execute the following: + +.. prompt:: bash $ ceph osd getcrushmap -o {compiled-crushmap-filename} @@ -48,7 +50,9 @@ edit it. Decompile a CRUSH Map --------------------- -To decompile a CRUSH map, execute the following:: +To decompile a CRUSH map, execute the following: + +.. prompt:: bash $ crushtool -d {compiled-crushmap-filename} -o {decompiled-crushmap-filename} @@ -57,7 +61,9 @@ To decompile a CRUSH map, execute the following:: Recompile a CRUSH Map --------------------- -To compile a CRUSH map, execute the following:: +To compile a CRUSH map, execute the following: + +.. prompt:: bash $ crushtool -c {decompiled-crushmap-filename} -o {compiled-crushmap-filename} @@ -66,7 +72,9 @@ To compile a CRUSH map, execute the following:: Set the CRUSH Map ----------------- -To set the CRUSH map for your cluster, execute the following:: +To set the CRUSH map for your cluster, execute the following: + +.. prompt:: bash $ ceph osd setcrushmap -i {compiled-crushmap-filename} @@ -118,14 +126,22 @@ Devices may also have a *device class* associated with them (e.g., ``hdd`` or ``ssd``), allowing them to be conveniently targeted by a crush rule. +.. prompt:: bash # + + devices + :: - # devices device {num} {osd.name} [class {class}] -For example:: +For example: + +.. prompt:: bash # + + devices + +:: - # devices device 0 osd.0 class ssd device 1 osd.1 class hdd device 2 osd.2 @@ -136,10 +152,6 @@ is normally a single storage device, a pair of devices (for example, one for data and one for a journal or metadata), or in some cases a small RAID device. - - - - CRUSH Map Bucket Types ---------------------- @@ -159,7 +171,7 @@ bucket types. Enter ``type`` followed by a unique numeric ID and a bucket name. By convention, there is one leaf bucket and it is ``type 0``; however, you may give it any name you like (e.g., osd, disk, drive, storage, etc.):: - #types + # types type {num} {bucket-name} For example:: @@ -655,19 +667,26 @@ There are three types of transformations possible: single bucket. For example, in the previous example, we want the ``ssd`` bucket to be mapped to the ``default`` bucket. -The final command to convert the map comprised of the above fragments would be something like:: +The final command to convert the map comprised of the above fragments would be something like: + +.. prompt:: bash $ - $ ceph osd getcrushmap -o original - $ crushtool -i original --reclassify \ - --set-subtree-class default hdd \ - --reclassify-root default hdd \ - --reclassify-bucket %-ssd ssd default \ - --reclassify-bucket ssd ssd default \ - -o adjusted + ceph osd getcrushmap -o original + crushtool -i original --reclassify \ + --set-subtree-class default hdd \ + --reclassify-root default hdd \ + --reclassify-bucket %-ssd ssd default \ + --reclassify-bucket ssd ssd default \ + -o adjusted -In order to ensure that the conversion is correct, there is a ``--compare`` command that will test a large sample of inputs to the CRUSH map and ensure that the same result comes back out. These inputs are controlled by the same options that apply to the ``--test`` command. For the above example,:: +In order to ensure that the conversion is correct, there is a ``--compare`` command that will test a large sample of inputs to the CRUSH map and ensure that the same result comes back out. These inputs are controlled by the same options that apply to the ``--test`` command. For the above example,: + +.. prompt:: bash $ + + crushtool -i original --compare adjusted + +:: - $ crushtool -i original --compare adjusted rule 0 had 0/10240 mismatched mappings (0) rule 1 had 0/10240 mismatched mappings (0) maps appear equivalent @@ -675,9 +694,11 @@ In order to ensure that the conversion is correct, there is a ``--compare`` comm If there were difference, you'd see what ratio of inputs are remapped in the parentheses. -If you are satisfied with the adjusted map, you can apply it to the cluster with something like:: +If you are satisfied with the adjusted map, you can apply it to the cluster with something like: + +.. prompt:: bash $ - ceph osd setcrushmap -i adjusted + ceph osd setcrushmap -i adjusted Tuning CRUSH, the hard way -------------------------- @@ -686,7 +707,9 @@ If you can ensure that all clients are running recent code, you can adjust the tunables by extracting the CRUSH map, modifying the values, and reinjecting it into the cluster. -* Extract the latest CRUSH map:: +* Extract the latest CRUSH map: + + .. prompt:: bash $ ceph osd getcrushmap -o /tmp/crush @@ -694,19 +717,25 @@ and reinjecting it into the cluster. for both large and small clusters we tested with. You will need to additionally specify the ``--enable-unsafe-tunables`` argument to ``crushtool`` for this to work. Please use this option with - extreme care.:: + extreme care.: - crushtool -i /tmp/crush --set-choose-local-tries 0 --set-choose-local-fallback-tries 0 --set-choose-total-tries 50 -o /tmp/crush.new + .. prompt:: bash $ -* Reinject modified map:: + crushtool -i /tmp/crush --set-choose-local-tries 0 --set-choose-local-fallback-tries 0 --set-choose-total-tries 50 -o /tmp/crush.new - ceph osd setcrushmap -i /tmp/crush.new +* Reinject modified map: + + .. prompt:: bash $ + + ceph osd setcrushmap -i /tmp/crush.new Legacy values ------------- For reference, the legacy values for the CRUSH tunables can be set -with:: +with: + +.. prompt:: bash $ crushtool -i /tmp/crush --set-choose-local-tries 2 --set-choose-local-fallback-tries 5 --set-choose-total-tries 19 --set-chooseleaf-descend-once 0 --set-chooseleaf-vary-r 0 -o /tmp/crush.legacy