Re: [PATCH docs v2 5/5] cephx-migration: Simplify docs

[Thomas Lamprecht <t.lamprecht@proxmox.com>]

Am 08.09.26 um 17:39 schrieb Maximiliano Sandoval:
> This is an already complex migration, simply reducing the word count can be
> helpful.
> 
> - The helper is verbose already, there is no need to document here what it is
>   (not) going to do or print.
> - No need to mention that client.admin and storage keys are unchanged, this is
>   the content of the next section.
> 
> Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
> ---
>  pveceph.adoc | 41 +++++++++++++++++++----------------------
>  1 file changed, 19 insertions(+), 22 deletions(-)
> 
> diff --git a/pveceph.adoc b/pveceph.adoc
> index 9eba9b3..038eb7d 100644
> --- a/pveceph.adoc
> +++ b/pveceph.adoc
> @@ -1330,19 +1330,19 @@ as the mute lasts.
>  Migrate Cephx Keys from `aes` to `aes256k`
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -This section explains how to migrate the cluster-owned keys and the keys of
> -compatible Ceph users from `aes` to `aes256k`. For an explanation of Ceph
> -users, tickets, and key storage, see
> +This section explains how to migrate Ceph user authentication keys from `aes` to
> +`aes256k`. For an explanation of Ceph users, tickets, and key storage, see
>  xref:pveceph_cephx_how_it_works[Cephx Authentication].
>  
>  Why the Health Checks Appear
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>  
>  Ceph Squid 19.2.6 and Ceph Tentacle 20.2.4 add health checks for keys and
> -temporary access credentials that use the older `aes` encryption method. The
> -checks can therefore appear directly after an upgrade even if the cluster
> -worked without warnings before. The older method is affected by
> +temporary access credentials that use the older `aes` encryption method which is
> +affected by
>  https://docs.ceph.com/en/latest/security/CVE-2025-30156['CVE-2025-30156'].
> +
> +The warnings can therefore appear after upgrading a previously healthy cluster.
>  See the upstream release announcement for background footnote:[Ceph: Squid
>  v19.2.6 and Tentacle v20.2.4 released
>  https://ceph.io/en/news/blog/2026/v20-2-4-v19-2-6-combo-released/].
> @@ -1358,8 +1358,8 @@ Migration Steps
>  {pve} offers a helper which can handle the migration. The following steps can be
>  performed on a single node.
>  
> -Reruns do not rotate completed keys again. After each run, invoke the helper

I added the sentence about reruns not rotating keys again deliberately, after
triple-checking if it actually holds up in practice myself when running into
an edge case on a production cluster, and I then figured some users will wonder
about this being idempotent here, as a another key rotation could mess things
up bad at the wrong step, and just betting on us doing the right thing without
any indicator seems rather nerve racking in such situations.

> -without options to check the current state and follow the next steps it prints.
> +Between runs, invoke the helper without options to check the current state and
> +follow the next steps it prints.
>  
>  .Before You Begin
>  * Upgrade all cluster nodes to the latest {pve} packages. In particular,
> @@ -1404,11 +1404,10 @@ If the plan reports no blocker, apply the same selection:
>  /usr/share/pve-manager/migrations/pve-cephx-rotate-service-keys --rotate-cluster-keys --apply
>  ----
>  
> -The helper rotates the manager, metadata server, OSD, monitor, bootstrap, crash,
> -and xref:pveceph_cephx_lockbox[encrypted OSD lockbox keys]. It restarts services
> -one at a time when needed, including monitors. Storage-user keys and
> -`client.admin` stay unchanged, existing tickets remain valid, and the old
> -cipher stays enabled.

I mine fine I guess, but I got a hard time figuring where explicitly stating
that the client keys stay unchanged here is really confusing anybody.


> +The helper rotates the keys of cluster services, and the
> +xref:pveceph_cephx_lockbox[encrypted OSD lockbox keys]. It restarts services
> +sequentially when needed. Existing tickets remain valid, and the old cipher
> +stays enabled.
>  
>  After Ceph updates its health status, the two error-severity checks clear. The
>  warning about rotating service keys can remain for a few hours and clears
> @@ -1423,11 +1422,10 @@ disconnected and external clients. If any affected client is incompatible or
>  unknown, leave its user's key unchanged and postpone this step.
>  
>  .Stage the keys
> -Use `--rotate-all-storage-keys` for the dedicated users of managed local RBD
> -and CephFS storages, together with `--rotate-admin-key` for `client.admin`,
> -which the command line and storages without their own user share. Every
> -client of these users is affected; storages of external clusters are
> -excluded.
> +Use `--rotate-all-storage-keys` for users of RBD and CephFS storages managed by
> +{pve}, together with `--rotate-admin-key` for `client.admin`, shared by the API
> +and storages without a dedicated user. Every client of these users is
> +affected; storages of external clusters are excluded.
>  
>  The helper stages each new key and writes it to the managed keyring and secret
>  files. Both keys remain valid until confirmation, allowing clients to refresh
> @@ -1464,7 +1462,7 @@ until confirmation makes the new key current and invalidates the old one.
>  * The helper refreshes idle CephFS mounts and leaves busy or unresponsive
>    mounts alone. Once nothing uses them, rerun the helper with `--apply` to
>    retry the outstanding mounts.
> -* For clients outside {pve}, distribute the staged credential from the
> +* For external clients, distribute the staged credential from the
>    xref:pveceph_cephx_external_copies[managed key files], then restart or remount
>    those clients.
>  
> @@ -1476,7 +1474,7 @@ and external key copies yourself.
>  3. Finish or Pause the Migration
>  ++++++++++++++++++++++++++++++++
>  
> -Run a final dry run to check for remaining old-key sessions. It offers a
> +Run a dry run to check for remaining old-key sessions. It offers a
>  confirmation command when its observed checks pass, but cannot verify
>  disconnected clients or external key copies for you.
>  
> @@ -1504,8 +1502,7 @@ enabled rather than restricting it. You can
>  xref:pveceph_mute_health_check[mute the remaining warnings] while waiting for
>  those clients to upgrade.
>  
> -Use `pveceph auth status` for current and pending key ciphers, as
> -`ceph auth ls` does not list pending keys.
> +Use `pveceph auth status` for current and pending key ciphers.

IMO rather relevant to now that `auth ls` is not complete to remove foot guns.
I.e., sure less docs to read is nice, but only as long as core foot guns and
clarity do not get traded for "word golfing". 

>  
>  NOTE: `/etc/pve/priv/cephx-key-migration.json` records progress and contains
>  secret old keys. Protect it and keep it until the migration is complete and