From dfaf5c452453b5aac8801143bf55b492001b05e8 Mon Sep 17 00:00:00 2001 From: Partha Aji Date: Thu, 23 Jan 2025 15:26:49 -0500 Subject: [PATCH] Docs to upgrade disconnected foreman/sat Updates the instructions to upgrade 'in-place' for disconnected environments. --- ...c_updating-disconnected-server-on-EL9.adoc | 139 +++++------------- ...grading-a-disconnected-project-server.adoc | 109 +++++--------- 2 files changed, 75 insertions(+), 173 deletions(-) diff --git a/guides/common/modules/proc_updating-disconnected-server-on-EL9.adoc b/guides/common/modules/proc_updating-disconnected-server-on-EL9.adoc index 85cfdf58f45..e8c948835da 100644 --- a/guides/common/modules/proc_updating-disconnected-server-on-EL9.adoc +++ b/guides/common/modules/proc_updating-disconnected-server-on-EL9.adoc @@ -1,7 +1,7 @@ [id="Updating-Disconnected-{project-context}-on-EL9_{context}"] = Updating a disconnected {ProjectServer} on {EL} 9 -You can update your disconnected {Project} on {RHEL} 9 by synchronizing the required repositories on the connected {Project} and syncing the content to the disconnected {Project} using `reposync`. +You can update your disconnected {Project} on {RHEL} 9 by synchronizing the required repositories on the connected {Project} and syncing the content to the disconnected {Project} using `syncable` exports. .Procedure on the connected {ProjectServer} . Ensure that you have synchronized the following repositories in your connected {ProjectServer}: @@ -9,125 +9,59 @@ You can update your disconnected {Project} on {RHEL} 9 by synchronizing the requ * {RepoRHEL9BaseOS} * {RepoRHEL9AppStream} * {RepoRHEL9ServerSatelliteServerProjectVersion} -* {RepoRHEL9ServerSatelliteMaintenanceProjectVersion} -. Download the debug certificate of the organization and store it locally at `/etc/pki/katello/certs/org-debug-cert.pem` or a location of your choosing. -For more information, see {AdministeringDocURL}Creating_an_Organization_Debug_Certificate_admin[Creating an Organization Debug Certificate] in _{AdministeringDocTitle}_. -. Create a Yum configuration file under `/etc/yum.repos.d`, such as `_{project-context}-disconnected_.repo`, with the following contents: +. Export these repositories via Syncable format. `hammer content-export complete repository --id= --format=syncable` +. Copy the exported directories over to your disconnected {ProjectServer}. + + + +.Procedure on the disconnected {ProjectServer} +. Copy the exported directories over to your disconnected {ProjectServer} + +[options="nowrap" subs="+quotes"] +. Create the `/etc/yum.repos.d/upgrade.repo` with the snippet below and and update the `baseurl` directive accordingly. + -[options="nowrap" subs="+quotes,verbatim,attributes"] +[options="nowrap" subs="+quotes"] ---- [{RepoRHEL9BaseOS}] name=Red Hat Enterprise Linux 9 for x86_64 - BaseOS (RPMs) -baseurl=_https://{foreman-example-com}_/pulp/content/_My_Organization_/Library/content/dist/rhel9/9/x86_64/baseos/os -enabled = 1 -sslclientcert = /etc/pki/katello/certs/org-debug-cert.pem -sslclientkey = /etc/pki/katello/certs/org-debug-cert.pem -sslcacert = /etc/pki/katello/certs/katello-server-ca.crt -sslverify = 1 +metadata_expire=-1 +gpgcheck=0 +cost=500 +baseurl=file:////content/dist/rhel9/9/x86_64/baseos/os [{RepoRHEL9AppStream}] name=Red Hat Enterprise Linux 9 for x86_64 - AppStream (RPMs) -baseurl=_https://{foreman-example-com}_/pulp/content/_My_Organization_/Library/content/dist/rhel9/9/x86_64/appstream/os -enabled = 1 -sslclientcert = /etc/pki/katello/certs/org-debug-cert.pem -sslclientkey = /etc/pki/katello/certs/org-debug-cert.pem -sslcacert = /etc/pki/katello/certs/katello-server-ca.crt -sslverify = 1 - -[{RepoRHEL9ServerSatelliteServerProjectVersion}] -name={ProjectName} {ProjectVersion} for RHEL 9 RPMs x86_64 -baseurl=_https://{foreman-example-com}_/pulp/content/_My_Organization_/Library/content/dist/layered/rhel9/x86_64/satellite/{ProjectVersion}/os -enabled = 1 -sslclientcert = /etc/pki/katello/certs/org-debug-cert.pem -sslclientkey = /etc/pki/katello/certs/org-debug-cert.pem -sslcacert = /etc/pki/katello/certs/katello-server-ca.crt -sslverify = 1 +mediaid=None +metadata_expire=-1 +gpgcheck=0 +cost=500 +baseurl=file:////content/dist/rhel9/9/x86_64/appstream/os -[{RepoRHEL9ServerSatelliteMaintenanceProjectVersion}] -name={ProjectName} Maintenance {ProjectVersion} for RHEL 9 RPMs x86_64 -baseurl=_https://{foreman-example-com}_/pulp/content/_My_Organization_/Library/content/dist/layered/rhel9/x86_64/sat-maintenance/{ProjectVersion}/os -enabled = 1 -sslclientcert = /etc/pki/katello/certs/org-debug-cert.pem -sslclientkey = /etc/pki/katello/certs/org-debug-cert.pem -sslcacert = /etc/pki/katello/certs/katello-server-ca.crt -sslverify = 1 ----- -. In the configuration file, complete the following steps: -* For the `sslclientcert` and `sslclientkey` options, replace `/etc/pki/katello/certs/org-debug-cert.pem` with the location of the downloaded organization debug certificate. -* For the `baseurl` option, replace `{foreman-example-com}` with the correct FQDN of your connected {ProjectServer}. -* For the `baseurl` option, replace `My_Organization` with your organization label. -. Obtain the organization label: -+ ----- -$ hammer organization list ----- -. Enter the `reposync` command: -+ -[options="nowrap" subs="+quotes,verbatim,attributes"] ----- -# dnf reposync \ ---delete \ ---disableplugin=foreman-protector \ ---download-metadata \ ---repoid {RepoRHEL9AppStream} \ ---repoid {RepoRHEL9BaseOS} \ ---repoid {RepoRHEL9ServerSatelliteMaintenanceProjectVersion} \ ---repoid {RepoRHEL9ServerSatelliteServerProjectVersion} \ --n \ --p ~/{Project}-repos ----- -+ -This downloads the contents of the repositories from the connected {ProjectServer} and stores them in the directory `~/{Project}-repos`. -. Verify that the RPMs have been downloaded and the repository data directory is generated in each of the sub-directories of `~/{Project}-repos`. -. Archive the contents of the directory: -+ -[options="nowrap" subs="+quotes,verbatim,attributes"] ----- -# tar czf {Project}-repos.tgz -C ~ {Project}-repos +[Satellite] +name=Satellite +mediaid=None +metadata_expire=-1 +gpgcheck=0 +cost=500 +baseurl=file:////content/dist/layered/rhel8/x86_64/satellite/{ProjectVersion}/os/ ---- -. Use the generated `{Project}-repos.tgz` file to update in the disconnected {ProjectServer}. -.Procedure on the disconnected {ProjectServer} -. Copy the generated `{Project}-repos.tgz` file to your disconnected {ProjectServer}. -. Extract the archive to anywhere accessible by the `root` user. -In the following example `/root` is the extraction location. + + -[options="nowrap" subs="+quotes,verbatim,attributes"] ----- -# tar zxf {Project}-repos.tgz -C /root ----- -. Create a Yum configuration file under `/etc/yum.repos.d` with the following repository information: +. Upgrade {foreman-maintain} to its next version: + -[options="nowrap" subs="+quotes,verbatim,attributes"] +[options="nowrap" subs="attributes"] +---- +# {foreman-maintain} self-upgrade --maintenance-repo-label=Satellite ---- -[{RepoRHEL9BaseOS}] -name=Red Hat Enterprise Linux 9 for x86_64 - BaseOS (RPMs) -baseurl=file:///root/{Project}-repos/{RepoRHEL9BaseOS} -enabled = 1 - -[{RepoRHEL9AppStream}] -name=Red Hat Enterprise Linux 9 for x86_64 - AppStream (RPMs) -baseurl=file:///root/{Project}-repos/{RepoRHEL9AppStream} -enabled = 1 -[{RepoRHEL9ServerSatelliteServerProjectVersion}] -name={ProjectNameX} for RHEL 9 Server RPMs x86_64 -baseurl=file:///root/{Project}-repos/{RepoRHEL9ServerSatelliteServerProjectVersion} -enabled = 1 -[{RepoRHEL9ServerSatelliteMaintenanceProjectVersion}] -name={ProjectName} Maintenance 6 for RHEL 9 Server RPMs x86_64 -baseurl=file:///root/{Project}-repos/{RepoRHEL9ServerSatelliteMaintenanceProjectVersion} -enabled = 1 ----- -. In the configuration file, replace the `/root/{Project}-repos` with the extracted location. . Use the health check option to determine if the system is ready for update. On first use of this command, `{foreman-maintain}` prompts you to enter the hammer admin user credentials and saves them in the `/etc/foreman-maintain/foreman-maintain-hammer.yml` file. -+ + [options="nowrap" subs="+quotes,verbatim,attributes"] ---- -# {foreman-maintain} update check \ ---whitelist="check-upstream-repository,repositories-validate" +# {foreman-maintain} upgrade check --whitelist="repositories-validate,repositories-setup" --target-version=6.15 ---- . Review the results and address any highlighted error conditions before performing the update. . Due to the lengthy update time, use a utility such as `tmux` to suspend and reattach a communication session. @@ -138,8 +72,7 @@ If you lose connection to the command shell where the update command is running, + [options="nowrap" subs="+quotes,verbatim,attributes"] ---- -# {foreman-maintain} update run \ ---whitelist="check-upstream-repository,repositories-setup,repositories-validate" +# {foreman-maintain} upgrade run --whitelist="repositories-validate,repositories-setup" --target-version=6.15 ---- include::snip_steps-needs-reboot.adoc[] diff --git a/guides/common/modules/proc_upgrading-a-disconnected-project-server.adoc b/guides/common/modules/proc_upgrading-a-disconnected-project-server.adoc index a5329b4c9e9..8b3d960d1c6 100644 --- a/guides/common/modules/proc_upgrading-a-disconnected-project-server.adoc +++ b/guides/common/modules/proc_upgrading-a-disconnected-project-server.adoc @@ -11,17 +11,12 @@ You can use the `--noop` option with the `{foreman-installer}` command to review ifdef::satellite[] For more information, see the Red Hat Knowledgebase solution https://access.redhat.com/solutions/3351311[How to use the noop option to check for changes in {Project} config files during an upgrade]. endif::[] -ifdef::katello,orcharhino,satellite[] -* The hammer import and export commands have been replaced with `hammer content-import` and `hammer content-export` tooling. -+ -If you have scripts that are using `hammer content-view version export`, `hammer content-view version export-legacy`, `hammer repository export`, or their respective import commands, you have to adjust them to use the `hammer content-export` command instead, along with its respective import command. -* If you implemented custom certificates, you must retain the content of both the `/root/ssl-build` directory and the directory in which you created any source files associated with your custom certificates. -+ -Failure to retain these files during an upgrade causes the upgrade to fail. -If these files have been deleted, they must be restored from a backup in order for the upgrade to proceed. -endif::[] ==== +.Prerequisites + +* These instructions are for upgrading a disconnected {ProjectServer} {ProjectVersionPrevious} running on RHEL 9 to {ProjectServer} {ProjectVersion}. If you are running {ProjectServer} {ProjectVersionPrevious} on RHEL 8, you need to first Leapp upgrade {ProjectServer} {ProjectVersionPrevious} to RHEL 9 and then follow the upgrade steps below to upgrade to {ProjectVersion}. + .Before you begin * Review and update your firewall configuration before upgrading your {ProjectServer}. @@ -73,69 +68,43 @@ Reboot these hosts after the upgrade has completed. # rm /etc/yum.repos.d/* ---- -. Obtain the latest ISO files by following the {InstallingServerDisconnectedDocURL}downloading-the-binary-dvd-images_satellite[Downloading the Binary DVD Images] procedure in _{InstallingServerDisconnectedDocTitle}_. - -. Create directories to serve as a mount point, mount the ISO images, and configure the `rhel8` repository by following the {InstallingServerDisconnectedDocURL}configuring-the-base-operating-system-with-offline-repositories_satellite[Configuring the base operating system with offline repositories] procedure in _{InstallingServerDisconnectedDocTitle}_. +.On the connected {ProjectServer} +. Ensure that you have synchronized the following repositories in your connected {ProjectServer}: + -Do not install or update any packages at this stage. +* {RepoRHEL9BaseOS} +* {RepoRHEL9AppStream} +* {RepoRHEL9ServerSatelliteServerProjectVersion} +. Export these repositories via Syncable format. `hammer content-export complete repository --id= --format=syncable` +. Copy the exported directories over to your disconnected {ProjectServer}. -. Configure the {Project} {ProjectVersion} repository from the ISO file. - -.. Copy the ISO file's repository data file for the {ProjectName} packages: +.On the disconnected {ProjectServer} +. Identify the location of the copied content. +. Create the repository data file and add the `baseurl` directive. + -[options="nowrap"] ----- -# cp /media/sat6/Satellite/media.repo /etc/yum.repos.d/satellite.repo +[options="nowrap" subs="+quotes"] ---- +[RHEL 9 Base OS] +name=Red Hat Enterprise Linux 9 for x86_64 - BaseOS (RPMs) +metadata_expire=-1 +gpgcheck=0 +cost=500 +baseurl=file:////content/dist/rhel9/9/x86_64/baseos/os -.. Edit the `/etc/yum.repos.d/satellite.repo` file: -+ ----- -# vi /etc/yum.repos.d/satellite.repo ----- - -... Change the default `InstallMedia` repository name to `{Project}-{ProjectVersion}`: -+ -[options="nowrap" subs="+quotes,attributes"] ----- -[{Project}-{ProjectVersion}] ----- +[RHEL 9 AppStream] +name=Red Hat Enterprise Linux 9 for x86_64 - AppStream (RPMs) +mediaid=None +metadata_expire=-1 +gpgcheck=0 +cost=500 +baseurl=file:////content/dist/rhel9/9/x86_64/appstream/os -... Add the `baseurl` directive: -+ -[options="nowrap"] ----- -baseurl=file:///media/sat6/Satellite ----- - -. Configure the {ProjectName} Maintenance repository from the ISO file. - -.. Copy the ISO file's repository data file for {ProjectName} Maintenance packages: -+ -[options="nowrap"] ----- -# cp /media/sat6/Maintenance/media.repo /etc/yum.repos.d/satellite-maintenance.repo ----- - -.. Edit the `/etc/yum.repos.d/satellite-maintenance.repo` file: -+ -[options="nowrap"] ----- -# vi /etc/yum.repos.d/satellite-maintenance.repo ----- - -... Change the default `InstallMedia` repository name to `{Project}-Maintenance`: -+ -[options="nowrap" subs="+quotes,attributes"] ----- -[{Project}-Maintenance] ----- - -.. Add the `baseurl` directive: -+ -[options="nowrap"] ----- -baseurl=file:///media/sat6/Maintenance/ +[Satellite] +name=Satellite +mediaid=None +metadata_expire=-1 +gpgcheck=0 +cost=500 +baseurl=file:////content/dist/layered/rhel8/x86_64/satellite/{ProjectVersion}/os/ ---- . Optional: Because of the lengthy upgrade time, use a utility such as `tmux` to suspend and reattach a communication session. @@ -147,7 +116,7 @@ If you lose connection to the command shell where the upgrade command is running + [options="nowrap" subs="attributes"] ---- -# {foreman-maintain} self-upgrade +# {foreman-maintain} self-upgrade --maintenance-repo-label=Satellite ---- . If you are using an external database, upgrade your database to PostgreSQL 13. @@ -157,7 +126,7 @@ These changes are applied to the `/etc/foreman-maintain/foreman-maintain-hammer. + [options="nowrap" subs="attributes"] ---- -# {foreman-maintain} upgrade check --whitelist="repositories-validate,repositories-setup" +# {foreman-maintain} upgrade check --whitelist="repositories-validate,repositories-setup" --target-version={ProjectVersion} ---- + Review the results and address any highlighted error conditions before performing the upgrade. @@ -165,10 +134,10 @@ Review the results and address any highlighted error conditions before performin + [options="nowrap" subs="attributes"] ---- -# {foreman-maintain} upgrade run --whitelist="repositories-validate,repositories-setup" +# {foreman-maintain} upgrade run --whitelist="repositories-validate,repositories-setup" --target-version={ProjectVersion} ---- + -If the script fails due to missing or outdated packages, you must download and install these separately. +If the script fails due to missing or outdated packages check your exported content. For more information, see {InstallingServerDisconnectedDocURL}resolving-package-dependency-errors_satellite[Resolving Package Dependency Errors] in _{InstallingServerDisconnectedDocTitle}_. include::snip_steps-needs-reboot.adoc[]