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, create an issue at http://issues.redhat.com. Select the Ansible Automation Platform project and use the Documentationcomponent.

Chapter 1. Upgrading to Red Hat Ansible Automation Platform

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

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 link:ref:`import_subscription` in the |atu|.
  • 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.

1.2. Choosing and obtaining a Red Hat Ansible Automation Platform installer

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

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.

1.4. Additional resources (or Next steps)

  • A bulleted list of links to other material closely related to the contents of the assembly, including xref links to other assemblies in your collection.
  • For more details on writing assemblies, see the Modular Documentation Reference Guide.
  • Use a consistent system for file names, IDs, and titles. For tips, see Anchor Names and File Names in Modular Documentation Reference Guide.

Chapter 2. Upgrading to automation execution environments

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.

2.1. Migrating virtual envs to automation execution environments

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

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

2.1.2. Viewing objects associated with a custom virtual environment

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: []

2.1.3. Selecing the custom virtual environment to export

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.

2.2. Additional resources

Legal Notice

Copyright © 2021 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.