Prepare the Ansible Environment

Prepare the Ansible Environment#

Section Components Description reviews all the Components that make up Carbonio.

This section describes the installation method using Ansible.

Ansible is free, open-source software that automates configuration and management tasks. The installation process relies on:

  • Ansible Galaxy

  • An Ansible playbook

  • An Ansible inventory file

The inventory file lists the Nodes on which the various Carbonio Components must be installed. Ansible reads this file and automatically executes all required tasks on the appropriate Node.

Once the Control Node - a workstation with Ansible installed from which Carbonio installations are launched (see Ansible Setup) - has been properly configured according to the instructions provided, the installation procedure requires only:

  1. Editing the inventory file

  2. Running a single CLI command to execute the playbook

Ansible Requirements#

You can run the Ansible playbook form any control node, which runs Linux, macOS, or BSD, satisfying the following requirements

Note

Using Ansible from a Windows control node is not straightforward: If you want to use the Ansible playbook from a Windows control node, please read the official Windows FAQ for setting it up.

Control Node requirements

  1. The control node has a working installation of Ansible (see Section Ansible Setup for directions)

  2. The control node has SSH access as the root user to all the Nodes on which Carbonio must be installed. This is necessary because Ansible needs to install packages and carry out various tasks which require root privileges.

    Hint

    You can temporarily copy the SSH key of the user on the control node to the .ssh/authorized_keys file of the Nodes’ root user

Carbonio installation and upgrade playbooks require the full Ansible package.

Ansible is distributed as a community bundle that includes:

  • ansible-core – the execution engine

  • A curated set of required collections and plugins

The ansible-core package alone provides only the execution engine and is not sufficient to run Carbonio install or upgrade playbooks.

Warning

Installing only ansible-core may cause playbooks to run but complete with errors due to missing collections and plugins.

For this reason, Carbonio install and upgrade procedures require the ansible package, not ansible-core alone.

Supported Versions

The supported ansible-core versions are >= 2.16.5

For more detailed information about available versions and compatibility between ansible and ansible-core, refer to the official Ansible documentation:

Nodes (Target) Requirements

In addition to the Carbonio Requirements that every Node must satisfy:

  1. For multi-node installations, each Node must:

    • Be equipped with the same supported OS (see section Software Requirements)

    • Be able to connect to the other Nodes via SSH without entering a password. For example, running:

      ssh root@<other-node>

      should log in directly without prompting for a password, which typically requires setting up SSH key-based authentication.

  2. Each Node must have the Carbonio repository configured (see section Configure repositories for setup instructions)

Ansible Setup#

This section guides you in the set up of a control node featuring Ansible (the Control Node) and the Carbonio Ansible playbook, with the purpose to install Carbonio on an existing infrastructure.

The control node should run on any Linux, macOS, or BSD box. Windows is supported but needs some work, therefore it is not mentioned here.

Install Ansible - Linux#

On Linux, Ansible can be installed using packages in the distribution’s repository, hence using the distribution’s package manager. Please refer to the official installation guide. This procedure pulls all the necessary dependencies, including python3.

To verify that installation was successful, run the following command on the control node

$ ansible --version

Install Ansible - macOS, BSD#

The best installation option on these platforms is to use homebrew, provided a python3 interpreter is installed on the system. You can follow these directions.

Install Carbonio Playbook#

Carbonio Playbook is available from Ansible Galaxy. Please ensure that you always have installed the latest playbook to be able to install the most recent Carbonio release.

Playbook for Carbonio installation
# ansible-galaxy collection install zxbot.carbonio_install -U

Configure Ansible#

You can configure Ansible using the ansible.cfg file. Please refer to the official documentation for directions.

Multiple Inventories#

If you plan to install multiple instances of Carbonio on different environments, we suggest that you create a dedicated directory to store the various inventories required for the different setups.

Contents