[pve-devel] [PATCH docs v2] package repos: revise Ceph section

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

- Start by mentioning the preconfigured Ceph repository and what options
  there are for using Ceph (HCI and external cluster)
- Link to available installation methods (web-based wizard, CLI tool)
- Describe when and how to upgrade
- Add new attributes to avoid manual editing multiple lines
- Create a table as an overview of Ceph release availability,
  maintaining clarity and avoiding duplicated text for each release
- Add a TODO describing what to update occasionally
- List and link to the estimated EOL dates of Ceph releases
- Revise the descriptions of available repository components
- Mention when it makes sense to edit a repository file manually

Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
---
v2:
- Revise several parts of v1 and update commit message
- Rebase on current master
- Implemented Aaron's suggestions from v1
- Ceph releases are now rows instead of columns in the table so that
  they can be easily updated.

v1: https://lore.proxmox.com/pve-devel/20250210103644.3-1-a.zeidler@proxmox.com/


 pve-package-repos.adoc | 134 +++++++++++++++++++++++++++++------------
 1 file changed, 97 insertions(+), 37 deletions(-)

diff --git a/pve-package-repos.adoc b/pve-package-repos.adoc
index 96e00bf..0d98372 100644
--- a/pve-package-repos.adoc
+++ b/pve-package-repos.adoc
@@ -26,6 +26,7 @@ single-line format and in `.sources` files placed in `/etc/apt/sources.list.d/`
 for the modern deb822 multi-line format, see
 xref:sysadmin_apt_repo_formats[Repository Formats] for details.
 
+[[_repository_management]]
 Repository Management
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -162,68 +163,128 @@ Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
 WARNING: The `pve-test` 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}.
+[[sysadmin_package_repositories_ceph]]
+Ceph Repositories
+~~~~~~~~~~~~~~~~~
+
+Ceph-related packages are kept up to date with a preconfigured Ceph enterprise
+repository. Preinstalled packages enables connecting to an external Ceph
+cluster and adding its xref:ceph_rados_block_devices[RBD] or
+xref:storage_cephfs[CephFS] pools as storage. You can also build a
+xref:chapter_hyper_converged_infrastructure[hyper-converged infrastructure (HCI)]
+by running xref:chapter_pveceph[Ceph] on top of the {pve} cluster.
+
+To read the latest version of the admin guide for your {pve} release, make sure
+that all system updates are installed and that this page has been reloaded.
+
+Information from this chapter is helpful in the following cases:
+
+Installing Ceph to build an HCI::
+Decide on a below described repository and recent Ceph release, which you can
+then select in the xref:pve_ceph_install_wizard[web-based wizard or the CLI tool].
+
+Already running the HCI and want to upgrade to the succeeding _Ceph_ major release::
+Please follow the related {webwiki-url}Category:Ceph_Upgrade[Ceph upgrade guide].
+
+Already running the HCI and want to upgrade to the succeeding _{pve}_ major release::
+In an HCI each {pve} major release requires a corresponding minimum Ceph major
+release, please follow the related
+{webwiki-url}Category:Upgrade[{pve} upgrade guide].
+
+Not running an HCI but using an external Ceph cluster::
+To install newer packages used to connect to Ceph, apply available system
+updates, decide on a below described repository and Ceph release, add it to
+your node via the __xref:_repository_management[Repository]__ panel, apply
+newly available system updates, verify the result by running `ceph --version`
+and disable the old Ceph repository.
+
+//TODO: At Ceph or PVE release changes, update:
+//      - below variables (used in below headings and example ceph.sources files)
+//      - the Ceph release table
+:pve-version: 9
+:ceph-release: ceph-squid
+:suite: trixie
+
+[caption=""]
+.Ceph releases available in {pve} {pve-version}
+[cols="<8,^8,^6,^7,^5"]
+
+:u: unreleased
+:t: tech preview
+:a: available
+:r: recommended
+|===
+|                   |{cephdocs-url}/releases/[Estimated End-of-Life]
+                                    |**`enterprise`**|**`no-subscription`**|**`test`**
+|**`ceph-tentacle`**|            {u}|{u}|{u}|{u}
+|**`ceph-squid`**   |2026-09 (v19.2)|{r}|{a}|{a}
+|===
+
+.Ceph repositories for {pve} {pve-version}
+
+Below content of the `ceph.sources` file serves as a reference (prior to {pve}
+9 the file `ceph.list` was used). To make changes, please use the methods
+described above. If you have disabled a repository in the web UI and also want
+to delist it, you can manually remove the corresponding lines from the file.
+
+====
+**`enterprise`**
+
+This repository is recommended for production use and contains the
+most stable package versions. It is accessible if the {pve} node has a
+valid subscription of any level. For details and included customer
+support levels visit:
+
+{pricing-url}
 
 .File `/etc/apt/sources.list.d/ceph.sources`
+[subs="attributes"]
 ----
 Types: deb
-URIs: https://enterprise.proxmox.com/debian/ceph-squid
-Suites: trixie
+URIs: https://enterprise.proxmox.com/debian/{ceph-release}
+Suites: {suite}
 Components: enterprise
 Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
 ----
+====
 
+====
+**`no-subscription`**
 
-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.
+This repository is suitable for testing and for non-production use. It
+is freely accessible and does not require a valid subscription. After
+some time, its package versions are also made available in the
+enterprise repository.
 
 .File `/etc/apt/sources.list.d/ceph.sources`
+[subs="attributes"]
 ----
 Types: deb
-URIs: http://download.proxmox.com/debian/ceph-squid
-Suites: trixie
+URIs: http://download.proxmox.com/debian/{ceph-release}
+Suites: {suite}
 Components: no-subscription
 Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
 ----
+====
 
+====
+**`test`**
 
-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}.
+Warning, this repository is not intended for production use! It
+contains the latest package versions and is primarily used by
+developers to test new features and bug fixes.
 
 .File `/etc/apt/sources.list.d/ceph.sources`
+[subs="attributes"]
 ----
 Types: deb
-URIs: http://download.proxmox.com/debian/ceph-squid
-Suites: trixie
+URIs: http://download.proxmox.com/debian/{ceph-release}
+Suites: {suite}
 Components: test
 Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
 ----
-
-Older Ceph Repositories
-~~~~~~~~~~~~~~~~~~~~~~~
-
-{pve} 9 doesn't support Ceph Reef, Ceph Quincy, or even older releases for
-hyper-converged setups. For those releases, you need to first upgrade Ceph to a
-newer release before upgrading to Proxmox VE 9.
-
-See the respective
-https://pve.proxmox.com/wiki/Category:Ceph_Upgrade[upgrade guide] for details.
-
+====
 
 [[sysadmin_debian_firmware_repo]]
 Debian Firmware Repository
@@ -254,7 +315,6 @@ NOTE: Modernizing your package repositories is recommended. Otherwise, `apt` on
 Debian Trixie will complain. You can run `apt modernize-sources` to do so.
 
 [[repos_secure_apt]]
-
 SecureApt
 ~~~~~~~~~
 
-- 
2.47.2



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