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

["Alexander Zeidler" <a.zeidler@proxmox.com>]

On Tue Mar 25, 2025 at 4:26 PM CET, Aaron Lauterer wrote:
> Overall, a nice overhaul to make the section a lot easier to grasp. 
> Thanks! A bit more content wise inline.

Thank you for the review! Will prepare a v2, see comments below.

>
> 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.

Will implement the suggestions from above.

>
>>   
>> -.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.

Will implement it.

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

s/review/preview/

>> +: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.

It may also be helpful in the install wizard, when the states from above
are included in the drop-down list.

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

I agree. By the way, while the preview flag has already been dropped,
the wizard still defaults to `reef`:
https://git.proxmox.com/?p=pve-manager.git;a=blob;f=www/manager6/ceph/CephInstallWizard.js;h=c22d5c64bfd6235a54d250de8b25e09c5ea9bd4b;hb=HEAD#l151

>
>>   
>> -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 :)

The following speaks against it:
- Nowadays we have the graphical repository management available, making
  manual editing rather obsolete.
- An example is in the to be edited `/etc/apt/sources.list.d/ceph.list`.
- Otherwise we either need to update the release name from time to time
  or need to specify, for example, a clearly outdated release name.


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