Turn 'deployment considerations' into 'deployment path'

[asteflova]

What changes are you introducing?

I'm proposing to get rid of the Deployment Considerations chapter and replace it with a more focused assembly that I named Deployment Path. The new assembly describes actions a user should take to deploy Foreman (installation + typical first configuration steps). Each step in the deployment journey is described only very briefly but it links to other guides for details.

I'm not adding any new information. All that you see in the PR was already documented; mostly in the old Deployment Considerations chapter (which was in some places out-of-date), some pieces I found scattered elsewhere in the docs set. In case of the pieces that were already documented elsewhere, I either copy-pasted them (when it was just one or two sentences) or reused (when it was a whole module, in which case I often had to resort to using ifevals).

Some parts of Deployment Considerations did not fit into the new Deployment Path assembly. I kept them under topics/ and will deal with them later, when modularizing the rest of the guide.

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

All content in Deployment Considerations was stored in topics/, not modules/. The initial goal was to modularize it.

However, if I just split the original large chapter into modules without making any modifications, I would introduce outdated modules into the main file set. So I knew I needed to do some rewriting. From there, it was only one more step towards making the content more action-based.

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

I will need to work with multiple tech reviewers to make sure the content is up-to-date.

Checklists

• I am okay with my commits getting squashed when you merge this PR.
• I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

• Foreman 3.13/Katello 4.15
• Foreman 3.12/Katello 4.14 (Satellite 6.16)
• Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only)
• Foreman 3.10/Katello 4.12
• Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
• Foreman 3.8/Katello 4.10
• Foreman 3.7/Katello 4.9 (Satellite 6.14)
• Foreman 3.6/Katello 4.8
• Foreman 3.5/Katello 4.7 (Satellite 6.13; orcharhino 6.6/6.7)
• We do not accept PRs for Foreman older than 3.5.

[github-actions]

The PR preview for b9af14b is available at theforeman-foreman-documentation-preview-pr-3456.surge.sh

The following output files are affected by this PR:

• Administering_Project/index-foreman-deb.html
• Administering_Project/index-foreman-el.html
• Administering_Project/index-katello.html
• Administering_Project/index-orcharhino.html
• Administering_Project/index-satellite.html
• Configuring_User_Authentication/index-foreman-deb.html
• Configuring_User_Authentication/index-foreman-el.html
• Configuring_User_Authentication/index-katello.html
• Configuring_User_Authentication/index-orcharhino.html
• Configuring_User_Authentication/index-satellite.html
• Installing_Proxy/index-foreman-el.html
• Installing_Proxy/index-katello.html
• Installing_Proxy/index-orcharhino.html
• Installing_Proxy/index-satellite.html
• Installing_Server/index-katello.html
• Installing_Server/index-orcharhino.html
• Installing_Server/index-satellite.html
• Installing_Server_Disconnected/index-satellite.html
• Managing_Content/index-katello.html
• Managing_Content/index-orcharhino.html
• Managing_Content/index-satellite.html
• Managing_Organizations_and_Locations/index-foreman-deb.html
• Managing_Organizations_and_Locations/index-foreman-el.html
• Managing_Organizations_and_Locations/index-katello.html
• Managing_Organizations_and_Locations/index-orcharhino.html
• Planning_for_Project/index-katello.html
• Planning_for_Project/index-orcharhino.html
• Planning_for_Project/index-satellite.html

show diff

show diff as HTML

[asteflova]

Reviewers, please ignore anything under topics/. Review only changes under common/modules/.

The list of affected guides is long, but only because module reuse is involved. All changes are limited to the Planning guide, chapter named Deployment path for {ProjectName}. Reviewing this chapter should be enough.

[asteflova]

Hi @evgeni, I was told that you might be the right person to give this PR a high-level review. Could you please take a look at assemby_deployment-path.adoc / Deployment path for Foreman/Satellite? What I mean by "high-level review" is that at this stage, I'm looking for feedback on whether this "deployment path" covers what users are actually expected to do when deploying Foreman, whether it doesn't skip any crucial steps, etc. (The goal is not to cover everything that Foreman can do, but to help users navigate through the Foreman landscape by giving them a list of the necessary minimum + whatever else is worth highlighting.)

My plan is to start asking people for more detailed feedback on the contents of the individual modules later, after this high-level review, but if you want to do that now too (especially for the modules that describe Platform's components), feel free to do so.

[evgeni]

I'm missing two things: compute resources and configuration management tools. While the set of "what is there by default" varies across the different deployment types we offer, there is always the chance to add an "integration with compute provider X" or "integration with configuration management tool Y", and while users will (probably) know that we support a lot of these, calling out "you can add those later" seems like a good thing?

[maximiliankolb]

Thanks Anet, I've reviewed everything but topics/*. Overall, LGTM.

[maximiliankolb]

Not a fan of this construct. I hightly believe that this would break this for me in downstream docs. not a blocker as I can always create a follow-up PR to change this further.

[Lennonka]

It shouldn't break if you define the context. Can you test it first, please?

[asteflova]

Is it the ifeval itself that's an issue, or just using it for a heading right after defining the anchor? We are using ifevals elsewhere already, for example

foreman-documentation/guides/common/modules/con_remote-execution-in-project.adoc

Line 35 in e5f1b86

ifeval::["{context}" == "planning"]

To be honest, I wasn't totally sure about using ifevals to differentiate headings like this. Won't it be confusing to users if they come across a module that's reused but with a different heading? I think I'll just try to find a heading that will work in both contexts.

[asteflova]

@maximiliankolb and I agreed that we will keep this as is for now and submit a follow-up PR if it breaks anything

[Lennonka]

Overally looking good. Just a few nitpicks

[Lennonka]

It shouldn't break if you define the context. Can you test it first, please?

[asteflova]

Hi @adamruzicka @ianballou @stejskalleos can you please review this PR? The diff looks huge but you don't need to review it all; below, I'm listing which sections are relevant.

The goal of this PR is to provide a high-level overview of the steps that users should take during deployment. I want to help users make a few decisions, but link to other parts of the docs set for detailed instructions. This is the new chapter: 7. Deployment path for Foreman / 7. Deployment path for Satellite. Specifically, I'm asking you to review these (mostly very short!) sections that are included in the chapter:

• @adamruzicka Configuring external authentication in Foreman (guides/common/modules/ref_overview-of-authentication-methods-in-project.adoc), Planning organization and location context (guides/common/modules/con_planning-organization-and-location-context.adoc), Defining role-based access control policies (guides/common/modules/con_creating-and-managing-roles.adoc and its subsection guides/common/modules/con_best-practices-for-role-based-access-control-in-project.adoc), Additional deployment tasks (guides/common/modules/con_additional-deployment-tasks.adoc)
• @ianballou Definining your content library (guides/common/modules/con_defining-your-content-library.adoc), Defining content access strategies for hosts (guides/common/modules/con_defining-content-access-strategies-for-hosts.adoc)
• @stejskalleos Configuring provisioning (guides/common/modules/con_configuring-provisioning.adoc)

Feel free to look at the others sections too, of course! I'm just trying to make this easier for you so I listed the sections than I think fall into your respective areas of expertise. Please let me know if there is anything unclear.

[asteflova]

Hi @evgeni, you already commented on this PR but I asked you for a high-level review of the whole chapter back then. Do you have any further feedback for sections Installing a Foreman server (guides/common/modules/con_installing-a-project-server.adoc and its subsections), Installing Smart Proxy servers (guides/common/modules/con_installing-smart-proxy-servers.adoc), and Adding a Red Hat subscription to your Satellite Server (guides/common/modules/con_installing-smart-proxy-servers.adoc)?

[asteflova]

For completeness: I'm not asking for a review of section Planning for disaster recovery because right now, that's basically just a list of links. I will be looking at disaster recovery docs in general later and I plan to revisit this section then.

[adamruzicka]

It reads well, but I wasn't sure where it stands with relation to katello. Does it assume pure foreman? If so, should it mention katello somewhere in the additional considerations?

[asteflova]

It reads well, but I wasn't sure where it stands with relation to katello. Does it assume pure foreman? If so, should it mention katello somewhere in the additional considerations?

The whole guide is currently labeled as Katello-specific. If the guide was intended to cover pure Foreman, you make a good point about the need to mention Katello. I don't think it's something we need to worry about now, though, considering that the guide as a whole doesn't seem to either.

Thanks for the feedback, I really appreciate it!

[asteflova]

Thanks for the feedback, Ian!

[asteflova]

Tech review feedback from all SMEs has been implemented. If anyone has more, please keep it coming, but right now, I think I can go ahead with tech review done.

[maximiliankolb]

19/29 files.

No blockers (apart from one hardcoded downstream term 🙃 ), mostly suggestions and notes to myself ...

[maximiliankolb]

27/29. I did not look at the wild table in guides/common/modules/ref_overview-of-authentication-methods-in-project.adoc and the file under topics/.

Made some suggestions and notes. Overall, LGTM

[asteflova]

I discussed this PR with @maximiliankolb privately. We agreed that it's good enough to be merged as is. Some comment threads are left open as trackers for him to open subsequent PRs. Therefore, I'll set the style review done flag and merge later today.

Generally speaking, this PR doesn't add new content, it only rearranges, de-duplicates, and shortens existing content. There is an agreement that this PR is an improvement over the current state of things. And we can always continue with further improvements.