Skip to content

Commit

Permalink
Docs to upgrade disconnected foreman/sat
Browse files Browse the repository at this point in the history 
Updates the instructions to  upgrade 'in-place' for disconnected
environments.
  • Loading branch information
@parthaa
parthaa committed Feb 3, 2025
1 parent afaf36c commit dfaf5c4
Show file tree
Hide file tree
Showing 2 changed files with 75 additions and 173 deletions.
139 changes: 36 additions & 103 deletions guides/common/modules/proc_updating-disconnected-server-on-EL9.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,133 +1,67 @@
[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}:
+
* {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=<repo_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:///<export baseos location>/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:///<export appstream location>/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:///<export location>/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.
Expand All @@ -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[]
Expand Down
109 changes: 39 additions & 70 deletions guides/common/modules/proc_upgrading-a-disconnected-project-server.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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}.
Expand Down Expand Up @@ -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=<repo_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:///<export baseos location>/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:///<export appstream location>/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:///<export location>/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.
Expand All @@ -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.
Expand All @@ -157,18 +126,18 @@ 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.
. Perform the upgrade:
+
[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[]
Expand Down

0 comments on commit dfaf5c4

Please sign in to comment.