Add procedures to migrate from RHEL8to9 using backups #3103

AkshayGadhaveRH · 2024-07-01T06:16:38Z

Backups can be used to migrate existing Project and Smart Proxy servers from RHEL8 to RHEL9. The backups from Project can be restored using the backup restore as well as clone method. The backups from Smart Proxies can only be restored using the backup restore method. Adding sections to backup and restore/clone.

JIRA link:
https://issues.redhat.com/browse/SAT-10790

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.11/Katello 4.13
Foreman 3.10/Katello 4.12
Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8)
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 · 2024-07-01T06:19:50Z

The PR preview for d136653 is available at theforeman-foreman-documentation-preview-pr-3103.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

evgeni

I did not mark all RHEL→EL changes, but you get the idea ;-)

guides/common/modules/con_migrating-project-or-smartproxy-to-rhel9.adoc

guides/common/assembly_migrating-to-rhel9.adoc

guides/common/modules/con_restoring-or-cloning-to-target.adoc

guides/common/modules/proc_cloning-to-rhel9.adoc

guides/doc-Upgrading_Project/master.adoc

aneta-petrova

I only have a two broad comments right now, but before I take a look at this PR in more detail, I'm wondering about the placement of the procedure. @apinnick can you please take a look here? Will users look for a migration procedure in a guide that is called "Upgrading"?

guides/common/modules/proc_migrating_project_or_smartproxy_using_backup.adoc

apinnick · 2024-07-09T14:17:01Z

I only have a two broad comments right now, but before I take a look at this PR in more detail, I'm wondering about the placement of the procedure. @apinnick can you please take a look here? Will users look for a migration procedure in a guide that is called "Upgrading"?

@asteflova No, users would not expect to find this in an Upgrade guide.

This kind of migration is a sub-use case of backup/restore, so it belongs in the Administering guide, which has procedures for migrating databases and for backing up servers.

AkshayGadhaveRH · 2024-07-10T06:01:23Z

@apinnick @asteflova so this procedure works as an alternative to the leapp upgrade of the OS which comes under the upgrade guide. Should I move the leapp section as well to Administering guide in that case? For 3.1, where we had EL7 -> EL8 upgrade using leapp, it was placed in the upgrade guide. But I see the point in moving it to Administering guide instead. @evgeni @Lennonka what do you think?

evgeni · 2024-07-10T06:03:04Z

Please keep both (leapp and migration) upgrade paths in the upgrade guide.

evgeni · 2024-07-10T06:10:40Z

This kind of migration is a sub-use case of backup/restore, so it belongs in the Administering guide, which has procedures for migrating databases and for backing up servers.

But it's a migration with the sole purpose of the upgrade of the underlying OS.

apinnick · 2024-07-10T09:15:48Z

This kind of migration is a sub-use case of backup/restore, so it belongs in the Administering guide, which has procedures for migrating databases and for backing up servers.

But it's a migration with the sole purpose of the upgrade of the underlying OS.

@evgeni In that case, I recommend calling this an upgrade in the title.

It's OK to mention that the upgrade is also a migration, in the introduction. That would eliminate confusion.

evgeni · 2024-07-10T09:25:06Z

So if the Leapp one is called "Upgrading {Project} or {SmartProxy} to {EL} 9 in-place by using Leapp" this one would be "Upgrading {Project} or {SmartProxy} to {EL} 9 by migrating"?

AkshayGadhaveRH · 2024-07-10T11:17:32Z

@evgeni @apinnick maybe we can have a chapter for Upgrading from EL 8 to 9, and under it two separate chapters:

Using LEAPP
Using Backups

Though technically we are not upgrading using backups, so I'm not very sure about this.

evgeni · 2024-07-10T11:27:00Z

I think that's a good idea!

apinnick · 2024-07-10T11:39:58Z

So if the Leapp one is called "Upgrading {Project} or {SmartProxy} to {EL} 9 in-place by using Leapp" this one would be "Upgrading {Project} or {SmartProxy} to {EL} 9 by migrating"?

@evgeni
IMO, you don't need "by migrating" unless you have, say, lots of different ways to upgrade {EL}. If that were the case, then you might need "by using migration", to show a distinction between different ways to do the same thing.

In general, short titles are good. :-)
They're easier for the user to scan and they minimize the ugly wrap-around effect in the nav menu.

apinnick · 2024-07-10T11:44:06Z

@evgeni @apinnick maybe we can have a chapter for Upgrading from EL 8 to 9, and under it two separate chapters:
1. Using LEAPP

2. Using Backups
Though technically we are not upgrading using backups, so I'm not very sure about this.

Ah, that's a totally different case! You do have two methods for upgrading EL, so it is appropriate to distinguish between the methods. "Using backups" is fine. I might have chosen "by backing up and restoring", but that is longer. Some repos allow "backup/restore". I don't recall whether our guidelines allow that. I'm sure whatever you choose will be fine.

Please ensure that there is a description of the use cases so that users know which upgrade method they should use.

guides/common/modules/proc_migrating_project_or_smartproxy_using_backup.adoc

maximiliankolb

I made some suggestions to use attributes in favor of Satellite/Foreman server or Capsule/Smart Proxies.

guides/common/modules/proc_migrating_project_or_smartproxy_using_backup.adoc

guides/common/modules/proc_migrating-project-or-smartproxy-using-backup.adoc

Backups can be used to migrate existing Project and Smart Proxy servers from RHEL8 to RHEL9. The backups from Project can be restored using the backup restore as well as clone method. The backups from Smart Proxies can only be restored using the backup restore method. Adding sections to backup and restore/clone. Adding the section to upgrade using leapp JIRA link: https://issues.redhat.com/browse/SAT-10790

- Instead of including modules, inserted links to the Administering doc for the relevant sections. - Applied conditionals to render for all builds except foreman-deb. - Haven't removed the assembly created earlier.

The LEAPP and migration sections will be set under an overarching chapter, changing the structure accordingly. Added some additional information about LEAPP vs migration and clone vs restore.

- Renamed file. - Fixed typos. - Reworded some sentences.

- Moved some lines from Leapp intro to the chapter intro. - Fixed wording. - Added the chapter to the disconnected guide.

Since cloning is done on a plain EL 9 system, adding information about that.

- Removed information that is already in the Prerequisites section. - Fixed a link. - Changed attribute.

guides/common/modules/proc_migrating-project-or-smartproxy-using-backup.adoc

Backups can be used to migrate existing Project and Smart Proxy servers from RHEL8 to RHEL9. The backups from Project can be restored using the backup restore as well as clone method. The backups from Smart Proxies can only be restored using the backup restore method. Adding sections to backup and restore/clone. JIRA link: https://issues.redhat.com/browse/SAT-10790

Lennonka · 2024-08-20T15:21:42Z

Cherry-picked:

fe9d3c3..ad30fa6 3.11 -> 3.11

maximiliankolb · 2024-08-21T10:14:53Z

Thank you @AkshayGadhaveRH 🚀

Backups can be used to migrate existing Project and Smart Proxy servers from RHEL8 to RHEL9. The backups from Project can be restored using the backup restore as well as clone method. The backups from Smart Proxies can only be restored using the backup restore method. Adding sections to backup and restore/clone. JIRA link: https://issues.redhat.com/browse/SAT-10790 (cherry picked from commit 7e0db3a)

evgeni requested changes Jul 1, 2024

View reviewed changes

pr-processor bot added the Waiting on contributor Requires an action from the author label Jul 1, 2024

AkshayGadhaveRH force-pushed the migrating_to_rhel9_using_backup branch from fd04755 to b5f8b9f Compare July 3, 2024 06:21

pr-processor bot added Needs re-review and removed Waiting on contributor Requires an action from the author labels Jul 3, 2024

AkshayGadhaveRH marked this pull request as ready for review July 9, 2024 04:52

AkshayGadhaveRH force-pushed the migrating_to_rhel9_using_backup branch from b5f8b9f to c4db3b1 Compare July 9, 2024 04:55

aneta-petrova reviewed Jul 9, 2024

View reviewed changes

guides/common/modules/proc_migrating_project_or_smartproxy_using_backup.adoc Outdated Show resolved Hide resolved

guides/common/modules/proc_migrating_project_or_smartproxy_using_backup.adoc Outdated Show resolved Hide resolved

aneta-petrova reviewed Jul 10, 2024

View reviewed changes