diff --git a/AGENTS.md b/AGENTS.md index bbd3de02c..6ec561348 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/docs/developer/development-environment.md b/docs/developer/development-environment.md index f6db26fff..eed522f26 100644 --- a/docs/developer/development-environment.md +++ b/docs/developer/development-environment.md @@ -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). + +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. +2. We recommend a full foremanctl backup before all upgrade operations. Run `foremanctl backup `. Please see [Backup](backup.md) for more information on this process. +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 diff --git a/docs/user/upgrade.md b/docs/user/upgrade.md new file mode 100644 index 000000000..eaf4f038c --- /dev/null +++ b/docs/user/upgrade.md @@ -0,0 +1,46 @@ +# Upgrading foremanctl + +Foremanctl releases bundle specific versions of Foreman with version-compatible dependencies and plugins. + +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 + +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//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 + +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.). + - 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 .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 .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 + +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.