foreman-documentation Update client repository to satellite-6-client-2

The newer versions support puppet-agent 8.
The client repo is versionless and older versions use puppet-agent 7.
To work around this, satellite-6-client-2 is created for the later versions with puppet-agent 8.
Removed the snippet linked in Installing and configuring Puppet agent manually as this snippet is used in multiple modules.

JIRA: https://issues.redhat.com/browse/SAT-27092

What changes are you introducing?

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

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

Checklists

[x] I am okay with my commits getting squashed when you merge this PR.
[X] I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

[X] Foreman 3.12/Katello 4.14 (Satellite 6.16)
[ ] Foreman 3.11/Katello 4.13
[ ] 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.

Aug 30 '24 11:08 AkshayGadhaveRH

The PR preview for a5a23757c367f705be815fbe8b26d8dedef403ef is available at theforeman-foreman-documentation-preview-pr-3247.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

Aug 30 '24 11:08 github-actions[bot]

Aren't we supposed to support both repos at this time? So instead of replacing it, we should add it?

Sep 02 '24 14:09 Lennonka

Good question. I think we want users to use the latest version. I think there's one edge case: if you have n-1 Capsules then they may run Puppetserver 7. You're only supposed to use agents that are at most as new as the server, so having Puppet 8 on clients with a Capsule 6.15 should be unsupported.

Not all Capsules will run Puppetserver, but out of simplicity I'd say that you need to have upgraded the server (Satellite or Capsule, depending on how the host is configured) to 6.16 to use satellite-6-client-2. Otherwise you need to stick to the old version.

It's possible to have a mixed environment where some hosts are connected to Satellite 6.16 using satellite-6-client-2 while other hosts are connected to a Capsule 6.15 using the old version. If the user is careful I don't see how that would be a problem, but generally I'd say users should upgrade their entire deployment (Satellite and all Capsules) before migrating to satellite-6-client-2.

Should that be covered in the upgrading guide as well? Probably also a release note, though I know we don't capture Satellite release notes here.

Sep 02 '24 15:09 ekohl

Good question. [...] I think there's one edge case: [...] If the user is careful I don't see how that would be a problem, but generally I'd say users should [...]

From our d/s perspective, we should not try to document every possible scenario. We should stick to the most user-friendly (and, I suppose, least error-prone) solutions. Without understanding all the details of this particular situation, I just wanted to chime in with my 2 cents: If there is a recommended scenario among many other different scenarios that could go badly if users aren't careful, we should document the recommended one to steer users towards those user stories that we actually want to support.

TL;DR: We shouldn't document everything that's possible. We should document the things that we want users to do.

Sep 02 '24 15:09 aneta-petrova

TL;DR: We shouldn't document everything that's possible. We should document the things that we want users to do.

I agree, which is why I emphasized on the simple solutions. But we must think about the edge cases because customers will come up with them. If we don't clearly document that users of n-1 first need to upgrade, it's likely that some customer will attempt to do so.

More concrete, we have this line in our Satellite upgrade guide:

Note that you can upgrade Capsules separately from Satellite.

And this line:

Note that Satellite Server upgraded from 6.15 to 6.16 can use Capsule Servers still at 6.15.

That will now have an asterisk that there are some limitations if you do.

Sep 02 '24 16:09 ekohl

I rather meant that in Sat 6.16 we support Puppet agent 7 in the Client 1 repo alongside Puppet agent 8 in the Client 2 repo. So we need to add a new attribute instead of replacing the existing value.

Sep 04 '24 13:09 Lennonka

@Lennonka I'll retain the old attribute as well.

Sep 06 '24 06:09 AkshayGadhaveRH

@evgeni @ehelms where should the new repos replace the old ones?

Sep 11 '24 05:09 AkshayGadhaveRH

where should the new repos replace the old ones?

We need to update the following:

https://docs.theforeman.org/nightly/Managing_Configurations_Puppet/index-satellite.html#introducing-configuration-management-by-using-puppet - sections about Puppet agent - I'm not sure if we want to provide guidance on upgrading Puppet agent 7 to Puppet agent 8, which might require another procedure
https://docs.theforeman.org/nightly/Managing_Security_Compliance/index-satellite.html#deploying-compliance-policies_security-compliance - sections 9.5 and 9.6

Sep 23 '24 10:09 Lennonka

FYI With recent updates from the RH engineering, the Client 2 repo will not be provided in 6.16.0 GA. It will be provided later. So we need to monitor it and merge this PR later.

Oct 08 '24 12:10 Lennonka

Hey @Lennonka fixed it. I had preserved the old snippet as well, but I think the build was failing because the project-client-2-name attribute was not defined for non-Satellite builds. Added these to the attributes and it seems to build fine now.

Oct 09 '24 06:10 AkshayGadhaveRH

@AkshayGadhaveRH That's good spotting, but I would prefer that we just edit the original snippet instead of adding a new one. It isn't necessary to add the new one because the old one can be reused with edits.

Oct 09 '24 16:10 Lennonka

@Lennonka would it be better to manipulate the attribute for puppet related modules so that it renders to Client-2 in that case?

Oct 10 '24 06:10 AkshayGadhaveRH

@AkshayGadhaveRH I think we should clarify first, whether we want to tell users that they can use either Client 1 or Client 2 repo, or we tell them only about Client 2, in 6.16.

@ehelms Can you please clarify?

Oct 10 '24 22:10 Lennonka

@AkshayGadhaveRH I think we should clarify first, whether we want to tell users that they can use either Client 1 or Client 2 repo, or we tell them only about Client 2, in 6.16.

@ehelms Can you please clarify?

There is no client 2 right now, this change is not needed for the moment. So we can just close it till we are ready.

Oct 11 '24 12:10 ehelms

Closing this as the changes have only been made to the puppeterver and the installer making these doc changes unnecessary.

Oct 15 '24 05:10 AkshayGadhaveRH