Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Red Hat Ansible Automation Platform Upgrade and Migration Guide

Red Hat Ansible Automation Platform 2.0-ea

Upgrading to the latest version of Ansible Automation Platform and migrating legacy virtual environments to automation execution environments

Red Hat Customer Content Services

Abstract

Providing Feedback:
If you have a suggestion to improve this documentation, or find an error, please contact technical support at https://access.redhat.com to create an issue on the Ansible Automation Platform Jira project using the Docs component.

Automation hub acts as a content provider for automation controller, which requires both an automation controller deployment and an automation hub deployment running alongside each other. The Red Hat Ansible Automation Platform installer contains both of these. This section covers each component of the upgrading process:

  • Upgrade planning
  • Obtaining the installer
  • Setting up the inventory file
  • Running the setup playbook
  • Migrating from virtual environments to automation execution environments
Note

All upgrades should be no more than two major versions behind what you are currently upgrading to. For example, in order to upgrade to automation controller 4.0, you must first be on version 3.8.x. There is no direct upgrade path from version 3.7.x or earlier. Refer to the article, Recommended upgrade path on the Red Hat customer portal for more information.

In order to run automation controller 4.0, you must also have Ansible 2.10.

1.1. Upgrade planning
Copy link

This section covers changes that you should keep in mind as you attempt to upgrade your automation controller instance

  • Even if you already have a valid license from a previous version, you must still provide your credentials or a subscriptions manifest again upon upgrading to automation controller 3.8. See Import a subscription in the Automation Controller User Guide.
  • If you need to upgrade Red Hat Enterprise Linux and automation controller, you will need to do a backup and restore of your automation controller data. Refer to Upgrading an Existing Controller Installation for further detail.
  • Clustered upgrades require special attention to instance and instance groups prior to starting the upgrade. Refer to the Setting up the inventory file and see Clustering for details.
  • Prior versions of Ansible Tower used the variable name rabbitmq_host during installation. If you are upgrading from a previous version of Tower, and you previously specified rabbitmq_host in your inventory, simply rename rabbitmq_host to routable_hostname before upgrading. See Clustering for details.

Choose the Red Hat Ansible Automation Platform installer you need based on your Red Hat Enterprise Linux environment internet connectivity. Review the scenarios below and determine which Red Hat Ansible Automation Platform installer meets your needs.

Note

A valid Red Hat customer account is required to access Red Hat Ansible Automation Platform installer downloads on the Red Hat Customer Portal.

Installing with internet access

Choose the Red Hat Ansible Automation Platform installer if your Red Hat Enterprise Linux environment is connected to the internet. Installing with internet access will retrieve the latest required repositories, packages, and dependencies.

  1. Navigate to https://access.redhat.com/downloads/content/480
  2. Click Download Now for the Ansible Automation Platform <latest-version> Setup.

  3. Extract the files: 

    $ tar xvzf ansible-automation-platform-setup-<latest-version>.tar.gz

Installing without internet access

Use the Red Hat Ansible Automation Platform Bundle installer if you are unable to access the internet, or would prefer not to install separate components and dependencies from online repositories. Access to Red Hat Enterprise Linux repositories is still needed. All other dependencies are included in the tar archive.

  1. Navigate to https://access.redhat.com/downloads/content/480
  2. Click Download Now for the Ansible Automation Platform <latest-version> Setup Bundle.

  3. Extract the files: 

    $ tar xvzf ansible-automation-platform-setup-bundle-<latest-version>.tar.gz

1.3. Role-Based Access Controls
Copy link

Ansible Tower 3.7 contains minor updates to the Role-Based Access Control (RBAC) system. For the latest RBAC documentation, refer to the Role-Based Access Controls section in the Automation Controller User Guide.

Organization field on Job Templates

Job templates in automation controller now include an organization field in the API. This is set on creation based on the organization of the project used by the Job Template, and cannot be changed. Because of this, a project’s organization cannot be changed once it is in use by Job Templates.

This changes visibility and access to job templates. Previously, an admin of the organization that a job template’s inventory belonged to would also be granted admin access to the job template. While existing permissions are preserved on an upgrade to Ansible Tower 3.7, newly created jobs will only grant view access to the job template to the inventory admin in this scenario.

If upgrading from older versions of automation controller to 4.0 or later, the controller has the ability to detect previous versions of virtual environments associated with Organizations, Inventory, and Job Templates; and inform you that you will need to migrate to the new automation execution environments model. A brand new installation of automation controller creates two virtualenvs during installation—​one is used to run the controller itself, while the other is used to run Ansible. Like legacy virtual environments, automation execution environments allow the controller to run in a stable environment, while allowing you to add or update modules to your automation execution environments as necessary to run your playbooks.

Migrate legacy venvs to automation execution environments

You can have the exact same setup in an automation execution environment that you had in a prior custom virtual environment by migrating them to the new automation execution environment. Use the awx-manage commands in this section to:

  • list of all the current custom virtual environments and their paths (list_custom_venvs)
  • view the resources that rely a particular custom virtual environment (custom_venv_associations)
  • export a particular custom virtual environment to a format that can be used to migrate to an automation execution environment (export_custom_venv)

The below workflow describes how to migrate from legacy venvs to automation execution environments using the awx-manage command.

Use the following sections to assist with additional steps in the migration process once you have upgraded to Red Hat Ansible Automation Platform 2.0 and automation controller 4.0.

2.1.1. Listing custom virtual environments
Copy link

You can list the virtual environments on your automation controller instance using the awx-manage command.

Procedure

  1. SSH into your automation controller instance and run: 

    $ awx-manage list_custom_venvs

A list of discovered virtual environments will appear. 

# Discovered virtual environments:
/var/lib/awx/venv/testing
/var/lib/venv/new_env

To export the contents of a virtual environment, re-run while supplying the path as an argument:
awx-manage export_custom_venv /path/to/venv

View the organizations, jobs, and inventory sources associated with a custom virtual environment using the awx-manage command.

Procedure

  1. SSH into your automation controller instance and run: 

    $ awx-manage custom_venv_associations /path/to/venv

A list of associated objects will appear. 

inventory_sources:
- id: 15
  name: celery
job_templates:
- id: 9
  name: Demo Job Template @ 2:40:47 PM
- id: 13
  name: elephant
organizations
- id: 3
  name: alternating_bongo_meow
- id: 1
  name: Default
projects: []

Select the custom virtual environment you wish to export using awx-manage export_custom_venv command.

Procedure

  1. SSH into your automation controller instance and run: 

    $ awx-manage export_custom_venv /path/to/venv

The output from this command will show a pip freeze of what is in the specified virtual environment. This information can be copied into a requirements.txt file for Ansible Builder to use for creating a new automation execution environments image 

numpy==1.20.2
pandas==1.2.4
python-dateutil==2.8.1
pytz==2021.1
six==1.16.0

To list all available custom virtual environments run:
awx-manage list_custom_venvs
Note

Pass the -q flag when running `awx-manage list_custom_venvs`to reduce output.

Legal Notice
Copy link

Copyright © 2022 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top