[pve-devel] [PATCH docs v3] package repos, software updates: revise Ceph section

[pve-devel] [PATCH docs v3] package repos, software updates: revise Ceph section

[Alexander Zeidler]

- 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
- Advise to read the latest version of the corresponding admin guide
- 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

- Mention upgrading Ceph under "System Software Updates"

Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
---
v3:
- Implement v2 suggestions from Max R. Carrara, thank you!
- Add release table anchor for possible future use
- Place the table attributes in a single row
- Move advise of reading the latest admin guide version below the table title
- Unify line lengths
- Mention upgrading Ceph under "System Software Updates"

v2: https://lore.proxmox.com/pve-devel/20250725103532.102255-1-a.zeidler@proxmox.com/t/#u
- 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/t/#u


 pve-package-repos.adoc       | 132 ++++++++++++++++++++++++++---------
 system-software-updates.adoc |   3 +
 2 files changed, 101 insertions(+), 34 deletions(-)

diff --git a/pve-package-repos.adoc b/pve-package-repos.adoc
index 96e00bf..7f1cd04 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,67 +163,131 @@ 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Ceph Repositories
+~~~~~~~~~~~~~~~~~
+
+Ceph-related packages are kept up to date with a preconfigured Ceph enterprise
+repository. Preinstalled packages enable 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.
+
+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 repository and Ceph release listed below, 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
+
+[[ceph_release_table]]
+.Ceph releases available in {pve} {pve-version}
+
+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.
+
+:u: unreleased
+:t: tech preview
+:a: available
+:r: recommended
+
+[caption="", cols="<8,^8,^6,^7,^5"]
+|===
+|                   |{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}
+|===
+
 
-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}.
+.Ceph repositories for {pve} {pve-version}
+
+The content of the `ceph.sources` file below serves as a reference (prior to
+{pve} 9 the file `ceph.list` was used). To make changes, please follow the case
+that applies to your situation as described at the beginning of this
+subchapter. If you have disabled a repository in the web UI and also want to
+delist it, you can manually remove the corresponding entry 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}.
+This repository 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.
+WARNING: The Ceph **`test`** repository should (as the name implies) only be
+used for testing new features or bug fixes.
 
 
 [[sysadmin_debian_firmware_repo]]
@@ -254,7 +319,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
 ~~~~~~~~~
 
diff --git a/system-software-updates.adoc b/system-software-updates.adoc
index 471ff1e..e6bf356 100644
--- a/system-software-updates.adoc
+++ b/system-software-updates.adoc
@@ -13,6 +13,9 @@ updates use the web-based GUI or the following CLI commands:
 # apt-get dist-upgrade
 ----
 
+For occasionally upgrading Ceph to its succeeding major release, see
+xref:sysadmin_package_repositories_ceph[Ceph Repositories].
+
 NOTE: The APT package management system is very flexible and provides many
 features, see `man apt-get`, or <<Hertzog13>> for additional information.
 
-- 
2.47.2



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

[pve-devel] applied: [PATCH docs v3] package repos, software updates: revise Ceph section

[Thomas Lamprecht]

On Wed, 30 Jul 2025 20:02:51 +0200, Alexander Zeidler wrote:
> - 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
> - Advise to read the latest version of the corresponding admin guide
> - 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
> 
> [...]

Applied, thanks!

I commented out the row for tentacle in a follow-up commit for now though, IMO
it can be a tiny bit confusing to have a release listed that's not available
anywhere yet.

[1/1] package repos, software updates: revise Ceph section
      commit: 2b32abd4de672abea44b255586d409deb46b760a


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