search

theforeman / foreman-documentation

Documentation for the Foreman Project and its ecosystem
https://docs.theforeman.org
Creative Commons Attribution Share Alike 4.0 International
17 stars 91 forks source link

Only generate guides and variants when it makes sense for the given scenario #396

Open ehelms opened 3 years ago

ehelms commented 3 years ago

For example, do not generate content guides for Foreman, only for Katello and Satellite.

Guide foreman-el foreman-deb katello satellite
Admistering Foreman Yes
Administering with Ansible Yes
Configuring Ansible Yes
Configuring Load Balancer Yes
Content Management Yes
Deplying on AWS Yes
Installing Proxy on Debian No
Installing Proxy on Red Hat Yes
Installing Server Disconnected Yes
Installing Server on Debian No
Installing Server on Red Hat Yes
Managing Hosts Yes
Planning Guide Yes Yes Yes Yes
Provisioning Guide Yes Yes Yes Yes
lzap commented 3 years ago

Eric, I took the opportunity to turn this ticket into discussion. I edited your post and added a table where we can put our thoughts, Yes meaning it makes sense to build that version. Feel free to correct my thoughts.

The breakup into foreman-el and foreman-deb made things a little bit worse for some guides, for example in the Provisioning Guide we only have if-statements for "satellite" and "foreman-el". Therefore it would probably make more sense to just pick one of the foreman-el and foreman-deb and build that. That would result in: foreman-el, katello and satellite. Thoughts? @ehelms @ekohl @melcorr @maximiliankolb

lzap commented 3 years ago

Once we land on something here, I will implement the necessary Makefile changes.

maximiliankolb commented 3 years ago

The breakup into foreman-el and foreman-deb made things a little bit worse for some guides, for example in the Provisioning Guide we only have if-statements for "satellite" and "foreman-el".

I am not up to date with this approach (is this a suggestion/has this been decided on/already been implemented?), but it makes sense to me.

A follow up should be going through all guides and checking if individual blocks are missing. I would certainly help doing this.

ehelms commented 3 years ago

I would agree that some guides, largely those that deal with using Foreman/Katello/Satellite should not be generated per OS but rather once where applicable. For example, there should be a Content Management guide for Katello users. For installation and administration guides, things get trickier and I currently find my leaning to the current approach of doing it per major OS as the commands and locations of things tends to differ. If we look at different versions of an OS, things do get a little bit harry there as sometimes commands are different (yum vs dnf) and sometimes packages are different (scl vs non-scl) and locations on disk differ (/var/lib/pgsql vs /var/opt/rh/rh-postgresql12/var/lib/pgsql). They may vary enough that having dedicated guides for each just feels cleaner than having both every time within the same page.

For installation this would mean doing:

Or:

I think the latter is more verbose, but in a way feels cleaner for the user as they can go to the dedicated guide for their deployment rather than sifting through finding, for each subsection, the sub-subsection for their OS of choice.

maximiliankolb commented 3 years ago

Regarding two different guides for EL 7 and EL 8: I slightly tend towards building less guides than more; but I don't really care too much. (For our downstream product, we only use individual guides with additional if downstream product > then X blocks.) I am happy either way.

I want to focus more on the "a single instruction for multiple Foreman instances (on Debian/EL/with Katello/without Katello)" aspect. I am quite happy with the if satellite > then A & if foreman > then B approach. Would this change? Are you worried about this not scaling? Does this different between EL versions yet?

Overall, I feel like the current approach is an excellent way of providing multiple versions of the Foreman documentation for multiple use cases/products. 😄

melcorr commented 3 years ago

In Satellite docs, we have always had to maintain parallel instructions for different versions of RHEL on a per-topic basis. I think we'll always have the scenario where we support two versions of an operating system, whatever that operating system might be. Let's not generate a separate guide for every OS version; I prefer to keep to the OS family.

I agree that we should not build out separate versions of all guides for both Foreman and Katello.

I agree with this approach for installation:

The other guides have content that is blended. We've dealt with this by using a note: "Katello plugin only" etc. For example, throughout the Provisioning guide where you have the option of using an activation key. I don't think there's a need to generate two versions of these guides as long as we can make clear that Katello is needed for certain scenarios.

I think that there are a few scenarios here where there is a great divergence, for example the Backup and Restore chapters in the admin guide, where I'll have to provide two totally different procedures for Foreman and Katello. Any thoughts on the best way to approach that?

https://community.theforeman.org/t/foreman-manual-reboot/22606

ehelms commented 3 years ago

I have taken the tactic suggested in https://github.com/theforeman/foreman-documentation/pull/411 -- this results in a few sections that need subsections by OS version, e.g. configuring repositories, storage guidelines, installing packages

lzap commented 3 years ago

So are we going with approach A or approach B? I don't have a strong opinion, I think installation guides are the most challenging ones and we should decide depending on what's better for those guides (thus people who maintain them more often). Then I would like to implement the changes because we already see another BUILD flag emerging at https://github.com/theforeman/foreman-documentation/pull/453 and this build matrix is getting out of control ;-)

ehelms commented 3 years ago

I have taken the approach A in the current set of guides. So any section that needs to call out things being different on versions of the OS (or spins thereof) includes dedicated sections for each.

melcorr commented 3 years ago

Hey @ehelms @lzap @maximiliankolb in #672 @ekohl suggests creating separate Foreman and Katello admin guides. What do you think? In #672 I had proposed adding a snippet just to note that some procedures or chapters don't apply here or there. However, I am open to publishing two versions of the guide. Let me know your thoughts please.

ehelms commented 3 years ago

Given they are two separate installation paths, for now I would agree the guides should be separate to drive home that fact to users.

ekohl commented 3 years ago

I think we'll then present 3 "books":

And I think we should also present it that way in the index.

melcorr commented 3 years ago

I would really appreciate support on the Debian side of things. I do not have the expertise to understand the Debian scenarios. I have only ever heard @ekohl talk about Debian documentation; anyone else I've asked hasn't really known. I will focus on the Foreman and Katello for EL scenarios because of this. I would appreciate any PRs that might refine it for Debian, but the scope of my PRs will be EL.

ekohl commented 3 years ago

The biggest differences are found in Apache. So it's apache2 instead of httpd. You'll find this in the package name and file paths (/etc/apache2 vs /etc/httpd, same in /var/log). Also the username is www-data on Debian while it's apache on RPM.

Another big one is the system SSL store: /etc/pki is a Red Hat thing while Debian uses /etc/ssl but with a very different structure.

Obviously apt (+ dpkg) vs yum/dnf (+ rpm) is another one. Other than the name, yum/dnf will retrieve metadata automatically while with apt it's explicit (apt update).

Something else is that on Debian services are started automatically on apt install while with yum install the service is not started. With systemd you can override this via presets, but we should always assume defaults. This doesn't affect us that much because the installer abstracts that way for us.

You'll also find differences in PostgreSQL packaging. Debian is multi-version by default, meaning every package has a version in it and can be installed in parallel (to be concrete: postgresql11 and postgresql12can be installed and running at the same time). The config is in/etc/postgresql/$version/$cluster(in RPM:/var/lib/pgsql/data) while the data is in/var/lib/postgresql/$version/$cluster(in RPM:/var/lib/pgsql/data). Slight complication is that on EL7 with SCLs you can install multiple versions at the same time and the paths are moved to/var/opt/rh/rh-postgresql$version/lib/data. We installrh-postgresql$version-postgresql-server-syspaths` to install utilities in the same name as without SCL for convenience. Again, something the installer mostly abstracts away but you do need to take care of it in planning your partitions for storage sizes and backups.

For PostgreSQL we actually have a different file path on all platforms (EL7, EL8, Debian/Ubuntu). Probably something we should handle with attributes.

Then there are differences in package names (but not all) and what has been packaged.

Logging is another: by default Red Hat uses /var/log/messages in syslog, but Debian uses /var/log/messages just for kernel logging, early init and syslog itself. Daemons log to /var/log/daemon.log. Again, something you can modify in syslog's config where different facilities log to but we should assume defaults. There is a shift to systemd-journald and Debian 11 actually has enabled persistent storage of it by default (in older versions it's empheral). That does mean long term we can unify on the journal using journalctl if we need to, which is great for us.

So in short the things we'll mostly run into:

Right now what would help me the most is if you could look into how we can actually generate multiple "books" (not sure how we should refer to this). We'll need to decide how far we want to go. It may actually be great for users if they can not just select EL but rather EL7 or EL8. Then they don't need to read carefully which version they have.

maximiliankolb commented 3 years ago

I think we'll then present 3 "books":

  • Foreman on EL
  • Foreman on Debian/Ubuntu
  • Katello on EL

I'm fine with this approach and hope that "Foreman on EL" can easily be combined with "Katello on EL". It would also be nice to have switches to turn on/off blocks for different EL versions, i.e. EL7 & EL8.

ekohl commented 3 years ago

I'm fine with this approach and hope that "Foreman on EL" can easily be combined with "Katello on EL"

I don't think so. At least for now ports are different (see https://github.com/theforeman/foreman-documentation/pull/651). We're working on that, but making sure it's a smooth migration for users means it's a long process. Then the entire certificate handling is different. Again, something we're working on but also a long process.

So ideally speaking, the Katello on EL guide is basically Foreman on EL + extra chapters but that's a long way out. I can't see that happening within a year given our current pace and backwards compatibility in mind.