3. Upgrading to 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 execution environment 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, execution environments allow the controller to run in a stable environment, while allowing you to add or update modules to your execution environment as necessary to run your playbooks. For more information, see Execution Environments in the Automation Controller User Guide.

3.1. Migrate legacy venvs to execution environments¶

You can have the exact same setup in an execution environment that you had in a prior custom virtual environment by migrating them to the new 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 execution environment (export_custom_venv)

Before you migrate, it is recommended that you view all the custom virtual environments you currently have running by using the awx-manage list command:

$ awx-manage list_custom_venvs

Below is an example output when running this command:

_images/venv-awx-manage-list-custom-venvs.png

The above output shows three custom virtual environments and their paths. If you have a custom virtual environment that is not located within the default /var/lib/awx/venv/ directory path, it will not be included here.

Use the _associations command to view what organizations, jobs, and inventory sources a custom virtual environment is associated with in order to determine which resources rely on them:

$ awx-manage custom_venv_associations /this/is/the/path/

Below is an example output when running this command:

_images/venv-awx-manage-custom-venv-associations.png

Select a path for the virtual environment that you want to migrate and specify it in the awx-manage export command:

$ awx-manage export_custom_venv /this/is/the/path/

The resulting output is essentially the results of executing a pip freeze command. The example shows the contents of the selected custom virtual environment:

_images/venv-awx-manage-export-custom-venvs.png

Note

All of these commands can be run with a -q option, which removes the instructional content provided on each output.

Now that you have the output from this pip freeze data, you can paste it into a definition file that can be used to spin up your new execution environment using ansible-builder. Anyone (both normal users and admins) can use ansible-builder to create an execution environment. See Building an Execution Environment in the Automation Controller User Guide for further detail.