4. Using virtualenv with Ansible Tower¶

4.1. Preparing a new custom virtualenv¶

You can specify a different virtualenv for running Job Templates in Tower. In order to do so, you must specify which directories those venvs reside. You could choose to keep custom venvs inside /var/lib/awx/venv/, but it is highly recommended that a custom directory be created. The following examples use a placeholder directory /opt/my-envs/, but you can replace this with a directory path of your choice anywhere this is specified.

1. Preparing a new custom virtualenv requires the virtualenv package to be pre-installed:

$ sudo yum install python-virtualenv

2. Create a directory for your custom venvs:

$ sudo mkdir /opt/my-envs

3. Make sure to give your directory the appropriate write permission, execution permission and ownership:

$ sudo chmod 0755 /opt/my-envs
$ sudo chown awx:awx /opt/my-envs

4. Optionally, you can specify in Tower which directory to look for custom venvs by adding this directory to the CUSTOM_VENV_PATHS setting as follows:

$ curl -X PATCH 'https://user:[email protected]/api/v2/settings/system/' \
    -d '{"CUSTOM_VENV_PATHS": ["/opt/my-envs/"]}'  -H 'Content-Type:application/json'

If you have venvs spanned over multiple directories, add all the paths and Tower will aggregate venvs from them:

$ curl -X PATCH 'https://user:[email protected]/api/v2/settings/system/' \
    -d '{"CUSTOM_VENV_PATHS": ["/path/1/to/venv/", "/path/2/to/venv/", "/path/3/to/venv/"]}' \
    -H 'Content-Type:application/json'

5. Now that a venv directory has been set up, create a virtual environment in that location:

$ sudo virtualenv /opt/my-envs/custom-venv

$ yum install gcc

$ yum install platform-python-devel

$ sudo /opt/my-envs/custom-venv/bin/pip install psutil

$ sudo /opt/my-envs/custom-venv/bin/pip install -U "ansible == X.Y.Z"

$ sudo /opt/my-envs/custom-venv/bin/pip install -U python-digitalocean

$ sudo /var/lib/awx/venv/ansible/bin/pip freeze

4.2. Assigning custom virtualenvs¶

Once you have created a custom virtualenv, you can assign it at the Organization, Project, or Job Template level to use it in job runs. You can set the custom venv on an inventory source to run inventory updates in that venv. Jobs using that inventory follow their own rules and will not use this venv. If an SCM inventory source does not have a venv selected, it can use the venv of its linked project. You can assign a custom venv on the organization, but if you do, it will not be used by inventory updates in the organization, as it is only used in job runs.

The following shows the proper way to assign a custom venv at the desired level.

PATCH https://awx-host.example.org/api/v2/organizations/N/
PATCH https://awx-host.example.org/api/v2/projects/N/
PATCH https://awx-host.example.org/api/v2/job_templates/N/
PATCH https://awx-host.example.org/api/v2/inventory_sources/N/

Content-Type: application/json
{
        'custom_virtualenv': '/opt/my-envs/custom-venv'
}

An HTTP GET request to /api/v2/config/ provides a list of detected installed virtualenvs:

{
        "custom_virtualenvs": [
                "/opt/my-envs/custom-venv",
                "/opt/my-envs/my-other-custom-venv",
        ],
...
}

You can also specify the virtual environment to assign to an Organization, Project, and Job Template from their respective edit screens in the Ansible Tower User Interface. Select the virtualenv from the Ansible Environment drop-down menu, as shown in the example below:

When you launch a job template, you will also see the virtualenv specified in the Job Details pane: