Suggestion: Publish a centralized compatibility matrix for Foreman releases

Site Feedback
, , , ,
1

Hello,

I would like to suggest a documentation improvement that could help administrators during deployments and upgrades.

During a recent investigation, I discovered that the availability of repositories does not necessarily mean that all versions are intended to be used together.

For example, it was not obvious to me which Candlepin version was expected for a given Foreman/Katello release.

Would it be possible to publish and maintain a centralized compatibility matrix based on the main Foreman release?

Example:

Foreman | Katello | Candlepin | Pulpcore | Java

---------|---------|------------|----------|------

3.19 | 4.21 | 4.7.x | 3.105.x | 17

5.1 | 5.1 | 4.8.x | … | 25

Such a matrix could include:

- Recommended versions

- Supported versions

- Java requirements

- Major component compatibility

I independently assumed that an available repository was also the recommended repository for the selected Foreman/Katello version. A compatibility matrix would have immediately clarified the expected component versions.

Benefits:

- Simplify upgrades

- Reduce version selection mistakes

- Help administrators validate their repository choices

- Improve troubleshooting

- Provide a single reference point for release planning

I believe this would benefit both new and experienced Foreman administrators.

Thank you for considering it.

Regards,

2

The release RPM approach works well for direct installations.

However, enterprises operating mirrors, Content Views, internal repositories or disconnected environments often work at the repository level and may never directly use the release RPMs.

For those administrators, a centralized compatibility reference would be extremely useful.

3

I don’t see anyone maintaining documentation specifically aimed at departing from the supported installation method.

However, if you know where, you can simply look up the source of truth for the official installation method. For example, if you want to know what candlepin and katello repo should be used with Foreman 3.19, see katello_version: and candlepin_version: here: foreman-packaging/package_manifest.yaml at rpm/3.19 · theforeman/foreman-packaging · GitHub

If you want to know the versions for a different Foreman version, then switch to the relevant branch (i.e. rpm/<foreman_version>).

For the pulpcore repo version, see %global pulpcore_version in: foreman-packaging/packages/katello/katello-repos/katello-repos.spec at rpm/3.19 · theforeman/foreman-packaging · GitHub

Not super convenient, but does contain the information you want.

4

Hmm, just realized the candlepin_version in package_manifest.yaml and katello-repos.spec are in disagreement. If I had to guess, I would say that katello-repos.spec is the one you want.

Starting with Foreman/Katello 5.0 the versions for Foreman and Katello will sync up. (That is you will always want Foreman version == Katello version). At that point the only other thing you need is pulpcore and candlepin versions from foreman-packaging/packages/katello/katello-repos/katello-repos.spec at rpm/5.0 · theforeman/foreman-packaging · GitHub

5

Thank you for the clarification.

I think this discussion actually demonstrates why a centralized compatibility reference would be valuable.

As an administrator, I was ultimately able to find the answer, but only after:

- Opening a support topic

- Investigating Java runtime dependencies

- Comparing package versions

- Looking into foreman-packaging

- Learning which branch to inspect

- Identifying the relevant files

- Determining which file was authoritative

- Discovering that the available metadata sources were not fully aligned

At the end of the process, the expected answer was simply:

Foreman 3.19 / Katello 4.21 → Candlepin 4.7

The information clearly exists today, but it required a significant amount of investigation to reach a conclusion that could potentially be expressed in a single line of documentation.

From my perspective, a published compatibility reference would not replace the release RPMs or the packaging metadata. It would simply make the existing knowledge accessible to administrators without requiring them to understand the packaging internals of the project.

The fact that several independent analyses (including experienced administrators) reached the same incorrect assumption based on repository availability suggests that the current discovery path may not be obvious to users.

I think documenting this information explicitly would save time for both users and maintainers.

6

One additional point from an operational perspective:

Foreman and Katello are actively developed projects with frequent releases and upgrades.

For administrators who keep their environments reasonably up to date, these version selection decisions are not one-time events. They are revisited regularly, often several times per year.

In practice, with a roughly quarterly upgrade cadence, administrators may need to review component compatibility up to four times per year.

Without a centralized compatibility reference, each upgrade cycle may require repeating the same investigation:

- Which Katello version matches this Foreman version?

- Which Candlepin version is expected?

- Which Pulpcore version should be used?

- Which Java version is required?

- Which repositories are intended to be enabled together?

The information clearly exists in the packaging metadata and release RPMs, but administrators operating mirrors, Content Views, disconnected environments or internal repository infrastructures may not directly consume those RPMs.

A published compatibility reference would reduce repeated investigation effort and provide a stable validation point for every upgrade cycle.

In my case, several hours of investigation ultimately led to a single compatibility statement:

Foreman 3.19 / Katello 4.21 → Candlepin 4.7

Having that information readily available in the documentation would have avoided the entire troubleshooting process.

7

There is also a community impact aspect.

Without a simple way to determine the expected component versions, administrators can easily end up reporting issues that are not actually software defects but compatibility mistakes.

That is exactly what happened to me.

I genuinely believed I had found a Java/Candlepin compatibility bug because I had no straightforward way to determine that:

Foreman 3.19 / Katello 4.21 → Candlepin 4.7

was the expected combination.

As a consequence:

- I opened a support discussion

- Community members spent time investigating

- Multiple hypotheses were explored

- Several rounds of troubleshooting were performed

In the end, the root cause was not a product defect but an incorrect repository/component combination.

A centralized compatibility reference would not only help administrators, it would also help maintainers by reducing avoidable support requests and apparent bugs caused by unsupported version combinations.

From my perspective, every hour spent maintaining such a reference could save many hours of troubleshooting across the community.

This becomes even more important because upgrades are frequent. Administrators may need to revisit these compatibility decisions several times per year, especially when following the regular Foreman/Katello release cadence.

The information already exists somewhere in the project. The challenge is making it discoverable before users arrive at the wrong conclusion and report issues that turn out to be compatibility mismatches rather than actual bugs.

9

Hello, I think for your use case (which you explained in the other thread) the best option is DNS forwarding or HTTP redirects so our expected URLs simply work? For example:

https://yum.theforeman.org/releases/5.0/el9/x86_64/foreman-release.rpm

If you change your DNS so that yum.theforeman.org points to your mirror and keep the directory structure intact, that will work.

When using Pulp, this might be a challenge, in that case create HTTP rewrite rules that will redirect to the destination.

In any case, you just found one line of the compatibility matrix, maintaining such information is as easy as editing a post on our discourse so feel free to start such thread. Include information on how you mirror our packages and deploy it, that could be very helpful to others.

Cheers!

10

Hello Izap and Community Team,

@Izap Thanks. The DNS/rewrite approach addresses package mirroring and deployment, which is indeed useful.

However, my suggestion is slightly different.

The issue I encountered was not how to mirror or consume the repositories, but how to determine the expected component combination behind a given release.

In my case I incorrectly concluded there might be a Java/Candlepin compatibility problem because I had no straightforward way to verify that:

Foreman 3.19 + Katello 4.21 + Candlepin 4.7

was actually the intended version set.

The information exists today in packaging metadata, but discovering it required a support topic, source code investigation and comparison of multiple metadata sources.

My concern is that other users may reach the same conclusion and open support discussions for compatibility mismatches rather than actual software defects.

A centralized compatibility reference would primarily improve discoverability rather than replace the existing installation method.

Regards,

11

Well, I should explain myself. My point was that once you do what I recommend, then your combination is here:

Change the number in the dropdown in documentation and you always get the correct combination. Copy and paste, it works (because of DNS/rewrites).

Cheers!

12

Thank you for the clarification.

I understand that following the official installation documentation and repository URLs results in the intended component combination.

However, my concern is slightly different.

Why should administrators need to install release RPMs, extract RPM content, inspect packaging repositories, or deploy a test environment simply to determine:

- which repository URLs are expected for a given release,

- which Candlepin version is expected,

- which Pulpcore version is expected,

- or which Java version is required?

In my case, I was not trying to choose component versions manually. I was trying to validate that the repositories I was preparing matched the intended Foreman/Katello release.

I eventually discovered that Foreman 3.19 / Katello 4.21 was intended to use Candlepin 4.7.x rather than Candlepin 4.8.x, but reaching that conclusion required support discussions and investigation of packaging metadata.

My suggestion is therefore about discoverability and validation.

Would it be useful to have an automatically generated reference, derived from existing release metadata, that allows administrators to determine the expected repositories and component versions for a given release without needing to:

- install the software,

- extract RPMs,

- deploy a test environment,

- or inspect packaging internals?

The goal would not be to replace the documented workflow, but to provide a simple way to verify what a particular Foreman/Katello release is expected to consume.

13

I understand, we have nothing for you that I am aware of. Our documentation is the best bet, it is well maintained. It does not contain versions of packages, for that you need to open the URLs with your browser.

Perhaps you can build a simple script that visits the documentation chapter, gets all DNF/DEB repos and fetches metadata to get the full package list.