Review Managing Configurations by using Ansible for CQA

[aneta-petrova]

What changes are you introducing?

Most of the changes revolve around making sure guide is focused on a single high-level user story (configuration management with Ansible) and also its assemblies describe a single user story each.

Other changes include reviewing abstracts, prerequisites, titles to comply with the requirements in https://github.com/theforeman/foreman-documentation/tree/master/.cursor/skills

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

Right now, the Managing Configurations by Ansible mixes two use cases: configuration management (= ensuring hosts maintain a specific state consistently over time) and ad-hoc Ansible tasks (= one-time remote execution). This made it difficult to recognize which tasks are actually useful for the purposes of config management, and which are included just because they also use Ansible or remote execution.

This is why this PR also drops the reused content for remote execution, Ansible collection management, and running Ansible playbooks. Stripping the guide of all non-config management content (and linking to where it's included in other guides) helps the primary purpose of the guide stand out properly.

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

This is part of the downstream Content Quality Assessment (CQA) effort.

Contributor 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.18/Katello 4.20 (Satellite 6.19)
• Foreman 3.17/Katello 4.19
• Foreman 3.16/Katello 4.18 (Satellite 6.18; orcharhino 7.6, 7.7, and 7.8)
• Foreman 3.15/Katello 4.17
• Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4; orcharhino 7.5)
• Foreman 3.13/Katello 4.15 (EL9 only)
• Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
• We do not accept PRs for Foreman older than 3.12.

[github-actions]

The PR preview for 7d03f0a is available at theforeman-foreman-documentation-preview-pr-4818.surge.sh

The following output files are affected by this PR:

• Managing_Configurations_Ansible/index-foreman-deb.html
• Managing_Configurations_Ansible/index-foreman-el.html
• Managing_Configurations_Ansible/index-foremanctl-katello.html
• Managing_Configurations_Ansible/index-foremanctl-orcharhino.html
• Managing_Configurations_Ansible/index-foremanctl-satellite.html
• Managing_Configurations_Ansible/index-katello.html
• Managing_Configurations_Ansible/index-orcharhino.html
• Managing_Configurations_Ansible/index-satellite.html
• Managing_Hosts/index-foreman-deb.html
• Managing_Hosts/index-foreman-el.html
• Managing_Hosts/index-foremanctl-katello.html
• Managing_Hosts/index-foremanctl-orcharhino.html
• Managing_Hosts/index-foremanctl-satellite.html
• Managing_Hosts/index-katello.html
• Managing_Hosts/index-orcharhino.html
• Managing_Hosts/index-satellite.html

show diff

show diff as HTML

[ekohl]

The section Running Ansible roles on hosts feels a bit chaotic to me because it also contains assignment. Should assignment be its own section with an introduction where we give a recommendation on when to assign to a host group and when to assign to a host?

The whole guide IMHO also misses the part that talks about setting up a schedule to keep hosts in line.

What I also miss is that IIRC host roles can also run after a host is provisioned but I forgot the exact details of how that worked.

Zooming out IMHO to a use case: imagine you have a host group with application servers that all need to be configured the same way (for example, they're behind a load balancer). What you should do is assign roles to a host group and ensure they run. When you expand the host group with an additional application server then you want the Ansible roles to run to bring the host in line with the others. If I'm a user, can I figure out how to make my use case work by reading this guide?

[ekohl]

In the preview I see this is rendered at https://theforeman-foreman-documentation-preview-pr-4818.surge.sh/nightly/Managing_Configurations_Ansible/index-katello.html#enabling-the-ansible-plugin and then after we also have Configuring your Foreman to run Ansible roles. They have a lot of overlap and I wonder if they should be merged into a single chapter.

[aneta-petrova]

I kept these as separate modules on purpose because the fact that the plugin is enabled only on non-Satellite builds makes them trickier to merge into one. Additionally, the procedures are performed in different locations: proc_enabling-the-ansible-plugin.adoc only on the server, proc_configuring-your-project-to-run-ansible-roles.adoc on the server and proxies.

[ekohl]

I lean to breaking up chapter 2.2:

• Step 1 in the procedure (adding roles) is IMHO more step 3.0 (before 3.1. Importing Ansible roles) and something you do repeatedly as you update your roles. Or arguably, it is part of step 3.1 as something that you do before importing. That step already says it is a prerequisite anyway.
• Step 2 is effectively the installation step for Smart Proxy servers where chapter 2.1 is the installation step on Foreman servers. Perhaps merge those into 1?
• Step 3 is effectively chapter 4.0: installing the keys is a prerequisite to applying definitions to hosts.

[maximiliankolb]

tech wise, this remains wrong because foreman-packaging packages ansible-core 🙃 but we had this discussion before on line 9.

[aneta-petrova]

@ekohl Do you happen to have an opinion (or better yet, advice) on this? If this is wrong, can we update the information to make it right?

[ekohl]

Adding to what @maximiliankolb said:

For foreman-deb we still use the OS provided packages. For anything else we started to package ansible-core in Foreman 3.14 and we are responsible for shipping it. IIRC we started to include ansible-core 2.16 because it provides the broadest range of OS support: EL 8 - EL 10.

Can't say for sure what Orcharhino does but I'm guessing they copy what foreman-packaging does.

[aneta-petrova]

Would this work to differentiate between foreman-deb and the other flavors?

[maximiliankolb]

I am a bit unsure about this concept:

• "managing and importing" -> Could this be split into two?
• What does managing mean? IMO "managing" is a completely empty term (relates to many many modules, so out of scope)
• Both line 7 and 8 do not really tell users anything IMO.
• what does "keeping roles organized" mean? How? Where? Why?

[aneta-petrova]

"Managing roles" is, in my eyes, the step you have to perform after enabling Ansible config management on the server side (assembly_enabling-configuration-management-with-ansible-in-project.adoc) and before actually running the roles on hosts (assembly_running-ansible-roles-on-hosts.adoc). And that's the purpose of the assembly -- to get your roles organized so that you can run them.

I'd rather not split the assembly because then it would be too granular. Grouping the actions in an assembly supports the fact that they are a user story -- there is a larger goal to this than just importing a role, for example.

[maximiliankolb]

Suggested change

	Enable the Ansible plugin on your {ProjectServer} to configure the server for Ansible configuration management.
	Enable the Ansible plugin on your {ProjectServer} to configure hosts by using Ansible roles through {Project}.

What do you think? My main issue is with "server" which I think we should avoid.

[aneta-petrova]

Except that this particular procedure really is performed on the server. The end goal is configuring hosts, sure, but at this point, users are still pretty far from that end goal.

Would this be better, to avoid the generic term "server"?

Suggested change

	Enable the Ansible plugin on your {ProjectServer} to configure the server for Ansible configuration management.
	Enable the Ansible plugin to configure your {ProjectServer} for Ansible configuration management.

[aneta-petrova]

The section Running Ansible roles on hosts feels a bit chaotic to me because it also contains assignment. Should assignment be its own section with an introduction where we give a recommendation on when to assign to a host group and when to assign to a host?

This is intentional. I want each assembly to correspond to a user story, and a user story should help accomplish a meaningful goal. Assigning a role + running it on a host can be that meaningful action performed by a single user. Perhaps it would help if the assembly/chapter wasn't called "running a role" because that duplicates the low-level procedure. "Applying configuration to a host" could work.

Or, if you think that a single user persona is unlikely to assign roles and run then, perhaps I could move the procedures on assigning roles to the preceding assembly that describes managing roles. Do you think this is the caes @ekohl?

The whole guide IMHO also misses the part that talks about setting up a schedule to keep hosts in line.

What I also miss is that IIRC host roles can also run after a host is provisioned but I forgot the exact details of how that worked.

Zooming out IMHO to a use case: imagine you have a host group with application servers that all need to be configured the same way (for example, they're behind a load balancer). What you should do is assign roles to a host group and ensure they run. When you expand the host group with an additional application server then you want the Ansible roles to run to bring the host in line with the others. If I'm a user, can I figure out how to make my use case work by reading this guide?

Great, those are three important gaps. I don't see either of these stories in the current master version of the guide: https://docs.theforeman.org/nightly/Managing_Configurations_Ansible/index-katello.html Do you? If they're there, then I shouldn't have removed them and I can re-add them. If they're not there, then I can file a request to have them documented. What do you think @ekohl?

[aneta-petrova]

I believe I've replied to/commented on/pushed back on all of the comments so far. Ready for re-review @ekohl @maximiliankolb

[ekohl]

The section Running Ansible roles on hosts feels a bit chaotic to me because it also contains assignment. Should assignment be its own section with an introduction where we give a recommendation on when to assign to a host group and when to assign to a host?

This is intentional. I want each assembly to correspond to a user story, and a user story should help accomplish a meaningful goal. Assigning a role + running it on a host can be that meaningful action performed by a single user. Perhaps it would help if the assembly/chapter wasn't called "running a role" because that duplicates the low-level procedure. "Applying configuration to a host" could work.

Or, if you think that a single user persona is unlikely to assign roles and run then, perhaps I could move the procedures on assigning roles to the preceding assembly that describes managing roles. Do you think this is the caes @ekohl?

IMHO they're separate but related user stories. The first is to make sure you have defined what Ansible needs to run. Part of this is assigning roles to hosts, but also assigning (Ansible) variables and values to a host. That defines what gets run when it is applied.

Once it is configured, you can run Ansible roles. How and when you do that will depend.

Some user stories to think about:

• I have provisioned or registered a new host and I want to apply the roles. Because the host is part of an already configured host group, the roles are inherited and I don't need to assign any roles.
• I have multiple hosts behind a load balancer and I need to set up a run where it gets run on at most N hosts at the same time so sufficient hosts remain available behind the load balancer to keep the application running.
• I have made a change to the assigned roles and/or variables and I want to see what will change so I will run Ansible roles in check mode before actually applying the changes

So I think there is some room to have 1 chapter about configuring and 1 chapter for running. Especially about how and when to do that.

Great, those are three important gaps. I don't see either of these stories in the current master version of the guide: https://docs.theforeman.org/nightly/Managing_Configurations_Ansible/index-katello.html Do you? If they're there, then I shouldn't have removed them and I can re-add them. If they're not there, then I can file a request to have them documented. What do you think @ekohl?

Yes, I think this is the first time I properly read this document and it's very procedure focused and not very use case focused. IMHO that's a gap that should be addressed, though not in this PR.

[aneta-petrova]

The section Running Ansible roles on hosts feels a bit chaotic to me because it also contains assignment. Should assignment be its own section with an introduction where we give a recommendation on when to assign to a host group and when to assign to a host?

This is intentional. I want each assembly to correspond to a user story, and a user story should help accomplish a meaningful goal. Assigning a role + running it on a host can be that meaningful action performed by a single user. Perhaps it would help if the assembly/chapter wasn't called "running a role" because that duplicates the low-level procedure. "Applying configuration to a host" could work.
Or, if you think that a single user persona is unlikely to assign roles and run then, perhaps I could move the procedures on assigning roles to the preceding assembly that describes managing roles. Do you think this is the caes @ekohl?

IMHO they're separate but related user stories. The first is to make sure you have defined what Ansible needs to run. Part of this is assigning roles to hosts, but also assigning (Ansible) variables and values to a host. That defines what gets run when it is applied.

Once it is configured, you can run Ansible roles. How and when you do that will depend.

This is great, and I think it ties into what @maximiliankolb was asking in #4818 (comment).

I have updated the list of assemblies to include one for defining Ansible configuration and another one to apply that configuration. As a result, the guide now includes these chapters:

• Enabling Ansible integration with Foreman (this is the initial step to prepare the environment for Ansible config management)
• Configuring Ansible definitions to apply to hosts
• Applying Ansible definitions to hosts

To me, these are logical steps/phases in rolling out Ansible-based configuration management, and hopefully also correspond to user personas.