Re: [PATCH docs v2 3/5] cephx-migration: Move all requirements into prelude

[Jonas Theisen <j.theisen@proxmox.com>]

On 9/8/26 17:39, Maximiliano Sandoval wrote:
> The migration should start after all requirements are meet.
>
> Note that the script will warn if it is not being run as root. There is no need
> to mention that the script should be run as root.
>
> Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
> ---
>   pveceph.adoc | 51 ++++++++++++++++++++++++++-------------------------
>   1 file changed, 26 insertions(+), 25 deletions(-)
>
> diff --git a/pveceph.adoc b/pveceph.adoc
> index 625768f..40ca16b 100644
> --- a/pveceph.adoc
> +++ b/pveceph.adoc
> @@ -1363,21 +1363,35 @@ Reruns do not rotate completed keys again. After each run, invoke the helper
>   without options to check the current state and follow the next steps it prints.
>   
>   .Before You Begin
> -* Upgrade `pve-manager` to 9.2.17 or newer and install the latest Ceph
> -  packages on every node. Staged client-key rotation requires Ceph
> -  19.2.6-pve3, 20.2.4-pve3, or newer on every monitor. Then complete the
> -  rolling restart of all Ceph services.
> +* Upgrade all cluster nodes to the latest {pve} packages. In particular,
> +  ** `pve-manager` '9.2.17' or newer
> +  ** Ceph '20.2.4-pve3' or newer if using Tentacle
> +  ** Ceph '19.2.6-pve3' or newer if using Squid
> +  ** Kernel 7.0 or newer.
> +* Ensure all external clients are running Ceph and Kernel versions supporting `aes256k`.
> +* Complete a rolling restart of Ceph services.
>   * Resolve health warnings and errors not listed in
> -  xref:pveceph_cephx_health_check_reference[Health Check Reference]. Ensure
> -  every node is reachable over SSH.
> -* Run the helper as `root` on one node only. Do not start another migration,
> -  a rolling restart, or change Ceph keys with other tools while it runs. The
> -  helper's lock does not block direct Ceph authentication commands.
> +  xref:pveceph_cephx_health_check_reference[Health Check Reference].
> +* Ensure every node is reachable over SSH.

Small knit: The trailing full stops are probably unnecessary for a list

Also i would propose to move the "Ensure all external clients [...]"
point to the bottom of the list since this will be the exception.
To reflect this the point could also be formulated like:
"If external clients are accessing the Ceph cluster ensure they support 
'aes256k'"
Imho this would reduce the risk of users getting confused.
> +
> +.Kernel Support Considerations
> +A storage client requires support for `aes256k` in the `rbd` kernel module if:
> +
> +* A container is using a RBD storage.
> +* or, A VM is using a RBD storage, if `krbd` is enabled on the storage configuration.
> +* or, a CephFS is mounted, unless `fuse` is enabled in the storage configuration.
> +
> +Clients requiring kernel support should not downgrade to older kernel versions
> +after the migration.
>   
>   1. Migrate the Cluster-Owned Keys
>   +++++++++++++++++++++++++++++++++
>   
> -Review the cluster-owned migration in the default dry-run mode:
> +WARNING: Do not start another migration, a rolling restart, or change Ceph keys
> +with other tools during the migration. The helper's lock does not block direct
> +Ceph authentication commands.
> +
> +Review the cluster-owned key migration in dry-run mode:
>   
>   [source,bash]
>   ----
> @@ -1405,21 +1419,8 @@ automatically.
>   2. Migrate the Keys of Compatible Ceph Users
>   ++++++++++++++++++++++++++++++++++++++++++++
>   
> -[[pveceph_cipher_support]]
> -.Check compatibility
> -Several workloads can share one Ceph user. Migrate its key only when every
> -client supports `aes256k`, including disconnected and external clients.
> -Ceph programs from the updated {pve} packages support it; kernel clients
> -require a *running* kernel version 7.0 or newer.
> -
> -[cols="2,3",options="header"]
> -|===
> -|Virtual machine with RBD disks |Userspace, unless `krbd` is enabled.
> -|Container on RBD |Always the kernel client.
> -|CephFS mount |Kernel, unless `fuse` is enabled.
> -|===
> -
> -Check external systems too. If any affected client is incompatible or
> +Migrate a user's key only once all its clients support `aes256k`, including
> +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