doc/rados: edit placement-groups.rst (1 of x) #51975

zdover23 · 2023-06-08T18:55:58Z

Edit doc/rados/operations/placement-groups.rst.

https://tracker.ceph.com/issues/58485

Contribution Guidelines

To sign and title your commits, please refer to Submitting Patches to Ceph.
If you are submitting a fix for a stable branch (e.g. "pacific"), please refer to Submitting Patches to Ceph - Backports for the proper workflow.

Checklist

Tracker (select at least one)
- References tracker ticket
- Very recent bug; references commit where it was introduced
- New feature (ticket optional)
- Doc update (no ticket needed)
- Code cleanup (no ticket needed)
Component impact
- Affects Dashboard, opened tracker ticket
- Affects Orchestrator, opened tracker ticket
- No impact that needs to be tracked
Documentation (select at least one)
- Updates relevant documentation
- No doc update is appropriate
Tests (select at least one)
- Includes unit test(s)
- Includes integration test(s)
- Includes bug reproducer
- No tests

Show available Jenkins commands

jenkins retest this please
jenkins test classic perf
jenkins test crimson perf
jenkins test signed
jenkins test make check
jenkins test make check arm64
jenkins test submodules
jenkins test dashboard
jenkins test dashboard cephadm
jenkins test api
jenkins test docs
jenkins render docs
jenkins test ceph-volume all
jenkins test ceph-volume tox
jenkins test windows

anthonyeleven

Various suggestions

anthonyeleven · 2023-06-08T21:00:22Z

doc/rados/operations/placement-groups.rst

+Placement groups (PGs) are an internal implementation detail of how Ceph
+distributes data. Autoscaling provides a way to manage PGs, and especially to
+manage the number of PGs present in different pools.  When *pg-autoscaling* is
+enabled, the cluster is allowed to make recommendations and automatic


anthonyeleven · 2023-06-08T21:01:31Z

doc/rados/operations/placement-groups.rst


 .. prompt:: bash #

   ceph osd pool set foo pg_autoscale_mode on

-You can also configure the default ``pg_autoscale_mode`` that is
-set on any pools that are subsequently created:
+There is also a default ``pg_autoscale_mode`` setting for any pools that are


s/default//

anthonyeleven · 2023-06-08T21:01:39Z

doc/rados/operations/placement-groups.rst

-You can also configure the default ``pg_autoscale_mode`` that is
-set on any pools that are subsequently created:
+There is also a default ``pg_autoscale_mode`` setting for any pools that are
+created after the initial setup of the cluster. To configure this setting, run


s/configure/change/

anthonyeleven · 2023-06-08T21:02:51Z

doc/rados/operations/placement-groups.rst

-   run the below if the ``.mgr`` pool should be constrained to ``ssd`` devices:
+   If the ``ceph osd pool autoscale-status`` command returns no output at all,
+   there is probably at least one pool that spans multiple CRUSH roots.  This
+   'spanning pool' issue can happen because of scenarios like the following:


s/because of/in/

anthonyeleven · 2023-06-08T21:03:30Z

doc/rados/operations/placement-groups.rst

-This will result in a small amount of backfill traffic that should complete
-quickly.
+   This intervention will result in a small amount of backfill traffic, but
+   typically this traffic completes quickly.


s/traffic//

anthonyeleven · 2023-06-08T21:04:00Z

doc/rados/operations/placement-groups.rst

-those adjustments are made.
+When a cluster or pool is first created, it consumes only a small fraction of
+the total cluster capacity and appears to the system as if it should need only
+a small number of PGs. However, in most cases, cluster administrators know


s/most/some/

colemitchell · 2023-06-09T02:04:16Z

doc/rados/operations/placement-groups.rst

+  as specified by the administrator) to the expected storage of all other pools
+  that have target ratios set.  If both ``target_size_bytes`` and
+  ``target_size_ratio`` are specified, then ``target_size_ratio`` takes
+  precedence.


@anthonyeleven - There were a few sentences we were a little uncertain about. This ("If both...") was one. It originally read: "If both target size bytes and ratio are specified, the ratio takes precedence." Does this revision look okay to you? Thanks for your help.

Honestly the autoscaler is a mystery to me so I have no idea :-/

colemitchell · 2023-06-09T02:04:23Z

doc/rados/operations/placement-groups.rst

+     size set.
+
+  #. Normalizing the target ratios among pools that have target ratio set so
+     that collectively they target the other pools. For example, four pools


@anthonyeleven - There were a few sentences we were a little uncertain about. This ("Normalizing...") was one. It originally read: "Normalizing the target ratios among pools with target ratio set so they collectively target the rest of the space." Does this revision look okay to you? Thanks for your help.

I think maybe "collectively target cluster capacity"

Accepted with minor modification.

colemitchell · 2023-06-09T02:04:31Z

doc/rados/operations/placement-groups.rst

+  pool is working towards. 
+
+- **NEW PG_NUM** (if present) is the value that the system is recommending the
+  ``pg_num`` of the pool to be changed to. It is always a power of 2, and it is


@anthonyeleven - There were a few sentences we were a little uncertain about. This ("NEW PG_NUM (if present)...") was one. It originally read: "NEW PG_NUM, if present, is what the system believes the pool's pg_num should be changed to." Does this revision look okay to you? Thanks for your help.

This is basically just a formatting improvement? LGTM. I think the if present reflects changes in behavior between releases -- there are more columns now than when the autoscaler first was introduced.

Edit doc/rados/operations/placement-groups.rst. https://tracker.ceph.com/issues/58485 Co-authored-by: Anthony D'Atri <anthony.datri@gmail.com> Co-authored-by: Cole Mitchell <cole.mitchell.ceph@gmail.com> Signed-off-by: Zac Dover <zac.dover@proton.me>

zdover23 · 2023-06-09T13:41:04Z

#51984 - Reef backport
#51985 - Quincy backport

zdover23 requested review from a team as code owners June 8, 2023 18:55

github-actions bot added core documentation labels Jun 8, 2023

anthonyeleven approved these changes Jun 8, 2023

View reviewed changes

colemitchell reviewed Jun 9, 2023

View reviewed changes

zdover23 force-pushed the wip-doc-2023-06-09-rados-operations-placement-groups-1-of-x branch from 9eb6d1d to d6e1116 Compare June 9, 2023 13:13

zdover23 merged commit 1e3835a into ceph:main Jun 9, 2023
11 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc/rados: edit placement-groups.rst (1 of x) #51975

doc/rados: edit placement-groups.rst (1 of x) #51975

zdover23 commented Jun 8, 2023 •

edited

anthonyeleven left a comment

anthonyeleven Jun 8, 2023

zdover23 Jun 9, 2023

anthonyeleven Jun 8, 2023

zdover23 Jun 9, 2023

anthonyeleven Jun 8, 2023

zdover23 Jun 9, 2023

anthonyeleven Jun 8, 2023

zdover23 Jun 9, 2023

anthonyeleven Jun 8, 2023

zdover23 Jun 9, 2023

anthonyeleven Jun 8, 2023

zdover23 Jun 9, 2023

colemitchell Jun 9, 2023

anthonyeleven Jun 9, 2023

colemitchell Jun 9, 2023

anthonyeleven Jun 9, 2023

zdover23 Jun 9, 2023

colemitchell Jun 9, 2023

anthonyeleven Jun 9, 2023

zdover23 commented Jun 9, 2023

doc/rados: edit placement-groups.rst (1 of x) #51975

doc/rados: edit placement-groups.rst (1 of x) #51975

Conversation

zdover23 commented Jun 8, 2023 • edited

Contribution Guidelines

Checklist

anthonyeleven left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zdover23 commented Jun 9, 2023

zdover23 commented Jun 8, 2023 •

edited