Add z stream and y stream instructions to user upgrade docs. by aidenfine · Pull Request #787 · theforeman/foremanctl

aidenfine · 2026-08-26T14:23:04Z

Why are you introducing these changes? (Problem description, related links)

Old user docs did not include correct steps for Z stream upgrades. I also included the optional foremanctl pull-images step in Y stream upgrade that could reduce downtown during upgrade.

What are the changes introduced in this pull request?

y stream and z stream upgrade doc changes

qcjames53 · 2026-08-26T14:47:54Z

    - 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)


Ewoud would like us to use "update" for the Z-stream changes.

It's not just me, I'm following what we introduced in our documentation. https://docs.theforeman.org/nightly/Upgrading_Project/index-katello.html and https://docs.theforeman.org/nightly/Updating_Project/index-katello.html are separate.

qcjames53 · 2026-08-26T14:50:01Z

+# Y Stream
+
+## Upgrading foremanctl from RPM install (Y Stream)


Suggested change

# Y Stream

## Upgrading foremanctl from RPM install (Y Stream)

# Upgrading foremanctl Y Stream (ex. x.1 to x.2)

## Upgrading foremanctl from RPM install

This reads better to me. Feel free to ignore since it's just a style suggestion.

I like it will change it.

qcjames53 · 2026-08-26T14:52:34Z

Suggested change

2. Consider backing up your Foreman environment before upgrade. See [Backup and Restore](backup-restore.md).

This needs updated to the new doc name.

qcjames53 · 2026-08-26T14:53:06Z

 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:


This is a great add. Love it.

qcjames53 · 2026-08-26T14:53:53Z

+    - 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)


Suggested change

## Upgrading foremanctl from disconnected RPM install (Y stream)

## Upgrading foremanctl from disconnected RPM install

Just a suggestion to match style tweak above.

qcjames53 · 2026-08-26T15:00:21Z

+    - 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)


Suggested change

## Upgrading foremanctl from disconnected RPM install (Z stream)

## Updating foremanctl from disconnected RPM install

qcjames53 · 2026-08-26T15:00:37Z

+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).


One more place to fix the link, sorry. Also "upgrade" -> "update".

qcjames53 · 2026-08-26T15:12:54Z

+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.


I confirmed that "This deploy command will restart services" is inaccurate when the image tag does not change. I tested this and systemctl restart foreman.target works best as a step after the deploy since migrations run during the deploy and then the restart flips execution over to the new code on the new images.

qcjames53 · 2026-08-26T15:17:22Z

 6. On a connected machine, pull required images and prepare them for transfer:
    - `foremanctl pull-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 <filename>.tar` to export all downloaded images as a tarball.


Aiden have you had any issues with this command? Someone ran into an issue with this downstream (no container tag fails it) but every time I've tarballed the podman images with this it's worked for me.

I have honestly not run it since I am working on this in parallel with a few other things I have been taking peoples word that it works currently.

I trust that if you and someone else mentioned it works its okay to put in here.

qcjames53 · 2026-08-26T15:18:18Z

+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.


Can you add the same additional step as above please? I've confirmed services do not restart as of today.

aidenfine · 2026-08-26T15:37:33Z

@qcjames53 Does running foremanctl deploy also not restart the services on the Y stream upgrades? I added the systemclt restart foreman.target step to the Z stream only

- 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'

qcjames53 · 2026-08-26T18:06:25Z

@qcjames53 Does running foremanctl deploy also not restart the services on the Y stream upgrades? I added the systemclt restart foreman.target step to the Z stream only

They restart on y stream. The new image tag sets a flag to restart the foreman services on deploy.

qcjames53

Everything looks great to me! Thanks, Aiden.

ehelms · 2026-08-26T19:40:01Z

    - 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)


Suggested change

# Updating foremanctl Z Stream (x.y.1, x.y.2)

# Updating foremanctl z-stream (x.y.1, x.y.2)

I would almost prefer a separate guide to re-enforce update vs upgrade like we do today in our documentation.

^ 'y-stream' as well. Thanks Aiden.

I dont mind creating separate files, I will make a commit tomorrow related to this.

aidenfine · 2026-08-31T13:18:48Z

Sorry guys got distracted with something else, just pushed the changes to separate the guides

aidenfine · 2026-09-01T18:02:14Z

@ehelms How does this look now?
cc @qcjames53

qcjames53

This looks good to me still. Thanks for the update. 👍

Add Z stream and Y stream instructions to user upgrade docs.

91e2d45

pr-processor Bot added the Not yet reviewed label Aug 26, 2026

qcjames53 suggested changes Aug 26, 2026

View reviewed changes

pr-processor Bot added Waiting on contributor and removed Not yet reviewed labels Aug 26, 2026

Updates

dcb6203

- 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'

pr-processor Bot added Needs re-review and removed Waiting on contributor labels Aug 26, 2026

aidenfine mentioned this pull request Aug 26, 2026

Update disconnected update procedure for containerization theforeman/foreman-documentation#5229

Open

9 tasks

qcjames53 approved these changes Aug 26, 2026

View reviewed changes

pr-processor Bot removed the Needs re-review label Aug 26, 2026

ehelms reviewed Aug 26, 2026

View reviewed changes

Create seperate guides for upgrade and update

90c412a

qcjames53 approved these changes Sep 1, 2026

View reviewed changes

		# Y Stream

		## Upgrading foremanctl from RPM install (Y Stream)


	2. Consider backing up your Foreman environment before upgrade. See [Backup and Restore](backup-restore.md).

	## Upgrading foremanctl from disconnected RPM install (Y stream)
	## Upgrading foremanctl from disconnected RPM install

		- 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)

	## Upgrading foremanctl from disconnected RPM install (Z stream)
	## Updating foremanctl from disconnected RPM install

	# Updating foremanctl Z Stream (x.y.1, x.y.2)
	# Updating foremanctl z-stream (x.y.1, x.y.2)

Uh oh!

Conversation

aidenfine commented Aug 26, 2026

Why are you introducing these changes? (Problem description, related links)

What are the changes introduced in this pull request?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aidenfine commented Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qcjames53 commented Aug 26, 2026

Uh oh!

qcjames53 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aidenfine commented Aug 31, 2026

Uh oh!

aidenfine commented Sep 1, 2026

Uh oh!

qcjames53 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aidenfine commented Aug 26, 2026 •

edited

Loading

qcjames53 left a comment •

edited

Loading