Improve proxy upgrade procedure (theforeman#3885)

aneta-petrova · maximiliankolb · web-flow · commit 50080bff8141 · 2025-06-18T15:29:22.000+02:00
* Simplify syncing new repos and proxy upgrade
* Include proxy upgrade procedure for Debian
* Replace REX proxy upgrade procedure with a reference to the job template
* Drop step to clean metadata
* Drop step to verify that settings.yml points to FQDN
* Minor edits

---------

Co-authored-by: Maximilian Kolb &lt;mail@maximilian-kolb.de&gt;
diff --git a/guides/common/modules/proc_synchronizing-the-new-repositories.adoc b/guides/common/modules/proc_synchronizing-the-new-repositories.adoc
@@ -6,41 +6,28 @@ You must enable and synchronize the new {ProjectVersion} repositories before you
 .Procedure
 
 . In the {ProjectWebUI}, navigate to *Content* > *Red{nbsp}Hat Repositories*.
-. Toggle the *Recommended Repositories* switch to the *On* position.
-. From the list of results, expand the following repositories and click the *Enable* icon to enable the repositories:
-+
-* To upgrade {Project} clients, enable the *{project-client-name}* repositories for all {RHEL} versions that clients use.
-+
-* If you have {SmartProxyServers}, to upgrade them, enable the following repositories too:
-+
-*{ProjectName} {SmartProxy} {ProjectVersion} (for RHEL 9 x86_64) (RPMs)*
-+
-*{ProjectName} Maintenance {ProjectVersion} (for RHEL 9 x86_64) (RPMs)*
-+
-*{EL} 9 (for x86_64 {endash} BaseOS) (RPMs)*
-+
-*{EL} 9 (for x86_64 {endash} AppStream) (RPMs)*
-
-+
-[NOTE]
-====
-If the {ProjectVersion} repositories are not available, refresh the Red{nbsp}Hat Subscription Manifest.
-In the {ProjectWebUI}, navigate to *Content* > *Subscriptions*, click *Manage Manifest*, then click *Refresh*.
-====
-+
+. Enable the following repositories:
+* Repositories required to upgrade {SmartProxyServers}:
+** *{ProjectName} {SmartProxy} {ProjectVersion} (for RHEL 9 x86_64) (RPMs)*
+** *{ProjectName} Maintenance {ProjectVersion} (for RHEL 9 x86_64) (RPMs)*
+** *{RHEL} 9 (for x86_64 {endash} BaseOS) (RPMs)*
+** *{RHEL} 9 (for x86_64 {endash} AppStream) (RPMs)*
+* Repositories required to upgrade {Project} clients:
+** *{project-client-name}* for each {RHEL} version your clients are using
 . In the {ProjectWebUI}, navigate to *Content* > *Sync Status*.
-. Click the arrow next to the product to view the available repositories.
-. Select the repositories for {ProjectVersion}.
-Note that *{project-client-name}* does not have a {ProjectVersion} version.
-Choose *{project-client-name}* instead.
-. Click *Synchronize Now*.
+. Synchronize the following repositories:
+** All repositories for version {ProjectVersion}
+** *{project-client-name}* repositories for each {RHEL} version your clients are using
+
+.Troubleshooting
+* If you do not see the {ProjectVersion} repositories in the list of repositories or if an error occurs when synchronizing a repository, refresh the Red{nbsp}Hat subscription manifest.
+In the {ProjectWebUI}, navigate to *Content* > *Subscriptions* > *Manage Manifest* > *Refresh*.
 +
-[IMPORTANT]
+[WARNING]
 ====
-If an error occurs when you try to synchronize a repository, refresh the manifest.
-If the problem persists, raise a support request.
-Do not delete the manifest from the Customer Portal or in the {ProjectWebUI}; this removes all the entitlements of your content hosts.
+Do not delete the manifest from the Customer Portal or in the {ProjectWebUI}.
+Deleting your manifest removes all the entitlements of your hosts.
 ====
-+
-. If you use content views to control updates to the base operating system of {SmartProxyServer}, update those content views with new repositories, publish, and promote their updated versions.
-For more information, see {ContentManagementDocURL}Managing_Content_Views_content-management[Managing content views] in _{ContentManagementDocTitle}_.
+
+.Additional resources
+* For more information on synchronizing repositories, see {ContentManagementDocURL}[Importing content] in _{ContentManagementDocTitle}_.
diff --git a/guides/common/modules/proc_upgrading-smartproxy-server.adoc b/guides/common/modules/proc_upgrading-smartproxy-server.adoc
@@ -1,133 +1,52 @@
 [id="upgrading_{smart-proxy-context}_server_{context}"]
 = Upgrading {SmartProxyServers}
 
-ifdef::katello,orcharhino,satellite[]
+ifdef::satellite[]
 After you have upgraded your {ProjectServer} and synchronized the required repositories, you can start upgrading your {SmartProxyServers}.
 endif::[]
-ifndef::katello,orcharhino,satellite[]
+ifndef::satellite[]
 After you have upgraded your {ProjectServer}, you can start upgrading your {SmartProxyServers}.
 endif::[]
 
-.Prerequisites
-ifdef::katello,orcharhino,satellite[]
-* If you use content views to control updates to the {SmartProxyServer} base operating system or repository, update those content views with new repositories, then publish and promote their updated versions.
-For more information, see {ContentManagementDocURL}Managing_Content_Views_content-management[Managing content views] in _{ContentManagementDocTitle}_.
-* Ensure the base system of the {SmartProxy} is registered to the newly upgraded {ProjectServer}.
-endif::[]
-* 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.
-ifdef::katello,orcharhino,satellite[]
-+
-[WARNING]
+ifndef::foreman-deb[]
+[NOTE]
 ====
-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.
+You can use the *{SmartProxy} Upgrade Playbook* job template to upgrade {SmartProxyServer}s remotely.
+For more information about running remote jobs based on templates, see {ManagingHostsDocURL}Configuring_and_Setting_Up_Remote_Jobs_managing-hosts[Configuring and setting up remote jobs] in _{ManagingHostsDocTitle}_.
 ====
 endif::[]
 
-.Upgrading {SmartProxyServers}
-. Create a backup.
-+
-* On a virtual machine, take a snapshot.
-* On a physical machine, create a backup.
-+
-For information on backups, see {AdministeringDocURL}backing-up-{project-context}-server-and-{smart-proxy-context}_admin[Backing Up {ProjectServer} and {SmartProxyServer}] in _{AdministeringDocTitle}_.
-
-ifdef::foreman-el,katello[]
-. Update repositories:
-+
-[options="nowrap" subs="attributes"]
-----
-ifdef::katello[]
-# {project-package-update} https://yum.theforeman.org/releases/{ProjectVersion}/el9/x86_64/foreman-release.rpm \
-https://yum.theforeman.org/katello/{KatelloVersion}/katello/el9/x86_64/katello-repos-latest.rpm
+.Prerequisites
+* The base system of the {SmartProxy} is registered to the newly upgraded {ProjectServer}.
+ifdef::katello,orcharhino[]
+* If you use content views to control updates to the base operating system of {SmartProxyServer}, ensure these content views are up-to-date with the new repositories.
 endif::[]
-ifdef::foreman-el[]
-# {project-package-update} https://yum.theforeman.org/releases/{ProjectVersion}/el9/x86_64/foreman-release.rpm
+ifdef::satellite[]
+* If you use content views to control updates to the base operating system of {SmartProxyServer}, ensure these content views are up-to-date with the new repositories synchronized in xref:synchronizing_the_new_repositories_{context}[].
 endif::[]
-----
-. Stop {SmartProxy} services:
-+
-[options="nowrap" subs="attributes"]
-----
-# {foreman-maintain} service stop
-----
-. Update the required packages:
-+
-[options="nowrap" subs="attributes"]
-----
-# {project-package-update}
-----
-. Run the installer:
-+
-[options="nowrap" subs="attributes"]
-----
-# {foreman-installer}
-----
+ifdef::katello,orcharhino,satellite[]
+This involves updating the content views and publishing and promoting the updated versions of the content views.
+For more information, see {ContentManagementDocURL}Managing_Content_Views_content-management[Managing content views] in _{ContentManagementDocTitle}_.
 endif::[]
-ifdef::satellite[]
-. Clean yum cache:
-+
-----
-# yum clean metadata
-----
-. Synchronize the `{RepoRHEL9ServerSatelliteCapsuleProjectVersion}` repository in the {ProjectServer}.
-. Publish and promote a new version of the content view with which the {SmartProxy} is registered.
-. Optional: Because of the lengthy upgrade time, use a utility such as `tmux` to suspend and reattach a communication session.
-You can then check the upgrade progress without staying connected to the command shell continuously.
-+
-If you lose connection to the command shell where the upgrade command is running, you can see the logged messages in the `{installer-smartproxy-log-file}` file to check if the process completed successfully.
-. The `rubygem-foreman_maintain` is installed from the {Project} Maintenance repository or upgraded from the {Project} Maintenance repository if currently installed.
-+
-Ensure that the {Project} Maintenance repository is enabled:
-+
-[options="nowrap" subs="attributes"]
-----
-# subscription-manager repos --enable \
-{RepoRHEL9ServerSatelliteMaintenanceProjectVersion}
-----
-+
-Ensure {SmartProxy} has access to `{RepoRHEL9ServerSatelliteMaintenanceProjectVersion}` and execute:
-+
-[options="nowrap" subs="attributes"]
-----
-# {foreman-maintain} self-upgrade
-----
 
-. On {SmartProxyServer}, verify that the `foreman_url` setting points to the {Project} FQDN:
-+
-----
-# grep foreman_url /etc/foreman-proxy/settings.yml
-----
-. Use the health check option to determine if the system is ready for upgrade:
-+
-[options="nowrap" subs="attributes"]
-----
-# {foreman-maintain} upgrade check
-----
-+
-Review the results and address any highlighted error conditions before performing the upgrade.
-. Perform the upgrade:
-+
-[options="nowrap" subs="attributes"]
-----
-# {foreman-maintain} upgrade run
-----
-+
+.Procedure
+ifdef::foreman-deb[]
+[tabs]
+=====
+Debian 12 (Bookworm)::
++
+--
+:distribution-codename: bookworm
+include::snip_upgrading-smartproxy-server.adoc[]
+--
+Ubuntu 22.04 (Jammy)::
++
+--
+:distribution-codename: jammy
+include::snip_upgrading-smartproxy-server.adoc[]
+--
+=====
+endif::[]
+ifndef::foreman-deb[]
+include::snip_upgrading-smartproxy-server.adoc[]
 endif::[]
-include::snip_steps-needs-reboot.adoc[]
-. Optional: If you made manual edits to DNS or DHCP configuration files, check and restore any changes required to the DNS and DHCP configuration files using the backups made earlier.
-
-.Upgrading {SmartProxyServers} using remote execution
-. Create a backup or take a snapshot.
-+
-For more information on backups, see {AdministeringDocURL}backing-up-satellite-server-and-capsule-server[Backing Up {ProjectServer} and {SmartProxyServer}] in _{AdministeringDocTitle}_.
-. In the {ProjectWebUI}, navigate to *Monitor* > *Jobs*.
-. Click *Run Job*.
-. From the *Job category* list, select *Maintenance Operations*.
-. From the *Job template* list, select *{SmartProxy} Upgrade Playbook*.
-. In the *Search Query* field, enter the host name of the {SmartProxy}.
-. Ensure that *Apply to 1 host* is displayed in the *Resolves to* field.
-. In the *target_version* field, enter the target version of the {SmartProxy}.
-. In the *whitelist_options* field, enter the options.
-. Select the schedule for the job execution in *Schedule*.
-. In the *Type of query* section, click *Static Query*.
diff --git a/guides/common/modules/snip_steps-needs-reboot.adoc b/guides/common/modules/snip_steps-needs-reboot.adoc
@@ -18,7 +18,7 @@ ifndef::foreman-deb[]
 endif::[]
 endif::[]
 ifdef::satellite[]
-. If the {foreman-maintain} command told you to reboot, then reboot the system:
+. If the `{foreman-maintain}` command told you to reboot, then reboot the system:
 endif::[]
 +
 [options="nowrap"]
diff --git a/guides/common/modules/snip_upgrading-smartproxy-server.adoc b/guides/common/modules/snip_upgrading-smartproxy-server.adoc
@@ -0,0 +1,89 @@
+. Create a backup of your {SmartProxyServer}.
+* If your {SmartProxyServer} runs on a virtual machine:
+.. Stop all {Project} services:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+# {foreman-maintain} service stop
+----
+.. Take a snapshot.
+.. Start all {Project} services:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+# {foreman-maintain} service start
+----
+* If your {SmartProxyServer} runs on a physical machine, create a backup as described in {AdministeringDocURL}[Backing up {ProjectServer} and {SmartProxyServer}] in _{AdministeringDocTitle}_.
+ifdef::foreman-el,katello[]
+. Update repositories:
++
+[options="nowrap" subs="attributes"]
+----
+ifdef::katello[]
+# {project-package-update} https://yum.theforeman.org/releases/{ProjectVersion}/el9/x86_64/foreman-release.rpm \
+https://yum.theforeman.org/katello/{KatelloVersion}/katello/el9/x86_64/katello-repos-latest.rpm
+endif::[]
+ifdef::foreman-el[]
+# {project-package-update} https://yum.theforeman.org/releases/{ProjectVersion}/el9/x86_64/foreman-release.rpm
+endif::[]
+----
+endif::[]
+ifdef::foreman-deb[]
+. Update repositories in `/etc/apt/sources.list.d/foreman.list` to consume content for {Project} {ProjectVersion}:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+deb http://deb.theforeman.org/ {distribution-codename} {ProjectVersion}
+deb http://deb.theforeman.org/ plugins {ProjectVersion}
+----
+endif::[]
+ifdef::foreman-deb,foreman-el,katello[]
+. Stop {Project} services:
++
+[options="nowrap" subs="attributes"]
+----
+# {foreman-maintain} service stop
+----
+. Update the required packages:
++
+[options="nowrap" subs="attributes"]
+----
+# {project-package-update}
+----
+. Run the {Project} installer:
++
+[options="nowrap" subs="attributes"]
+----
+# {foreman-installer}
+----
+endif::[]
+ifdef::satellite[]
+. Upgrade the `{foreman-maintain}` utility on the {SmartProxyServer} to its latest version:
++
+[options="nowrap" subs="attributes"]
+----
+# {foreman-maintain} self-upgrade
+----
+. Determine whether {SmartProxyServer} is ready for the upgrade:
++
+[options="nowrap" subs="attributes"]
+----
+# {foreman-maintain} upgrade check
+----
++
+Review the results and address any highlighted error conditions before performing the upgrade.
+. Run the {Project} upgrade command.
+Because of the lengthy upgrade time, consider using a utility such as `tmux`.
+ifdef::upgrading-connected[]
+For more information, see xref:following_the_progress_of_the_upgrade_upgrading-connected[].
+endif::[]
+ifdef::upgrading-disconnected[]
+For more information, see xref:following_the_progress_of_the_upgrade_upgrading-disconnected[].
+endif::[]
++
+[options="nowrap" subs="attributes"]
+----
+# {foreman-maintain} upgrade run
+----
+endif::[]
+include::snip_steps-needs-reboot.adoc[]
diff --git a/guides/doc-Upgrading_Project/master.adoc b/guides/doc-Upgrading_Project/master.adoc
@@ -33,10 +33,8 @@ ifdef::satellite[]
 include::common/modules/proc_synchronizing-the-new-repositories.adoc[leveloffset=+2]
 endif::[]
 
-ifdef::foreman-el,katello,satellite,orcharhino[]
 // Upgrading Smart Proxy Server
 include::common/modules/proc_upgrading-smartproxy-server.adoc[leveloffset=+2]
-endif::[]
 
 ifdef::foreman-el,katello,satellite,orcharhino[]
 // Upgrading the External database

Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@ ifndef::foreman-deb[]`
`18`	`18`	`endif::[]`
`19`	`19`	`endif::[]`
`20`	`20`	`ifdef::satellite[]`
`21`		`-. If the {foreman-maintain} command told you to reboot, then reboot the system:`
	`21`	+. If the `{foreman-maintain}` command told you to reboot, then reboot the system:
`22`	`22`	`endif::[]`
`23`	`23`	`+`
`24`	`24`	`[options="nowrap"]`