Ansible installation¶

Ansible is an open-source agentless tool that facilitates the automation of software deployment. A supported version of Ansible (version 9 through 12) can be installed via pip into a Python virtual environment. This guide assumes that the necessary versions of Python (3.10 or later) and pip have been installed on the host that will be running the Ansible deployment (the Ansible controller). The streamlined instructions for the installation of Ansible are provided below.

Understanding Ansible Architecture

Ansible Controller: The machine where Ansible is installed and from which you run playbooks. This is where you execute ansible-playbook commands.

Target Hosts: The remote machines that Ansible manages and configures. These are the servers where VOR Stream will be deployed.

Ansible is only installed on the controller, never on target hosts (agentless architecture)
The controller connects to targets via SSH to execute tasks
Python requirements differ between controller and targets:
- Controller: Requires Python 3.10+ to run Ansible
- Targets: Use their system Python (e.g., Python 3.6 on RHEL 8)

For more details, see Ansible's basic concepts documentation.

Deploying to RHEL 8? Ansible 9 is required. DO NOT USE LATEST

If any of your targets are RHEL 8 targets, you MUST install Ansible 9 (not the latest version).

RHEL 8 uses Python 3.6 for its package manager (dnf), and Ansible 10+ requires Python 3.7 or higher (see ansible-core 2.17 release notes) on the target host. Installing the latest Ansible on the Ansible controller and attempting a deployment to a RHEL 8 target will result in the error below.

Error SnippetSample Detailed Error

SyntaxError: future feature annotations is not defined

TASK [Gathering Facts] ****************************************************************************************************************************************
Monday 04 August 2025  10:24:23 +0800 (0:00:00.004)       0:00:00.004 *********
[WARNING]: Unhandled error in Python interpreter discovery for host alma@orb: Expecting value: line 1 column 1 (char 0)
fatal: [alma@orb]: FAILED! => changed=false
  ansible_facts: {}
  failed_modules:
    ansible.legacy.setup:
      ansible_facts:
        discovered_interpreter_python: /usr/bin/python3
      exception: |-
        Traceback (most recent call last):
          File "<stdin>", line 107, in <module>
          File "<stdin>", line 99, in _ansiballz_main
          File "<stdin>", line 44, in invoke_module
          File "<frozen importlib._bootstrap>", line 971, in _find_and_load
          File "<frozen importlib._bootstrap>", line 951, in _find_and_load_unlocked
          File "<frozen importlib._bootstrap>", line 894, in _find_spec
          File "<frozen importlib._bootstrap_external>", line 1157, in find_spec
          File "<frozen importlib._bootstrap_external>", line 1131, in _get_spec
          File "<frozen importlib._bootstrap_external>", line 1112, in _legacy_get_spec
          File "<frozen importlib._bootstrap>", line 441, in spec_from_loader
          File "<frozen importlib._bootstrap_external>", line 544, in spec_from_file_location
          File "/tmp/ansible_ansible.legacy.setup_payload_seqf4950/ansible_ansible.legacy.setup_payload.zip/ansible/module_utils/basic.py", line 5
        SyntaxError: future feature annotations is not defined
      failed: true
      module_stderr: |-
        Traceback (most recent call last):
          File "<stdin>", line 107, in <module>
          File "<stdin>", line 99, in _ansiballz_main
          File "<stdin>", line 44, in invoke_module
          File "<frozen importlib._bootstrap>", line 971, in _find_and_load
          File "<frozen importlib._bootstrap>", line 951, in _find_and_load_unlocked
          File "<frozen importlib._bootstrap>", line 894, in _find_spec
          File "<frozen importlib._bootstrap_external>", line 1157, in find_spec
          File "<frozen importlib._bootstrap_external>", line 1131, in _get_spec
          File "<frozen importlib._bootstrap_external>", line 1112, in _legacy_get_spec
          File "<frozen importlib._bootstrap>", line 441, in spec_from_loader
          File "<frozen importlib._bootstrap_external>", line 544, in spec_from_file_location
          File "/tmp/ansible_ansible.legacy.setup_payload_seqf4950/ansible_ansible.legacy.setup_payload.zip/ansible/module_utils/basic.py", line 5
        SyntaxError: future feature annotations is not defined
      module_stdout: ''
      msg: |-
        MODULE FAILURE: No start of json char found
        See stdout/stderr for the exact error
      rc: 1
      warnings:
  - Platform linux on host alma@orb is using the discovered Python interpreter at /usr/bin/python3, but future installation of another Python interpreter could change the meaning of that
    path. See https://docs.ansible.com/ansible-core/2.18/reference_appendices/interpreter_discovery.html for more information.
  msg: |-
    The following modules failed to execute: ansible.legacy.setup

To install the latest Ansible 9, use the following command (see the detailed installation instructions for more guidance):

pip install --upgrade 'ansible<10'

Ansible Package vs ansible-core

When you install Ansible via pip, you're installing the Ansible package which includes ansible-core plus additional modules. The version numbers differ:

Ansible package 12.x includes ansible-core 2.19.x
Ansible package 11.x includes ansible-core 2.18.x
Ansible package 10.x includes ansible-core 2.17.x
Ansible package 9.x includes ansible-core 2.16.x

Our playbooks check for ansible-core 2.16 to 2.19, which corresponds to Ansible package 9.0.1 to 12.

Manual Installation into a Python Virtual Environment¶

The installations below are recommended to be done in a Python virtual environment.

Minimum Python Version Requirement for Ansible Controller

The required versions of Ansible outlined in this document require that Python 3.10 or higher is installed on the Ansible controller prior to installing Ansible. If Python 3.10 or later isn't already available on the host acting as the Ansible controller, install it by following directions on the Python website. If using RHEL 8 or 9 as the Ansible controller, the following command can be run to install the correct version of Python:

sudo dnf install python3.11

Create a Python 3 virtual environment.

Note

The following command assumes python3 points to the correct installation of Python. To verify this, run python3 --version. If it doesn't, you may need to specify the specific version instead of python3, e.g., python3.11.
```
python3 -m venv venv
```
Activate the virtual environment.
```
source venv/bin/activate
```
Upgrade pip and setuptools.
```
pip install --upgrade pip setuptools
```

Install Ansible.

Choose the correct command based on your target hosts:

For deployments where at least one target is RHEL 8:
```
pip install --upgrade 'ansible<10'
```
For deployments where all targets are RHEL 9:
```
pip install --upgrade 'ansible<13'
```

To verify the installation and check versions:

# Check Ansible package version
ansible --version
# This will show ansible-core version (e.g., 2.18.x for Ansible 11.x)

# Check installed package version
pip show ansible
# This will show the Ansible package version (e.g., 11.7.0)

The installation of Ansible can also be performed by following the steps outlined in the Ansible documentation.

Offline Installation from Deployment Package¶

Starting with VOR Stream 25.4.0, Ansible packages are included in the deployment package for offline installations. The artifacts for this are located in the directory ansible-core/artifacts and include:

python_packages Directory containing Ansible packages for Ansible 9 for both x86_64 and aarch64 architectures and installing into a Python virtual environment (Python 3.10, 3.11, 3.12, or 3.13)
requirements_ansible9.txt Requirements file for Ansible 9 (latest 9.x)

Tip

To automatically install these packages, use the provided setup-ansible-offline.sh script.

Offline Ansible Setup Script¶

For environments without internet access, use the provided Ansible packages from the deployment package.

From the root of the extracted deployment package, execute the setup-ansible-offline.sh script to automatically install Ansible using the packages:

Warning

Python 3.10 or higher must be installed (Python 3.11 recommended as it's available in package managers)
For RHEL-based 8/9 controllers, Python 3.11 can be installed with:
```
sudo dnf install python3.11 python3.11-pip
```
Run the script from the root directory of the extracted deployment package

$ ./setup-ansible-offline.sh
🔎 Detecting Python version...
✅ Found Python 3.11.
🛠️ Creating Python virtual environment with python3.11 at venv...

Verifying Ansible installation...
ansible [core 2.16.14]
  config file = None
  configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /package/venv/lib64/python3.11/site-packages/ansible
  ansible collection location = /root/.ansible/collections:/usr/share/ansible/collections
  executable location = /package/venv/bin/ansible
  python version = 3.11.11 (main, Aug 21 2025, 00:00:00) [GCC 11.5.0 20240719 (Red Hat 11.5.0-5)] (/package/venv/bin/python3.11)
  jinja version = 3.1.6
  libyaml = True

Ansible installed successfully!

To use Ansible, activate the virtual environment with:

    source venv/bin/activate