Skip to content

Fixes #615 - Add documentation for upgrade procedure #621

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aidenfine wants to merge 10 commits into
base: master
Choose a base branch
from
+83 −0
Open

Fixes #615 - Add documentation for upgrade procedure #621

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
8c464e3
Fixes #615 - Add documentation for upgrade procedure
qcjames53 Jul 2, 2026
cae3f9b
add foremanctl health recommendation
aidenfine Jul 23, 2026
93ffb11
Note that the Foreman repository is needed for foremanctl RPM deps
aidenfine Jul 23, 2026
bdd2ec7
Update source to "Foreman"
aidenfine Jul 23, 2026
0c2ad4f
typo fix
aidenfine Jul 23, 2026
c96ba8c
Add repo update steps and clean up docs
aidenfine Jul 27, 2026
f1ee6dc
remove lock steps
aidenfine Jul 27, 2026
f1157f0
Address PR comments
aidenfine Jul 28, 2026
510e93e
Add local repo mirror steps
aidenfine Jul 29, 2026
fa970e2
replace target naming with next
aidenfine Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,3 +46,23 @@ AI agent specifications (rules, skills, agent personas) live under `.agents/`.
- [Check Roles](docs/developer/checks.md) — check role catalog and integration patterns
- [Testing](docs/developer/testing.md) — test infrastructure, fixtures, patterns
- [Parameters](docs/user/parameters.md) — installation parameter map; update when adding parameters
Developer docs:
- [Check roles](docs/developer/checks.md) - How to integrate check roles; update as checks are created/modified
- [Container Image Builds](docs/developer/container-image-builds.md) - Info on image naming, registries
- [Deployment Architecture](docs/developer/deployment.md)
- [Development Environment](docs/developer/development-environment.md) - Dev environment setup with Foreman from source
- [How to Add a Feature](docs/developer/how-to-add-a-feature.md) - End-to-end feature development
- [Playbooks and Roles](docs/developer/playbooks-and-roles.md) - Playbook structure, naming, metadata
- [Testing](docs/developer/testing.md) - Additional info on test infrastructure, fixtures, patterns

User docs:
- [Backup](docs/user/backup.md) - How to back up your data
- [Certificates](docs/user/certificates.md) - Overview of certificate sources
- [Parameters](docs/user/parameters.md) - Map of Foreman installation parameters; update as parameters are created/modified
- [Upgrade](docs/user/upgrade.md) - How to upgrade your Foreman server through foremanctl

- [CONTRIBUTING](CONTRIBUTING.md) - How to contribute
- [Development](DEVELOPMENT.md) - Foremanctl development overview
- [IOP](docs/iop.md) - Overview of insights on premise
- [Migration Guide](docs/migration-guide.md) - Migrating from foreman-installer to foremanctl
- [Release](RELEASE.md) - Info on Foremanctl releases
17 changes: 17 additions & 0 deletions docs/developer/development-environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,23 @@ After deployment, the environment includes:
- `smart-proxy` and its plugins
- the development smart proxy registered into Foreman

### Upgrading from source

In a source install, git branches control versioning instead of RPM packages. Stable branches (e.g. `2.y-stable`) track a specific Foreman Y-stream, while the `master` branch tracks nightly changes (most recent).
Comment thread
ehelms marked this conversation as resolved.

All steps must be run as the root user. These steps assume that foremanctl is being ran from the same machine that Foreman was deployed on.

1. Please take a moment to determine your preferred Foreman version / git branch, we only support sequential updates.

@ianballou ianballou Jul 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't support anything on development environments, so people can git pull at will.

2. We recommend a full foremanctl backup before all upgrade operations. Run `foremanctl backup <filepath for backup>`. Please see [Backup](backup.md) for more information on this process.

@ianballou ianballou Jul 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While it's a good practice, I'm not sure how many people will be taking backups of their development environment. Actually, it makes me wonder if they're somehow incompatible with backup/restore.

3. Begin the upgrade by stopping all Foreman processes with `systemctl stop foreman.target`.
4. Switch to the preferred target branch:
- Switch to a stable Y-stream: `git fetch origin && git checkout origin/X.y-stable`
- Switch to nightly: `git fetch origin && git checkout origin/master`
5. Run upgrade tasks by re-deploying foremanctl with your customized deploy command: `foremanctl deploy [...]`. Please see [Parameters](parameters.md) for available deploy options.

This final 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.


## Architecture

### Service Integration
Expand Down
46 changes: 46 additions & 0 deletions docs/user/upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Upgrading foremanctl

Foremanctl releases bundle specific versions of Foreman with version-compatible dependencies and plugins.
Comment thread
aidenfine marked this conversation as resolved.

For nearly all install situations, upgrading your Foreman server should be approached through upgrading foremanctl. Scroll to the correct procedure below which matches your installation environment type (RPM, disconnected RPM, source).

## Upgrading foremanctl from RPM install

@ehelms ehelms Jul 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This procedure doesn't explain to the user where to get the new version of foremanctl. I would expect it to include managing the Foreman repository. I think the title here is also confusing as it talks about "upgrading foremanctl". But upgrading foremanctl inherently means also updating or upgrading Foreman. Right now, we do not support one without the other. Therefore, I think the focus needs to be on "How do I upgrade my installation from X.Y to X.Y+1"

@ianballou ianballou Jul 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@aidenfine it might help to run through the upgrading and updating guides in the existing documentation to understand how we handle defining repositories. I think the general strategy for how we manage the repo will stay the same.


All steps must be run as root user. We also recommend that a `foremanctl health` check is run before these steps.

1. Update the Foreman repository to the next X or Y release:
- `dnf upgrade https://yum.theforeman.org/releases/<next-version>/el9/x86_64/foreman-release.rpm`
2. Upgrade the foremanctl package:
- `dnf upgrade foremanctl`
3. Run upgrade tasks by re-deploying: `foremanctl deploy`. Please see [Parameters](parameters.md) for additional deploy options.

This final 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.

## Upgrading foremanctl from disconnected RPM install
Comment thread
aidenfine marked this conversation as resolved.

All below steps must be run as root user. We also recommend that a `foremanctl health` check is run before these steps.

Disconnected users should also create a local repository mirror of foreman, an example of this from Red Hat is linked here https://access.redhat.com/solutions/7019225.

1. Stage the foremanctl RPM package
- The Foreman repository is needed for dependencies related to the foremanctl RPM.
- The foremanctl RPM must be available in a repository accessible to your disconnected Foreman server. Please transfer the RPM to your disconnected system via an available transport mechanism (USB drive, rsync over a bastion, etc.).

@ehelms ehelms Jul 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the RPM enough? Or will they need the Foreman repository for dependencies?

@aidenfine aidenfine Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I recall you should also need the repo for the deps, let me test right now.

@aidenfine aidenfine Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ehelms Take a look I added an extra bullet point what do you think?

@ianballou ianballou Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would recommend telling users to stage the entire repository locally. python3.12-obsah is a dependency of foremanctl for example, and users may want to update it even if the update isn't a hard requirement. One reason could be for a CVE, for example.

- The foremanctl RPM can be downloaded from `https://yum.theforeman.org`
- Once staged, `dnf info foremanctl` will resolve as in a connected environment.
2. Stage the required container images
- On a connected machine, pull all required images with `foremanctl pull-images`.
- Confirm the correct images were downloaded by running `podman images` on both the connected and disconnected machines. All images from your previous-version disconnected environment should be present on the connected environment. If images are missing, ensure parameters are identical between machines.
- On the connected environment, run `podman save $(podman images --format "{{.Repository}}:{{.Tag}}" | tr '\n' ' ') -o <filename>.tar` to export all downloaded images as a tarball.
- Transfer the tar file to your disconnected environment via an available transport mechanism.
- Run `podman load -i <filename>.tar` to stage the required images.
3. Complete the [Upgrading foremanctl from RPM install](#upgrading-foremanctl-from-rpm-install) section above starting from step 3 to install from locally staged packages and images.

## Recovering from a failed upgrade

@ianballou ianballou Jul 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The troubleshooting section should probably have a section about varying Ansible errors, after which a user should probably open up an issue on GitHub or a post at community.theforeman.org.

@aidenfine aidenfine Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any link to common Ansible errors that may occur?


In the event of a failed upgrade, don't panic! A failed deploy will typically reveal the details of what went wrong and can give hints regarding the nature of your issue. Here are some troubleshooting steps:

#### (RPM install) `dnf upgrade foremanctl` had "Nothing to do"
Run `dnf versionlock list` to see if your system is configured to allow X or Y version upgrades. Update the versionlock using the steps above.

#### `foremanctl deploy` could not pull images from remote
Ensure that https://quay.io is unblocked on your network. You can manually open https://quay.io/foreman/foreman in a browser to view available images.