[pve-devel] [PATCH docs] Fix #2015: Improve CephFS docs

[Alwin Antreich]

Signed-off-by: Alwin Antreich <***@proxmox.com>
---
This does not address the package update yet.

pve-storage-cephfs.adoc | 7 +++++++
1 file changed, 7 insertions(+)

diff --git a/pve-storage-cephfs.adoc b/pve-storage-cephfs.adoc
index b7f3f4d..5111ad1 100644
--- a/pve-storage-cephfs.adoc
+++ b/pve-storage-cephfs.adoc
@@ -78,6 +78,13 @@ secret generally requires root privileges. The file must only contain the
secret key itself, opposed to the `rbd` backend which also contains a
`[client.userid]` section.

+A secret can be received from the ceph cluster (as ceph admin) by issuing the
+following command. Replace the `userid` with the actual client ID configured to
+access the cluster. For further ceph user managment see the Ceph docs
+footnote:[Ceph user management http://docs.ceph.com/docs/luminous/rados/operations/user-management/].
+
+ ceph auth get-key client.userid > /etc/ceph/cephfs.secret
+
If Ceph is installed locally on the PVE cluster, i.e., setup with `pveceph`,
this is done automatically.

[Alwin Antreich]

Signed-off-by: Alwin Antreich <***@proxmox.com>
---
pve-storage-cephfs.adoc | 2 ++
pveceph.adoc | 19 +++++++++++++++++++
2 files changed, 21 insertions(+)

diff --git a/pve-storage-cephfs.adoc b/pve-storage-cephfs.adoc
index 5111ad1..3d495fc 100644
--- a/pve-storage-cephfs.adoc
+++ b/pve-storage-cephfs.adoc
@@ -18,6 +18,8 @@ configuring a CephFS storage easier. As recent hardware has plenty of CPU power
and RAM, running storage services and VMs on same node is possible without a
big performance impact.

+To use the CephFS storage you need update the Debian stock Ceph client. For this see xref:pve_ceph_update_client_only[Update Ceph client packages only].
+
[[storage_cephfs_config]]
Configuration
~~~~~~~~~~~~~
diff --git a/pveceph.adoc b/pveceph.adoc
index 68399ad..48901aa 100644
--- a/pveceph.adoc
+++ b/pveceph.adoc
@@ -106,6 +106,25 @@ pveceph install
This sets up an `apt` package repository in
`/etc/apt/sources.list.d/ceph.list` and installs the required software.

+[[pve_ceph_update_client_only]]
+Update Ceph client packages only
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you would like to only update the default shipped ceph client, you can add
+Proxmox's Ceph repository by hand and run an `apt update`, followed by an `apt
+dist-upgrade` to get the latest supported Ceph client packages from Proxmox.
+
+Open a terminal on the respective Proxmox VE node and run the following line as
+root. This will add Proxmox's Ceph repository.
+
+[source,bash]
+----
+echo deb http://download.proxmox.com/debian/ceph-luminous stretch main > /etc/apt/sources.list.d/ceph.list
+----
+
+You need to make sure that there is no other Ceph repository configured,
+otherwise the installation will fail or there will be different package
+versions on the node, leading to unexpected behavior.
+

Creating initial Ceph configuration
-----------------------------------

[Thomas Lamprecht]

Post by Alwin Antreich
---
pve-storage-cephfs.adoc | 2 ++
pveceph.adoc | 19 +++++++++++++++++++
2 files changed, 21 insertions(+)
diff --git a/pve-storage-cephfs.adoc b/pve-storage-cephfs.adoc
index 5111ad1..3d495fc 100644
--- a/pve-storage-cephfs.adoc
+++ b/pve-storage-cephfs.adoc
@@ -18,6 +18,8 @@ configuring a CephFS storage easier. As recent hardware has plenty of CPU power
and RAM, running storage services and VMs on same node is possible without a
big performance impact.
+To use the CephFS storage you need update the Debian stock Ceph client. For this see xref:pve_ceph_update_client_only[Update Ceph client packages only].

please break long lines

Post by Alwin Antreich
+
[[storage_cephfs_config]]
Configuration
~~~~~~~~~~~~~
diff --git a/pveceph.adoc b/pveceph.adoc
index 68399ad..48901aa 100644
--- a/pveceph.adoc
+++ b/pveceph.adoc
@@ -106,6 +106,25 @@ pveceph install
This sets up an `apt` package repository in
`/etc/apt/sources.list.d/ceph.list` and installs the required software.
+[[pve_ceph_update_client_only]]
+Update Ceph client packages only
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you would like to only update the default shipped ceph client, you can add
+Proxmox's Ceph repository by hand and run an `apt update`, followed by an `apt
+dist-upgrade` to get the latest supported Ceph client packages from Proxmox.
+
+Open a terminal on the respective Proxmox VE node and run the following line as
+root. This will add Proxmox's Ceph repository.
+
+[source,bash]
+----
+echo deb http://download.proxmox.com/debian/ceph-luminous stretch main > /etc/apt/sources.list.d/ceph.list
+----

why not add our ceph repo to our pve-package-repository, so that we have them
all in one place, belonging together, and do not forget to bump one version, for
a theoretical pve 6.X buster and mimic, nautilus, whatsoever.

Then you could write here just that one needs to setup our ceph repo [linking to
the new pve-package-repo section] and need to do an update/upgrade cycle.

Post by Alwin Antreich
To use the CephFS storage you need update the related packages to at least XYZ and
at best to the same version yourt server uses. For Luminous you can use our tested
packages by adding our Ceph repository and running an `apt update` `apt dist-upgrade`
cycle.

needs wording/grammar fixes but this then would be valid for external ceph server
setups and ours and contains repository info in one place, where mentioning Ceph
would've been nice either way.

Post by Alwin Antreich
+
+You need to make sure that there is no other Ceph repository configured,
+otherwise the installation will fail or there will be different package
+versions on the node, leading to unexpected behavior.
+
Creating initial Ceph configuration
-----------------------------------

[Thomas Lamprecht]

a bit more meaningful title is always nice:

partially-fix #2015: cephfs: document how a ceph auth key

Post by Alwin Antreich
---
This does not address the package update yet.
pve-storage-cephfs.adoc | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/pve-storage-cephfs.adoc b/pve-storage-cephfs.adoc
index b7f3f4d..5111ad1 100644
--- a/pve-storage-cephfs.adoc
+++ b/pve-storage-cephfs.adoc
@@ -78,6 +78,13 @@ secret generally requires root privileges. The file must only contain the
secret key itself, opposed to the `rbd` backend which also contains a
`[client.userid]` section.
+A secret can be received from the ceph cluster (as ceph admin) by issuing the
+following command. Replace the `userid` with the actual client ID configured to
+access the cluster. For further ceph user managment see the Ceph docs
+footnote:[Ceph user management http://docs.ceph.com/docs/luminous/rados/operations/user-management/].
+
+ ceph auth get-key client.userid > /etc/ceph/cephfs.secret

Sorry if I overlook something, but why do you pipe it to /etc/ceph/cephfs.secret ??

Would it not make more sense to advise something like:

***@cephServer# ceph auth get-key client.USERID > USERID.secret
***@cephServer# scp USERID.secret PVE-HOST:/etc/pve/priv/ceph/SID.secret

As this is what's actually needed?

Post by Alwin Antreich
+
If Ceph is installed locally on the PVE cluster, i.e., setup with `pveceph`,
this is done automatically.