Re: [pve-devel] [PATCH docs v1] package repos: revise Ceph section, introduce 2 attributes

[Aaron Lauterer <a.lauterer@proxmox.com>]

Overall, a nice overhaul to make the section a lot easier to grasp. 
Thanks! A bit more content wise inline.

On  2025-02-10  11:36, Alexander Zeidler wrote:
> * Remove duplicated text to maintain clarity
> * Mention available installation methods (web-based wizard, CLI tool)
> * Create a table to see the support state of Ceph releases
> * List and link to the EOL dates of Ceph releases
> * Reword the descriptions of available PVE repositories
> 
> * Add two new attributes to avoid manual editing multiple lines
> ** debian-codename=bookworm
>     It seems that the codename is not available in the build process,
>     so updating the new attribute on Debian major release upgrades may
>     be fine.
> ** pve-version=8
>     While `revnumber` ("8.3.1") is made available by the current build
>     process, it is not as suitable as only mentioning the major version
>     number.
> 
> Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
> ---
>   asciidoc/asciidoc-pve.conf |   2 +
>   pve-package-repos.adoc     | 165 ++++++++++++++-----------------------
>   2 files changed, 63 insertions(+), 104 deletions(-)
> 
> diff --git a/asciidoc/asciidoc-pve.conf b/asciidoc/asciidoc-pve.conf
> index 0c28298..8ad635f 100644
> --- a/asciidoc/asciidoc-pve.conf
> +++ b/asciidoc/asciidoc-pve.conf
> @@ -3,6 +3,8 @@
>   proxmoxGmbh=Proxmox Server Solutions GmbH
>   copyright=Proxmox Server Solutions GmbH
>   pve=Proxmox VE
> +pve-version=8
> +debian-codename=bookworm
>   pricing-url=https://proxmox.com/en/proxmox-virtual-environment/pricing
>   website=https://www.proxmox.com/
>   forum-url=https://forum.proxmox.com/
> diff --git a/pve-package-repos.adoc b/pve-package-repos.adoc
> index c831cd9..e0a9fb5 100644
> --- a/pve-package-repos.adoc
> +++ b/pve-package-repos.adoc
> @@ -24,6 +24,7 @@ security updates, bug fixes and new features.
>   APT Repositories are defined in the file `/etc/apt/sources.list` and in `.list`
>   files placed in `/etc/apt/sources.list.d/`.
>   
> +[[repository_management]]
>   Repository Management
>   ^^^^^^^^^^^^^^^^^^^^^
>   
> @@ -120,133 +121,90 @@ deb http://download.proxmox.com/debian/pve bookworm pvetest
>   WARNING: The `pvetest` repository should (as the name implies) only be used for
>   testing new features or bug fixes.
>   
> -[[sysadmin_package_repositories_ceph]]
> -Ceph Squid Enterprise Repository
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -
> -This repository holds the enterprise {pve} Ceph 19.2 Squid packages. They are
> -suitable for production. Use this repository if you run the Ceph client or a
> -full Ceph cluster on {pve}.
> -
> -.File `/etc/apt/sources.list.d/ceph.list`
> -----
> -deb https://enterprise.proxmox.com/debian/ceph-squid bookworm enterprise
> -----
> -
> -
> -Ceph Squid No-Subscription Repository
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -
> -This Ceph repository contains the Ceph 19.2 Squid packages before they are moved
> -to the enterprise repository and after they where on the test repository.
> -
> -NOTE: It's recommended to use the enterprise repository for production
> -machines.
> -
> -.File `/etc/apt/sources.list.d/ceph.list`
> -----
> -deb http://download.proxmox.com/debian/ceph-squid bookworm no-subscription
> -----
> -
> -
> -Ceph Squid Test Repository
> -~~~~~~~~~~~~~~~~~~~~~~~~~~
> -
> -This Ceph repository contains the Ceph 19.2 Squid packages before they are moved
> -to the main repository. It is used to test new Ceph releases on {pve}.
> -
> -.File `/etc/apt/sources.list.d/ceph.list`
> -----
> -deb http://download.proxmox.com/debian/ceph-squid bookworm test
> -----
>   
> -Ceph Reef Enterprise Repository
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +[[sysadmin_package_repositories_ceph]]
> +Ceph Repositories
> +~~~~~~~~~~~~~~~~~
>   
> -This repository holds the enterprise {pve} Ceph 18.2 Reef packages. They are
> -suitable for production. Use this repository if you run the Ceph client or a
> -full Ceph cluster on {pve}.
> +The optional use of xref:chapter_pveceph[Ceph] requires a configured
> +Ceph repository. Start by deciding on a recent Ceph release from the
> +table below and perform the initial setup conveniently using the
> +xref:pve_ceph_install_wizard[web-based wizard or the CLI tool].

The "conveniently" sounds a bit too much like a cheap sales pitch to me 
;). I guess we can avoid such language.
Also, one does not need to select a ceph repo before installing ceph 
since it will always be set (explicit or defaults) when running the 
installation wizard or `pveceph install` and will overwrite what was set 
before.

We could probably explain why with PVE 8 there is always a Ceph 
repository configured, even if Ceph isn't used in an HCI fashion.

IIRC: Without our own Ceph repos, the default Debian Ceph packages would 
be used if one wants to connect to an external Ceph cluster. Those 
packages might be too old and did cause issues in some situations in the 
past.
By having a default Proxmox Ceph repo defined, we have more current RBD 
and CephFS client packages than what we would get from upstream Debian.

>   
> -.File `/etc/apt/sources.list.d/ceph.list`
> -----
> -deb https://enterprise.proxmox.com/debian/ceph-reef bookworm enterprise
> -----
> +NOTE: Only the listed Ceph releases are supported in {pve}
> +{pve-version} in a hyper-converged setup (Ceph cluster runs on {pve}
> +cluster). If your {pve} cluster is not on version {pve-version} yet,
> +make sure to upgrade Ceph to one of its supported releases in advance.
> +See the respective {webwiki-url}Category:Ceph_Upgrade[upgrade guide]
> +for details.

I would refer to the upgrade guide of PVE 7 -> 8. It contains all the 
necessary info regarding Ceph upgrades for the PVE upgrade.

>   
> +[caption=""]
> +.Ceph Releases in {pve} {pve-version}
> +[cols="<,^,^,^"]
>   
> -Ceph Reef No-Subscription Repository
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +:t: tech-review
> +:r: recommended
> +:a: available

I am not sure if we want to have it in such detail. But @Thomas might 
have an opinion on this, as it will mean a bit more work if we mark a 
new version as stable and maybe the new default in the install wizard.

Also, squid is not a tech-preview anymore if the ceph install wizard is 
any indication.

>   
> -This Ceph repository contains the Ceph 18.2 Reef packages before they are moved
> -to the enterprise repository and after they where on the test repository.
> +|===
> +|                     |**`ceph-squid`**     |**`ceph-reef`**      |**`ceph-quincy`**
> +|{cephdocs-url}/releases/[Estimated End-of-Life]
> +                      |2026-09 (v19.2)      |2025-08 (v18.2)      |2025-01 (v17.2)
> +|**`enterprise`**     |{t}                  |{r}                  |{a}
> +|**`no-subscription`**|{a}                  |{a}                  |{a}
> +|**`test`**           |{a}                  |{a}                  |{a}
> +|===>
> -NOTE: It's recommended to use the enterprise repository for production
> -machines.
> +.Repositories for {pve} {pve-version}
>   
> -.File `/etc/apt/sources.list.d/ceph.list`
> -----
> -deb http://download.proxmox.com/debian/ceph-reef bookworm no-subscription
> -----
> +Choose one of the following repositories during the initial Ceph
> +setup. Subsequent changes can be made via web interface in the
> +__xref:repository_management[Repository]__ panel or by manually
> +editing the `deb` line in the file
> +`/etc/apt/sources.list.d/ceph.list` .
>   
> +====
> +**`enterprise`**
>   
> -Ceph Reef Test Repository
> -~~~~~~~~~~~~~~~~~~~~~~~~~
> +This repository is recommended for production use and contains the
> +most stable packages. It is accessible if the {pve} node has a valid
> +subscription of any level. For details and included customer support
> +levels visit:
>   
> -This Ceph repository contains the Ceph 18.2 Reef packages before they are moved
> -to the main repository. It is used to test new Ceph releases on {pve}.
> +{pricing-url}
>   
> -.File `/etc/apt/sources.list.d/ceph.list`
> +[subs="attributes"]
>   ----
> -deb http://download.proxmox.com/debian/ceph-reef bookworm test
> +deb https://enterprise.proxmox.com/debian/&lt;ceph-release&gt; {debian-codename} enterprise

could we maybe add one full example to make it clear that the ceph 
release part is  "ceph-..."?
I think there might be some chance for confusion without it :)



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel