Document installing of plugins in installation guides

[adamlazik1]

Original discussion: https://github.com/theforeman/foreman-documentation/pull/2372#discussion_r1304196923

The question is whether we should collectively document plug-in installations in installation guides: Installing Server and Installing Proxy.

Specifically in the case of the REX plug-in, there is a whole chapter on it in Managing Hosts, so that would be another logical place to provide the instructions for enabling it which are currently missing (only needed by upstream foreman since other builds have it enabled by default).

Let's discuss.

[asteflova]

(I'll weigh in on this -- because to me it's actually fun to discuss stuff like this! -- but I don't have enough experience installing Foreman server or any plug-ins, so I may be wrong. In which case please tell me I'm wrong and why.)

When it comes to deciding what to include in an installation guide and what in other guides, it depends on when users are expected to do the action. Talking specifically about --enable-foreman-plugin-remote-execution from https://github.com/theforeman/foreman-documentation/pull/2372 :

• If it's an option that needs to be passed with foreman-installer when you first run it, then it's a no-brainer => Installation Guide.
• If it's something that is configured very soon after running foreman-installer to install a server, and you need to enable the plug-in to properly start using the server, then Installation is still a very good choice. (Especially since there doesn't seem to be a comprehensive Deployment guide.)
• If it's something that is routinely configured after the server has been put to use, I'd rather include it in Management, but it could be linked to from Installation.

At the same time, you want to keep installation guides as lean and straightforward as possible, for a smooth user experience. So trying to stuff as much as possible into an installation guide just because someone might potentially look for it there is not a good idea.

[adamlazik1]

I agree with your point. From my understanding REX is something that foreman does not need to function properly (I could be wrong, too), therefore I would also put it in Managing hosts. The bonus is no new chapter needs to be created since there already is one and everything will be in one place - except enabling REX on smartproxy which we already have in the Installing Smartproxy guide before the relevant Cofiguring Remote Execution for Pull Client section. Again it is something that is grouped together so it creates a logical block of content so I think it is fine.

@ekohl what is you view on this with the information given by @asteflova?

[ekohl]

I think @asteflova gave a good overview. We should really do a better job of applying it.

At the same time, you want to keep installation guides as lean and straightforward as possible, for a smooth user experience. So trying to stuff as much as possible into an installation guide just because someone might potentially look for it there is not a good idea.

This is something I feel so much.

For me it's always easier to come with examples. For DNS we have:

• https://docs.theforeman.org/nightly/Installing_Server/index-katello.html#configuring-dns-dhcp-and-tftp_foreman
• https://docs.theforeman.org/nightly/Installing_Server/index-katello.html#configuring-external-dns_foreman
• https://docs.theforeman.org/nightly/Provisioning_Hosts/index-katello.html#Using_Infoblox_as_DHCP_and_DNS_Providers_provisioning
• https://docs.theforeman.org/nightly/Installing_Proxy/index-katello.html#configuring-external-services
• https://docs.theforeman.org/nightly/Installing_Proxy/index-katello.html#Managing_DNS_Using_Smart_Proxy_smart-proxy

All of these are ways to install a DNS provider on a Foreman Proxy. That means it can be applied on a ProjectServer and SmartProxyServer. Yet the documentation is all over the place. Note the last one does a decent job of linking to the various places.

I've already argued we should have a Managing DNS guide that goes over the various deployment models and their pros and cons. Then in the provisioning guide it should simply be a prerequisite to have some DNS set up with a link to the guide. Similarly, at the end of the installing server/proxy documents it can describe "further steps" and link to the next documents.

And then do the same thing for DHCP.

I could also be convinced that a separate remote execution guide could be useful. A very long Management guide is also hard to navigate.

[asteflova]

I've already argued we should have a Managing DNS guide that goes over the various deployment models and their pros and cons. Then in the provisioning guide it should simply be a prerequisite to have some DNS set up with a link to the guide. Similarly, at the end of the installing server/proxy documents it can describe "further steps" and link to the next documents.

I find this intriguing. If you remember that ISAM thing I'm supposed to work on (I shared a doc plan a few weeks ago), it started as an initiative to write a Deployment guide. Sometimes I feel like the Foreman docs set needs a go-to place for deployment advice; other times, I come to the conclusion that it probably already exists and I just don't see it because I'm not yet familiar with the project well enough.

And just to clarify what I mean by deployment:

• Installation = You install a product, but it is not yet configured for production.
• Deployment = You have a product that is 100% configured and ready for production.

[ekohl]

I think there's a slight nuance to it. Deployment can also be enabling additional capabilities. You may run the installation and only use features X and Y. Then later you have an additional need so start using feature Z.

Or more concrete: you can deploy Katello and only use host registration and content management. Later you start using host provisioning, so set that up. Reasons can be that you already have an existing host provisioning platform and need to migrate. Very common in brown field deployments (and realistically, many (if not most) deployments are like that).

Another example: in an organization there's a Linux engineering team and a network engineering team. The Linux team maintains Satellite, but the network team maintains DHCP and DNS. Politics can get in the way. So they start without the integration. Then they start the process of integration. Having a clear guide explicitly describing that can also help to bridge the organizational gap.

Satellite is a big and complex piece of software. Few, if any, use all features at the same time. Feedback from users (and customers) is that l they like that. We should embrace that users will pick and choose their feature set. It does make our lives harder, but it reflects the very messy real world that our users (& customers) operate in.

So I doubt you will be able to have a "100% configured" point. There is "ready for production", but that definition will differ a lot.

[maximiliankolb]

I believe users should install plug-ins when they have to. Example: Installing the SCC Manager Plug-in is part of Managing SUSE Content. Same for provisioning hosts; they have to install the required plug-ins, such as "VMware plug-in": Installing VMware Plugin as part of "Provisioning Hosts".

IMHO all configuration steps/procedures should be optional after users have a working Foreman/Smart Proxy instance.

Regarding REX: Yes, most likely everyone will want to use this plug-in. Maybe we can add "Requirements: You have installed the REX plug-in. See X" to procedures that require it?

Additional note: I am unsure about Satellite, but orcharhino always comes with certain plugins installed by default; namely foreman_remote_execution and foreman-tasks plug-ins (might be more!). > This means I don't want/have to show "Install X plugin" in some instances.