Ansible Leapp Collection

Description

This collection provides Ansible roles for RHEL in-place upgrades using the Leapp framework (and, for older paths, Preupgrade Assistant and Red Hat Upgrade Tool). Running upgrades at scale across a large estate needs automation tailored to your environment; these roles are intended as the foundation for that solution.

Who should use it: Platform engineers, automation teams, and anyone automating supported RHEL upgrade paths with Ansible.

What you can do: Run pre-upgrade analysis, perform upgrades, and assist with remediation using consistent, parameterized roles.

Roles

These roles are included in the collection. Each has a README and examples under its directory.

• roles/analysis — Leapp pre-upgrade phase (or Preupgrade Assistant on RHEL 6)
• roles/remediate — Help remediate systems after pre-upgrade
• roles/upgrade — Leapp OS upgrade (or Red Hat Upgrade Tool on RHEL 6)

Supported RHEL upgrade paths

The collection supports in-place upgrades for the following paths (using Preupgrade Assistant and Red Hat Upgrade Tool, or Leapp as indicated):

• RHEL 6 to RHEL 7 (Preupgrade Assistant and Red Hat Upgrade Tool)
• RHEL 7 to RHEL 8 (Leapp)
• RHEL 8 to RHEL 9 (Leapp)
• RHEL 9 to RHEL 10 (Leapp)

Important

Not every path may be supported in the same way by Red Hat product support. See RHEL In-place upgrade Support Policy and Supported in-place upgrade paths for Red Hat Enterprise Linux for current guidance.

The roles have been used in varied environments: on-prem bare metal and VMs with packages from Red Hat CDN, Satellite content views, or internal mirrors (including disconnected layouts). RHEL on Amazon EC2 with BYOS CDN or pay-as-you-go RHUI has been tested; other public clouds are generally feasible when you set the documented role variables for your subscription and repos.

Example playbooks live under playbooks/.

Out of scope

The upgrade role does not upgrade third-party products or non-RHEL package sets. For a full stack upgrade you may need extra automation for agents, clustered storage, databases, and similar (for example Veritas InfoScale clustering or SAP HANA on RHEL). Packages from non-RHEL repos (for example Red Hat Software Collections, EPEL, RPM Fusion) are not handled by the role as RHEL content.

Many workloads remain compatible after an in-place upgrade under RHEL application compatibility guidance; validate in non-production before production cutovers.

Requirements

• Ansible / ansible-core: Must satisfy requires_ansible in meta/runtime.yml. Use an ansible-core and Automation Platform release that meets that constraint and your organization's support policy.
• Python: Use the Python versions supported for your control node or execution environment together with your chosen ansible-core (see Ansible Automation Platform documentation).
• Collection dependencies: This collection requires fedora.linux_system_roles.

Important

Managed-node compatibility depends on the Ansible version on the controller. See Ansible Core compatibility with RHEL 7 and RHEL 6 managed nodes and Red Hat Ansible Automation Platform life cycle. Ensure the combination of meta/runtime.yml, your Ansible version, and target OS versions is valid for your scenario.

Installation

Ansible or ansible-core is supplied with Ansible Automation Platform and its execution environments; this section describes installing the collection (for example from automation hub or Ansible Galaxy) using the CLI.

Before using this collection, install it with the Ansible Galaxy command-line tool:

ansible-galaxy collection install infra.leapp

You can also list it in a requirements.yml and install with ansible-galaxy collection install -r requirements.yml:

---
collections:
  - name: infra.leapp
    version: "*"
  - name: fedora.linux_system_roles # or redhat.rhel_system_roles see roles README for more details
    version: "*"

Use redhat.rhel_system_roles where documented in role READMEs if that fits your environment instead of fedora.linux_system_roles.

To upgrade the collection to the latest published version:

ansible-galaxy collection install infra.leapp --upgrade

To install a specific version (example: 1.0.0):

ansible-galaxy collection install infra.leapp:==1.0.0

See Using Ansible collections for more details.

Contributing

We are a fledgling community and welcome any new contributors. Get started by opening an issue or pull request. Refer to CONTRIBUTING.md for more information.

Support

This collection is Red Hat Ansible Certified Content, distributed on Red Hat Ansible Automation Hub under the redhat namespace for use with Red Hat Ansible Automation Platform.

If you have a Red Hat subscription: use Red Hat Customer Support (access.redhat.com/support) for Ansible Automation Platform and subscription assistance. For problems with the certified collection build on Automation Hub, use the Create issue button at the top right of this collection's page in the hub so your case is handled under your entitlement.

Release Notes and Roadmap

• Release notes / changelog: CHANGELOG.rst and changelogs/changelog.yaml.
• Roadmap: No separate public roadmap document; follow the changelog and repository activity for upcoming changes.

License Information

This collection is published under the MIT license. The full text is in the LICENSE file.