Correct https://docs.theforeman.org/ is a pretty good resource - it is the official Red Hat docs open sourced for the Foreman community. However, we have not solved some problems yet. For example, how do we bring everything that exists together? How to we change the style of the manuals vs user-scenario driven docs etc.
Another problem that really hasn’t been solved is supporting all operating systems that Foreman support. I still regard it as Katello documentation that is slowly gaining docs for other cases.
A difference is also in the definition of supported. For Red Hat customers supported means you can call Red Hat support for it and they’ll help you solve it. In upstream isn’t strictly defined. It can be “it’s known to work” or “it should work and it’s a bug if it doesn’t”. Many things can be made to work and if it doesn’t, people may still help you with fixing it. Is that supported? There is no guarantee that it’ll continue to work in the future.
Personally I love the freedom that it gives me but I’m not scared to dive into the code to fix things when they don’t comply with what I want, others may not. That’s the ever lasting challenge with documenting an open source project.
Do you have any suggestions for how we can improve this? The docs origin in the Red Hat downstream makes it understandable that there is a lot of Katello scenarios embedded in it. I put out a call for help in rewriting a Debian version of the installation guides, but despite good intent and a lot of effort, we didn’t have the correct eyes on this to make it a success. These docs are as open to contributions as any other part of Foreman. The asciidoc allows a flexibility where we could pull together Foreman-only manuals if necessary and if correctly guided. For now, myself and the others involved went to great lengths to review and to mark every action that cannot be completed without Katello as a note. I’m confident that while there are a lot of Katello scenarios in there, no one will be misled into trying something without knowing Katello is needed. In place of an alternative, I’m not sure is this so problematic. The feedback on these guides so far has been overwhelmingly positive from new users.
I did a quick search and there are, in most guides, under 10 mentions of support, and a lot of these are with regards to the Foreman context. Would a note defining what support means in the Foreman context added to the beginning of every guide solve this?
I suppose I hope that every Foreman user will feel this eventually. You’ve reached the summit. It’d be hard to find someone who knows the ins and outs more than you. As someone who has spent the last ten years trying to provide an entry point for the lowest common denominator of user, I see the need to provide opinionated scaffolding, and I do think that these guides, which I link to almost weekly to guide new users on Discourse or on Freenode, do provide some value.
These guides are, for certain, not without their problems, but perhaps with some suggestions/opinions, we can provide at least the entry point with which to gain confidence, then paths to greater expertise.
This probably comes across as an off topic rant, but I just hope to illustrate my issues with the new documentation effort. I also know it’s also a lot easier to point out problems than to come up with solutions.
A big problem is that the guides from downstream are often so focused at EL 7 and Katello that you end up scrapping half of the document (or more).
Let’s take an example and look at the planning guide. Right of the bat, the System Architecture diagram for vanilla Foreman is wrong. There is no Life Cycle Management, you don’t pull content from the RH Portal, Puppet, Docker etc. There are no Red Hat Analytics. That means the upper 2/3 of the diagram must be dropped. Then it doesn’t mention configuration management and reporting, which are core features.
That was just the diagram that drew my attention. If we read the text, it states:
Foreman Server synchronizes the content from Red Hat Customer Portal and other sources
That is a Katello feature.
Foreman Smart Proxy server mirrors content from Foreman Server to facilitate content federation across various geographical locations. Host systems can pull content
Again, Katello feature
Smart Proxy servers decrease the load on the central server, increase redundancy, and reduce bandwidth usage.
IMHO not why you use a Smart Proxy and I think on a conceptual level even the wrong thing. It doesn’t reduce load, it allows you to provide access in different network segments. Also why I think the whole document on Configuring Smart Proxies with a Load Balancer is wrong at a conceptual level.
If you really want to scale out Puppet, I would take a completely different approach: you scale out Pupppet itself (following their scaling guides) and deploy a single Smart Proxy pointing at it. Since Puppet 6 we can use the REST API and this is a good way.
Scaling out DNS should also be done outside of the actual Smart Proxy server but depends on the DNS server that’s used. Often you will end up deploying the Smart Proxy server as a hidden master and let a bunch of other servers serve the actual DNS requests.
For DHCP it also depends on the exact server implementation. With ISC DHCP you can configure a failover server, MS DHCP has built in replication via Active Directory, Infoblox probably also has their own solution.
The architecture diagrams also wrong to the point I would strongly recommend vanilla Foreman users to not look at them. The whole concept of an internal capsule doesn’t really exist within Foreman. Every Smart Proxy is the same. There may be one that’s deployed on the same host as Foreman, but this is completely optional. The Smart Proxy runs on port 8443, not 9090. There is no Pulp, qpid, Candlepin.
This is the reason I didn’t start to contribute Debian docs: once you start, you end up having comments about every paragraph.
In the upstream documentation I would avoid the word support as much as possible. Instead of saying Foreman supports PostgreSQL 10 or higher, I would use requires.
Now that’s actually a good example. Red Hat on recent versions only supports PostgreSQL 12 but upstream is compatible with version 10 (shipped by Ubuntu 18.04).
Now for solutions: we are working on making Katello more a part of the regular Foreman world. That means changing their Smart Proxies to port 8443 instead of 9090 to be consistent. Once we drop Pulp 2, Qpid and MongoDB will also be gone. That already simplifies things a lot. So I at least try to keep the current manual up to date and work on improving the actual platform. I also try comment on the new docs when I see something that’s really incorrect but there’s a long way to go.
As much as your statement is correct, we don’t have any planning information for upstream Foreman. People keeps coming back to Discourse with those questions.
The solution? Starting a new guide (or chapter within planning guide) strictly dedicated to Foreman. The documentation is in the process of modularization which should make this little bit better in terms of long-term maintainance - chapters relevant for Foreman core could be included using asciidoc statements. So even if some portions are the same for both Katello and Foreman, we would only maintain a single document. This process hasn’t finished yet.
The problem? Lack of resources. You mentioned just a tip of an iceberg, there’s plenty of work. I will be rewriting Monitoring Guide from scratch pretty soon. We need to get more people involved. Frankly. we know in the beginning that we will not be able to handle all of the work. What we are trying to do is solve various technical problems and set some standards and guidelines (see the README for example) for others to follow so in the end, we have a good quality content.
If you see anything wrong for Foreman core context, let’s just restructure the guide in a way that it’s obvious what is relevant and what not. In the worst case, each guide would have one big chapter for Foreman, one for Katello. Or we can maybe decide to have two separate guides just like we have for Debian. And this is fine, we know how to technically do that, it would be good to modularize the guide before any rework is done.
I agree, I hate this word. I sometimes like to use word “known to work” when I want to say “unsupported”.
This is great, something I have been personally asking for years. Less confusion, more clear documentation. This actually enables us to share lot more content than we would.
