From 91e2d45327d4c54fe0083766b24ce33968fc1545 Mon Sep 17 00:00:00 2001 From: Aiden Fine Date: Wed, 26 Aug 2026 10:19:24 -0400 Subject: [PATCH 1/3] Add Z stream and Y stream instructions to user upgrade docs. --- docs/user/upgrade.md | 69 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 64 insertions(+), 5 deletions(-) diff --git a/docs/user/upgrade.md b/docs/user/upgrade.md index 71f53ecd1..66f1b37d6 100644 --- a/docs/user/upgrade.md +++ b/docs/user/upgrade.md @@ -4,9 +4,11 @@ Foremanctl releases are locked to specific Foreman images with version-compatibl Foreman MUST be upgraded one release at a time (e.g. 3.19 -> 3.20). -Scroll to the correct procedure below which matches your installation environment type (RPM and disconnected RPM). +Scroll to the correct procedure below which matches your installation environment type (RPM and disconnected RPM) and targeted stream (Z stream and Y Stream). -## Upgrading foremanctl from RPM install +# Y Stream + +## Upgrading foremanctl from RPM install (Y Stream) All steps must be run as root user. @@ -17,12 +19,15 @@ All steps must be run as root user. - Example: Foreman 3.19 -> 3.20 upgrades would use `dnf upgrade https://yum.theforeman.org/releases/3.20/el9/x86_64/foreman-release.rpm`. 4. Upgrade the foremanctl package: - `dnf upgrade foremanctl` -5. Run upgrade tasks by re-deploying your Foreman environment: +5. (Optional) Pre-pull container images to reduce downtime during deploy: + - `foremanctl pull-images` + - This step is optional but recommended. Services can continue running while images are pulled, reducing the downtime window during the deploy. +6. Run upgrade tasks by re-deploying your Foreman environment: - `foremanctl deploy` - Please see [Parameters](parameters.md) for additional deployment options. - - This deploy command will pull new images and run all upgrade jobs required by Foreman, its dependencies, and your configured plugins. Expect this deploy to take longer than typical deploys. + - This deploy command will pull new images (if not already pulled in the previous step) and run all upgrade jobs required by Foreman, its dependencies, and your configured plugins. Expect this deploy to take longer than typical deploys. -## Upgrading foremanctl from disconnected RPM install +## Upgrading foremanctl from disconnected RPM install (Y stream) All steps must be run as root user. @@ -57,3 +62,57 @@ All steps must be run as root user. - `foremanctl deploy` - Please see [Parameters](parameters.md) for additional deployment options. - This deploy command will pull new images and run all upgrade jobs required by Foreman, its dependencies, and your configured plugins. Expect this deploy to take longer than typical deploys. + +# Z Stream +## Upgrading foremanctl from RPM install (Z stream) + +All steps must be run as root user. + +1. Run `foremanctl health` to ensure your existing Foreman server is healthy. Correct any issues before continuing. +2. Consider backing up your Foreman environment before upgrade. See [Backup](backup.md). +3. Upgrade the foremanctl package: + - `dnf upgrade foremanctl` +4. Pull updated container images: + - `foremanctl pull-images` + - Z-stream updates do not change container image tags, but the images behind those tags are updated with bug fixes and security patches. This step ensures you get the latest images. +5. Run upgrade tasks by re-deploying your Foreman environment: + - `foremanctl deploy` + - Please see [Parameters](parameters.md) for additional deployment options. + - This deploy command will restart services with the updated images and run all upgrade jobs required by Foreman, its dependencies, and your configured plugins. Expect this deploy to take longer than typical deploys. + + +## Upgrading foremanctl from disconnected RPM install (Z stream) + +All steps must be run as root user. + +1. On your disconnected environment, run `foremanctl health` to ensure your existing Foreman server is healthy. Correct any issues before continuing. +2. Consider backing up your Foreman environment before upgrade. See [Backup](backup.md). +3. On a connected machine, install the same Foreman Release repository as your disconnected environment: + - `dnf install https://yum.theforeman.org/releases//el9/x86_64/foreman-release.rpm` +4. On a connected machine, create a local mirror of the foreman repository: + - `reposync -n -p /path/to/mirror --download-metadata --repoid=foreman` +5. On a connected machine, install foremanctl and configure it identically to your disconnected environment: + - `dnf install foremanctl` + - Note the version of foremanctl which installed. + - Configure your connected foremanctl to use the same features as your disconnected environment. +6. On a connected machine, pull updated container images: + - `foremanctl pull-images` + - Z stream updates do not change container image tags, but the images behind those tags are updated. This step ensures you get the latest images. + - Confirm the correct images were downloaded by running `podman images`. All images from your previous-version disconnected environment should be present on the connected environment. If images are missing, ensure foremanctl features parameters are identical between machines. + - Run `podman save $(podman images --format "{{.Repository}}:{{.Tag}}" | tr '\n' ' ') -o .tar` to export all downloaded images as a tarball. +7. Using an available transport mechanism, move the following to your disconnected environment: + - The foreman repo mirror and contents (contains the updated foremanctl). + - The foremanctl container image tarball. +8. On the disconnected environment, set up the repository mirrors: + - Copy the mirrored directory to a stable location (e.g., `/var/repos/foreman`). + - Redirect the existing repository configuration to use your local mirror: + - `dnf config-manager --setopt=foreman.baseurl=file:///var/repos/foreman --save` + - Verify the mirror is serving the correct package version with `dnf info foremanctl`. This version should match step 5. +9. On the disconnected environment, stage the updated container images: + - `podman load -i .tar` +10. On the disconnected environment, upgrade the foremanctl package: + - `dnf upgrade foremanctl` +11. Run upgrade tasks by re-deploying your Foreman environment: + - `foremanctl deploy` + - Please see [Parameters](parameters.md) for additional deployment options. + - This deploy command will restart services with the updated images and run all upgrade jobs required by Foreman, its dependencies, and your configured plugins. Expect this deploy to take longer than typical deploys. From dcb620325e7d15f12ed944fa1e7fdf8b446a68e2 Mon Sep 17 00:00:00 2001 From: Aiden Fine Date: Wed, 26 Aug 2026 11:40:27 -0400 Subject: [PATCH 2/3] Updates - Updated backup doc href due to filename change - Small style changes on titles - Add systemclt restart foreman.target to Z stream instructions - Changed Z stream naming from 'upgrade' to 'update' --- docs/user/upgrade.md | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/user/upgrade.md b/docs/user/upgrade.md index 66f1b37d6..45d8d6923 100644 --- a/docs/user/upgrade.md +++ b/docs/user/upgrade.md @@ -6,14 +6,14 @@ Foreman MUST be upgraded one release at a time (e.g. 3.19 -> 3.20). Scroll to the correct procedure below which matches your installation environment type (RPM and disconnected RPM) and targeted stream (Z stream and Y Stream). -# Y Stream +# Upgrading foremanctl Y Stream (ex. x.1 to x.2) -## Upgrading foremanctl from RPM install (Y Stream) +## Upgrading foremanctl from RPM install All steps must be run as root user. 1. Run `foremanctl health` to ensure your existing Foreman server is healthy. Correct any issues before continuing. -2. Consider backing up your Foreman environment before upgrade. See [Backup](backup.md). +2. Consider backing up your Foreman environment before upgrade. See [Backup and Restore](backup-restore.md). 3. Manually update your Foreman Release repository to the next Foreman Y release: - `dnf upgrade https://yum.theforeman.org/releases//el9/x86_64/foreman-release.rpm` - Example: Foreman 3.19 -> 3.20 upgrades would use `dnf upgrade https://yum.theforeman.org/releases/3.20/el9/x86_64/foreman-release.rpm`. @@ -27,12 +27,12 @@ All steps must be run as root user. - Please see [Parameters](parameters.md) for additional deployment options. - This deploy command will pull new images (if not already pulled in the previous step) and run all upgrade jobs required by Foreman, its dependencies, and your configured plugins. Expect this deploy to take longer than typical deploys. -## Upgrading foremanctl from disconnected RPM install (Y stream) +## Upgrading foremanctl from disconnected RPM install All steps must be run as root user. 1. On your disconnected environment, run `foremanctl health` to ensure your existing Foreman server is healthy. Correct any issues before continuing. -2. Consider backing up your Foreman environment before upgrade. See [Backup](backup.md). +2. Consider backing up your Foreman environment before upgrade. See [Backup and Restore](backup-restore.md). 3. On a connected machine, install the Foreman Release repository for the next Foreman Y release: - `dnf install https://yum.theforeman.org/releases//el9/x86_64/foreman-release.rpm` - Example: Foreman 3.19 -> 3.20 upgrades would use `dnf install https://yum.theforeman.org/releases/3.20/el9/x86_64/foreman-release.rpm`. @@ -63,30 +63,31 @@ All steps must be run as root user. - Please see [Parameters](parameters.md) for additional deployment options. - This deploy command will pull new images and run all upgrade jobs required by Foreman, its dependencies, and your configured plugins. Expect this deploy to take longer than typical deploys. -# Z Stream -## Upgrading foremanctl from RPM install (Z stream) +# Updating foremanctl Z Stream (x.y.1, x.y.2) +## Updating foremanctl from RPM install All steps must be run as root user. 1. Run `foremanctl health` to ensure your existing Foreman server is healthy. Correct any issues before continuing. -2. Consider backing up your Foreman environment before upgrade. See [Backup](backup.md). -3. Upgrade the foremanctl package: +2. Consider backing up your Foreman environment before update. See [Backup and Restore](backup-restore.md). +3. update the foremanctl package: - `dnf upgrade foremanctl` 4. Pull updated container images: - `foremanctl pull-images` - Z-stream updates do not change container image tags, but the images behind those tags are updated with bug fixes and security patches. This step ensures you get the latest images. -5. Run upgrade tasks by re-deploying your Foreman environment: +5. Run update tasks by re-deploying your Foreman environment: - `foremanctl deploy` - Please see [Parameters](parameters.md) for additional deployment options. - - This deploy command will restart services with the updated images and run all upgrade jobs required by Foreman, its dependencies, and your configured plugins. Expect this deploy to take longer than typical deploys. +6. Restart foreman services + - `systemclt restart foreman.target` -## Upgrading foremanctl from disconnected RPM install (Z stream) +## Updating foremanctl from disconnected RPM install All steps must be run as root user. 1. On your disconnected environment, run `foremanctl health` to ensure your existing Foreman server is healthy. Correct any issues before continuing. -2. Consider backing up your Foreman environment before upgrade. See [Backup](backup.md). +2. Consider backing up your Foreman environment before update. See [Backup and Restore](backup-restore.md). 3. On a connected machine, install the same Foreman Release repository as your disconnected environment: - `dnf install https://yum.theforeman.org/releases//el9/x86_64/foreman-release.rpm` 4. On a connected machine, create a local mirror of the foreman repository: @@ -110,9 +111,10 @@ All steps must be run as root user. - Verify the mirror is serving the correct package version with `dnf info foremanctl`. This version should match step 5. 9. On the disconnected environment, stage the updated container images: - `podman load -i .tar` -10. On the disconnected environment, upgrade the foremanctl package: +10. On the disconnected environment, update the foremanctl package: - `dnf upgrade foremanctl` -11. Run upgrade tasks by re-deploying your Foreman environment: +11. Run update tasks by re-deploying your Foreman environment: - `foremanctl deploy` - Please see [Parameters](parameters.md) for additional deployment options. - - This deploy command will restart services with the updated images and run all upgrade jobs required by Foreman, its dependencies, and your configured plugins. Expect this deploy to take longer than typical deploys. +12. Restart foreman services + - `systemclt restart foreman.target` From 90c412aaaf48f66b2d8755a971c75c29de3118e6 Mon Sep 17 00:00:00 2001 From: Aiden Fine Date: Mon, 31 Aug 2026 09:18:13 -0400 Subject: [PATCH 3/3] Create seperate guides for upgrade and update --- docs/user/update.md | 62 ++++++++++++++++++++++++++++++++++++++++++++ docs/user/upgrade.md | 60 ++---------------------------------------- 2 files changed, 64 insertions(+), 58 deletions(-) create mode 100644 docs/user/update.md diff --git a/docs/user/update.md b/docs/user/update.md new file mode 100644 index 000000000..311413540 --- /dev/null +++ b/docs/user/update.md @@ -0,0 +1,62 @@ +# Updating foremanctl + +Foremanctl releases are locked to specific Foreman images with version-compatible dependencies and plugins. Your system's installed `foreman-release` repository configuration RPM locks your system to the correct foremanctl version, which in turn will pull the correct Foreman images. For nearly all install situations, upgrading your Foreman server should be approached through upgrading `foreman-release` and/or `foremanctl`. + +Scroll to the correct procedure below which matches your installation environment type (RPM and disconnected RPM). + +# Updating foremanctl z-stream (x.y.1, x.y.2) + +## Updating foremanctl from RPM install + +All steps must be run as root user. + +1. Run `foremanctl health` to ensure your existing Foreman server is healthy. Correct any issues before continuing. +2. Consider backing up your Foreman environment before update. See [Backup and Restore](backup-restore.md). +3. update the foremanctl package: + - `dnf upgrade foremanctl` +4. Pull updated container images: + - `foremanctl pull-images` + - z-stream updates do not change container image tags, but the images behind those tags are updated with bug fixes and security patches. This step ensures you get the latest images. +5. Run update tasks by re-deploying your Foreman environment: + - `foremanctl deploy` + - Please see [Parameters](parameters.md) for additional deployment options. +6. Restart foreman services + - `systemclt restart foreman.target` + + +## Updating foremanctl from disconnected RPM install + +All steps must be run as root user. + +1. On your disconnected environment, run `foremanctl health` to ensure your existing Foreman server is healthy. Correct any issues before continuing. +2. Consider backing up your Foreman environment before update. See [Backup and Restore](backup-restore.md). +3. On a connected machine, install the same Foreman Release repository as your disconnected environment: + - `dnf install https://yum.theforeman.org/releases//el9/x86_64/foreman-release.rpm` +4. On a connected machine, create a local mirror of the foreman repository: + - `reposync -n -p /path/to/mirror --download-metadata --repoid=foreman` +5. On a connected machine, install foremanctl and configure it identically to your disconnected environment: + - `dnf install foremanctl` + - Note the version of foremanctl which installed. + - Configure your connected foremanctl to use the same features as your disconnected environment. +6. On a connected machine, pull updated container images: + - `foremanctl pull-images` + - z-stream updates do not change container image tags, but the images behind those tags are updated. This step ensures you get the latest images. + - Confirm the correct images were downloaded by running `podman images`. All images from your previous-version disconnected environment should be present on the connected environment. If images are missing, ensure foremanctl features parameters are identical between machines. + - Run `podman save $(podman images --format "{{.Repository}}:{{.Tag}}" | tr '\n' ' ') -o .tar` to export all downloaded images as a tarball. +7. Using an available transport mechanism, move the following to your disconnected environment: + - The foreman repo mirror and contents (contains the updated foremanctl). + - The foremanctl container image tarball. +8. On the disconnected environment, set up the repository mirrors: + - Copy the mirrored directory to a stable location (e.g., `/var/repos/foreman`). + - Redirect the existing repository configuration to use your local mirror: + - `dnf config-manager --setopt=foreman.baseurl=file:///var/repos/foreman --save` + - Verify the mirror is serving the correct package version with `dnf info foremanctl`. This version should match step 5. +9. On the disconnected environment, stage the updated container images: + - `podman load -i .tar` +10. On the disconnected environment, update the foremanctl package: + - `dnf upgrade foremanctl` +11. Run update tasks by re-deploying your Foreman environment: + - `foremanctl deploy` + - Please see [Parameters](parameters.md) for additional deployment options. +12. Restart foreman services + - `systemclt restart foreman.target` diff --git a/docs/user/upgrade.md b/docs/user/upgrade.md index 45d8d6923..a0f55ac8b 100644 --- a/docs/user/upgrade.md +++ b/docs/user/upgrade.md @@ -4,9 +4,9 @@ Foremanctl releases are locked to specific Foreman images with version-compatibl Foreman MUST be upgraded one release at a time (e.g. 3.19 -> 3.20). -Scroll to the correct procedure below which matches your installation environment type (RPM and disconnected RPM) and targeted stream (Z stream and Y Stream). +Scroll to the correct procedure below which matches your installation environment type (RPM and disconnected RPM). -# Upgrading foremanctl Y Stream (ex. x.1 to x.2) +# Upgrading foremanctl y-stream (ex. x.1 to x.2) ## Upgrading foremanctl from RPM install @@ -62,59 +62,3 @@ All steps must be run as root user. - `foremanctl deploy` - Please see [Parameters](parameters.md) for additional deployment options. - This deploy command will pull new images and run all upgrade jobs required by Foreman, its dependencies, and your configured plugins. Expect this deploy to take longer than typical deploys. - -# Updating foremanctl Z Stream (x.y.1, x.y.2) -## Updating foremanctl from RPM install - -All steps must be run as root user. - -1. Run `foremanctl health` to ensure your existing Foreman server is healthy. Correct any issues before continuing. -2. Consider backing up your Foreman environment before update. See [Backup and Restore](backup-restore.md). -3. update the foremanctl package: - - `dnf upgrade foremanctl` -4. Pull updated container images: - - `foremanctl pull-images` - - Z-stream updates do not change container image tags, but the images behind those tags are updated with bug fixes and security patches. This step ensures you get the latest images. -5. Run update tasks by re-deploying your Foreman environment: - - `foremanctl deploy` - - Please see [Parameters](parameters.md) for additional deployment options. -6. Restart foreman services - - `systemclt restart foreman.target` - - -## Updating foremanctl from disconnected RPM install - -All steps must be run as root user. - -1. On your disconnected environment, run `foremanctl health` to ensure your existing Foreman server is healthy. Correct any issues before continuing. -2. Consider backing up your Foreman environment before update. See [Backup and Restore](backup-restore.md). -3. On a connected machine, install the same Foreman Release repository as your disconnected environment: - - `dnf install https://yum.theforeman.org/releases//el9/x86_64/foreman-release.rpm` -4. On a connected machine, create a local mirror of the foreman repository: - - `reposync -n -p /path/to/mirror --download-metadata --repoid=foreman` -5. On a connected machine, install foremanctl and configure it identically to your disconnected environment: - - `dnf install foremanctl` - - Note the version of foremanctl which installed. - - Configure your connected foremanctl to use the same features as your disconnected environment. -6. On a connected machine, pull updated container images: - - `foremanctl pull-images` - - Z stream updates do not change container image tags, but the images behind those tags are updated. This step ensures you get the latest images. - - Confirm the correct images were downloaded by running `podman images`. All images from your previous-version disconnected environment should be present on the connected environment. If images are missing, ensure foremanctl features parameters are identical between machines. - - Run `podman save $(podman images --format "{{.Repository}}:{{.Tag}}" | tr '\n' ' ') -o .tar` to export all downloaded images as a tarball. -7. Using an available transport mechanism, move the following to your disconnected environment: - - The foreman repo mirror and contents (contains the updated foremanctl). - - The foremanctl container image tarball. -8. On the disconnected environment, set up the repository mirrors: - - Copy the mirrored directory to a stable location (e.g., `/var/repos/foreman`). - - Redirect the existing repository configuration to use your local mirror: - - `dnf config-manager --setopt=foreman.baseurl=file:///var/repos/foreman --save` - - Verify the mirror is serving the correct package version with `dnf info foremanctl`. This version should match step 5. -9. On the disconnected environment, stage the updated container images: - - `podman load -i .tar` -10. On the disconnected environment, update the foremanctl package: - - `dnf upgrade foremanctl` -11. Run update tasks by re-deploying your Foreman environment: - - `foremanctl deploy` - - Please see [Parameters](parameters.md) for additional deployment options. -12. Restart foreman services - - `systemclt restart foreman.target`