From 8ecae46345c39426f71a3f4e4b77a6f812bc9aae Mon Sep 17 00:00:00 2001 From: Mykola Golub Date: Tue, 3 Aug 2021 17:40:22 +0300 Subject: [PATCH] doc: add crushdiff(8) man page Signed-off-by: Mykola Golub --- ceph.spec.in | 1 + debian/ceph-common.install | 1 + doc/man/8/CMakeLists.txt | 1 + doc/man/8/crushdiff.rst | 118 +++++++++++++++++++++++++++++++++++++ doc/man_index.rst | 1 + doc/rados/man/index.rst | 1 + 6 files changed, 123 insertions(+) create mode 100644 doc/man/8/crushdiff.rst diff --git a/ceph.spec.in b/ceph.spec.in index 5fe197417a2..7ca560fe81b 100644 --- a/ceph.spec.in +++ b/ceph.spec.in @@ -1603,6 +1603,7 @@ exit 0 %{_mandir}/man8/ceph-syn.8* %{_mandir}/man8/ceph-post-file.8* %{_mandir}/man8/ceph.8* +%{_mandir}/man8/crushdiff.8* %{_mandir}/man8/mount.ceph.8* %{_mandir}/man8/rados.8* %{_mandir}/man8/radosgw-admin.8* diff --git a/debian/ceph-common.install b/debian/ceph-common.install index 2ec671b357c..c3bc9dbaa4e 100755 --- a/debian/ceph-common.install +++ b/debian/ceph-common.install @@ -33,6 +33,7 @@ usr/share/man/man8/ceph-rbdnamer.8 usr/share/man/man8/ceph-syn.8 usr/share/man/man8/ceph-post-file.8 usr/share/man/man8/ceph.8 +usr/share/man/man8/crushdiff.8 usr/share/man/man8/mount.ceph.8 usr/share/man/man8/rados.8 usr/share/man/man8/radosgw-admin.8 diff --git a/doc/man/8/CMakeLists.txt b/doc/man/8/CMakeLists.txt index c3eb4101bf9..4675cc11dd2 100644 --- a/doc/man/8/CMakeLists.txt +++ b/doc/man/8/CMakeLists.txt @@ -24,6 +24,7 @@ set(osd_srcs ceph-volume.rst ceph-volume-systemd.rst ceph-osd.rst + crushdiff.rst osdmaptool.rst ceph-bluestore-tool.rst) diff --git a/doc/man/8/crushdiff.rst b/doc/man/8/crushdiff.rst new file mode 100644 index 00000000000..44ba4f5611a --- /dev/null +++ b/doc/man/8/crushdiff.rst @@ -0,0 +1,118 @@ +:orphan: + +.. _crushdiff: + +======================================= + crushdiff -- ceph crush map test tool +======================================= + +.. program:: crushdiff + +Synopsis +======== + +| **crushdiff** [ --osdmap *osdmap* ] [ --pg-dump *pg-dump* ] + [ --compiled ] [ --verbose ] *command* *crushmap* + + +Description +=========== + +**crushdiff** is a utility that lets you test the effect of a crushmap +change: number of pgs, objects, bytes moved. This is a wrapper around +:doc:`osdmaptool `\(8), relying on its **--test-map-pgs-dump** +option to get the list of changed pgs. Additionally it uses pg stats +to calculate the numbers of objects and bytes moved. + +By default, **crushdiff** will use the cluster current osdmap and pg +stats, which requires access to the cluster. Though one can use the +**--osdmap** and **--pg-dump** options to test against previously +obtained data. + +Options +======= + +.. option:: --compiled + + The input/output crushmap is compiled. If the options is not + specified the expected/returned crushmap is in txt (decompiled) + format. + +.. option:: --pg-dump + + JSON output of **ceph pg dump**. If not specified **crushdiff** + will try to get data running the command itself. + +.. option:: --osdmap + + The cluster osdmap, obtained with **ceph osd getmap** command. If + not specified **crushdiff** will try to get data running the + command itself. + +.. option:: --verbose + + Produce diagnostic output. + +Commands +======== + +:command:`compare` *crushmap* + Compare the crushmap from *crushmap* file with the crushmap from + the cluster osdmap. The output will show the expected number of pgs, + objects, bytes moved when the new crushmap is installed. + +:command:`export` *crushmap* + Export crushmap to *crushmap* file from the cluster osdmap. + +:command:`import` *crushmap* + Import crushmap from *crushmap* file to the cluster osdmap. + +Example +======= + +Get the current crushmap:: + + crushdiff export cm.txt + +Edit the map:: + + $EDITOR cm.txt + +Check the result:: + + crushdiff compare cm.txt + + 79/416 (18.99%) pgs affected + 281/1392 (20.19%) objects affected + 80/1248 (6.41%) pg shards to move + 281/4176 (6.73%) pg object shards to move + 730.52Mi/10.55Gi (6.76%) bytes to move + +When running with **--verbose** option the output will also contain +detailed information about the affected pgs, like below:: + + 4.3 [0, 2, 1] -> [1, 4, 2] + 4.b [0, 1, 3] -> [2, 1, 3] + 4.c [4, 0, 1] -> [4, 1, 2] + +i.e. a pg number, and its old and the new osd active sets. + +If the result is satisfactory install the updated map:: + + crushdiff import cm.txt + + +Availability +============ + +**crushdiff** is part of Ceph, a massively scalable, open-source, distributed storage system. Please +refer to the Ceph documentation at https://docs.ceph.com for more +information. + + +See also +======== + +:doc:`ceph `\(8), +:doc:`crushtool `\(8), +:doc:`osdmaptool `\(8), diff --git a/doc/man_index.rst b/doc/man_index.rst index d89cac2d310..1f786ac8a74 100644 --- a/doc/man_index.rst +++ b/doc/man_index.rst @@ -26,6 +26,7 @@ man/8/cephfs-top man/8/cephfs-mirror man/8/cephfs-shell + man/8/crushdiff man/8/crushtool man/8/librados-config man/8/monmaptool diff --git a/doc/rados/man/index.rst b/doc/rados/man/index.rst index 8311bfd5a30..bac56aa4602 100644 --- a/doc/rados/man/index.rst +++ b/doc/rados/man/index.rst @@ -18,6 +18,7 @@ ../../man/8/ceph-kvstore-tool.rst ../../man/8/ceph-run.rst ../../man/8/ceph-syn.rst + ../../man/8/crushdiff.rst ../../man/8/crushtool.rst ../../man/8/librados-config.rst ../../man/8/monmaptool.rst -- 2.39.5