What does it do?
tendrl-ansible automates installation of Tendrl and helps with cluster expansion based description from Tendrl wiki. You should check installation documentation there to have basic understanding of various machine roles in Tendrl cluster before using tendrl-ansible.
How to get tendrl-ansible?
Just clone this repo:
$ git clone https://github.com/Tendrl/tendrl-ansible.git
or you can install rpm package from copr repo
tendrl/release with stable
# yum copr enable tendrl/release # yum install tendrl-ansible
See how to enable copr repository if you need more help with this step.
Note that installing tendrl-ansible from rpm package is highly recommended
when you use stable builds from
tendrl/release copr. Otherwise just cloning
the repo is good enough.
Which version of ansible do I need?
Ansible >= 2.4 is required to use tendrl-ansible.
What roles and playbooks are there?
This is a brief overview only, there is a README file for each role, where you can see more details about each role, along with list of ansible variables one can use to tweak it.
Ansible roles for Tendrl:
tendrl-ansible.tendrl-copr: installs yum repositories with builds provided by Tendrl project, it uses stable
tendrl/releasecopr by default
tendrl-ansible.tendrl-server: installation of Tendrl Server machine (where Tendrl api, web and etcd are running)
tendrl-ansible.tendrl-storage-node: installation of Tendrl Storage Node machines (Gluster servers, which you would like to monitor by Tendrl)
Roles installing yum repositories of Tendrl dependencies:
tendrl-ansible.grafana-repo: installs official upstream yum repository with latest stable Grafana release.
For convenience, there are also ansible roles for installation of yum
repositories with upstream releases of Ceph, Gluster and theirs installation
tools (such as
prechecks.yml: playbook checking requirements before Tendrl installation (see comments inside the playbook file for references)
site.yml: main playbook of tendrl-ansible, which one will use to install Tendrl
Where are the roles and playbooks if I use rpm package?
Ansible roles are available in
/usr/share/ansible/roles/ directory, where
the role directories are prefixed with
tendrl-ansible., for example:
Each role has it's own
README.md file, where you can find all details about
Playbooks are available in
1.6.0 is version of tendrl-ansible package.
What should I know before using tendrl-ansible?
Moreover since this README file can't provide all details about Tendrl, you should read Tendrl installation documentation as well.
And last but not least, both
tendrl-ansible.tendrl-storage-node roles contain
many variables which one can use to tweak the installation. See README files of
the roles for their description.
What installation steps from Tendrl installation documentation are not part of tendrl-ansible?
This should be clear from Tendrl installation documentation itself, but for the sake of convenience, here is the list of installation or deployment steps which are out of scope of tendrl-ansible:
- Deployment and installation of machines (either virtual or bare metal), which includes setup of networking, partitioning of disks, deployment of ssh public keys and so on.
- Installation and configuration of GlusterFS on the machines, see gdeploy for automation of this task.
- Setup of dedicated disk for etcd and graphite data directories.
- Setup of https for Tendrl web and api.
- Deployment of tls certificates and keys for etcd tls based client server encryption and authentication (this means communication between various tendrl components and etcd instance).
How do I install Tendrl with tendrl-ansible?
# yum install tendrl-ansible
See section "How to get tendrl-ansible?" in this README file for more details.
Create Ansible inventory file with groups for
gluster_servers. Here is an example of inventory file for 4 node cluster with Gluster:
[gluster_servers] gl1.example.com gl2.example.com gl3.example.com gl4.example.com [tendrl_server] tendrl.example.com
Add mandatory ansible variables into the inventory file you created in the previous step.
etcd_ip_addressconfigures where etcd instance is listening
etcd_fqdnconfigure tendrl components to be able to connect to etcd instance
graphite_fqdnconfigures tendrl components to be able to connect to graphite instance (this value doesn't reconfigure graphite itself!)
For simple example cluster from previous step, assuming there is only single network interface on all machines, the code you need to add into the inventory file would look like:
[all:vars] etcd_ip_address=192.0.2.1 etcd_fqdn=tendrl.example.com graphite_fqdn=tendrl.example.com
192.0.2.1is ip address of tendrl server,
tendrl.example.comis a hostname of tendrl server and
tendrl.example.comhostname is translated to
See full description in README file of
tendrl-ansible.tendrl-serverrole and pay attention to the values you specify there when you use multiple network interfaces on the machines.
Note: you can define these variables anywhere else you like (eg. in variable files or from command line directly), but including them into the inventory provides you with a single file with almost full description of tendrl-ansible setup for future reference (eg. reruning tendrl-ansible later when you need to expand cluster or make sure the configuration still holds). The only information not stored in inventory file which you may need in the future is
grafana_admin_passwdfile, which contains grafana admin password, which will be generated during tendrl-ansible run.
Add optional ansible variables into the inventory file.
Based on Tendrl documentation and description in README files of tendrl-ansible roles, specify values for variables you like to tweak.
This is important because some features tendrl-ansible can help you with are disabled by default as they require additional user input.
This includes etcd tls client authentication (
etcd_tls_client_authand other variables), tendrl notifier configuration for snmp or smtp (
tendrl_notifier_email_idand other variables), and other tweaks (eg.
There are also features such as firewalld setup for Tendrl (variable
configure_firewalld_for_tendrl) which are enabled by default, but can be disabled if needed.
If you use tendrl-ansible from rpm package, copy
site.ymlplaybook into working directory (where you already store the inventory file):
$ cp /usr/share/doc/tendrl-ansible-VERSION/site.yml .
Do the same for prechecks playbook:
$ cp /usr/share/doc/tendrl-ansible-VERSION/prechecks.yml .
Check that ssh can connect to all machines from the inventory file without asking for password or validation of public key by running:
$ ansible -i inventory_file -m ping all
You should see ansible to show
"pong"message for all machines. In case of any problems, you need to fix it before going on. If you are not sure what's wrong, consult documentation of ansible and/or ssh.
The following example shows how to use ansible become feature when direct ssh login of root user is not allowed and you are connecting via non-root
cloud-useraccount, which can leverage
sudoto run any command as root without any password:
$ ansible --become -u cloud-user -i inventory_file -m ping all
If this is your case, you may consider converting command line arguments related to Ansbile become feature into behavioral inventory parameters and adding them into the inventory file. This way, you don't need to specify these arguments again for every ansible command. Example of this update which matches previous command line example follows (it should be appended to the
After this edit, you can re run the ping example without become command line arguments:
$ ansible -i inventory_file -m ping all
Now you can run prechecks playbook to verify if minimal requirements and setup for Tendrl are satisfied. Any problem with the pre checks will make the playbook run fail immediately, pointing you to a particular requirement or problem with configuration before the installation itself (preventing you to spend time with unnecessary debugging after installation).
For production deployment, run the full check:
$ ansible-playbook -i inventory_file prechecks.yml
While for proof of concept deployments, you can avoid checking of stringent production requirements using
$ ansible-playbook -i inventory_file prechecks.yml --skip-tags "production"
If you are not sure why a particular check is there or what is checked exactly, open the playbook file and see comments and/or implementation of the check.
Then we are ready to run ansible to install Tendrl:
$ ansible-playbook -i inventory_file site.yml
Assuming we have deployed ssh keys on the machines and have Gluster trusted storage pool already installed and running there.
Log in to your tendrl server at
http://tendrl.example.com(hostname of Tendrl server as specified in the inventory file in step #2) with username
adminand default password
tendrl-ansible.tendrl-serverrole includes setup of admin user account for Tendrl (usable with both api and web interface), and that default password is
adminuser. Moreover the admin password is also stored on Tendrl Server machine in
/root/passwordfile (this feature of tendrl-ansible is based on TEN-257).
How do I expand cluster with tendrl-ansible?
See Tendrl wiki for full details of cluster expansion procedure. This section contains only brief overview of the expand operation for you to understand how tendrl-ansible fits into Tendrl cluster expand operation.
First of all, you need to install operating system and Gluster on new servers(s) and add them into existing cluster (aka Gluster Trusted Storage Pool) via peer probe and add bricks on new server(s) into existing gluster volume(s) based on your needs.
When Gluster is aware of new servers (you see them in output of
gluster pool listcommand), you add the new servers into ansible inventory file (into group
gluster_servers) which you used during installation of Tendrl.
Note that it's important to add new servers into the same inventory file as was used during installation, because you need to ensure that you are using the same set of ansible variables. For the same reason, you need to have the lookup file with password for grafana admin
grafana_admin_passwdavailabe in current directory.
Then, you rerun ansible playbook in the same way as done during Tendrl installation:
$ ansible-playbook -i inventory_file site.yml
During this run, ansible should report "ok" status for already existing machines, while reporting "changed" status for the new machines you just added.
Now, you should be able to see new servers in Tendrl web ui (see Tendrl documentation for details).
Does tendrl-ansible use some ansible tags?
Yes, tendrl-ansible uses ansible tags as listed below.
The purpose of these tags is to make debugging after installation easier by allowing to run particular type of tasks quickly without rerunning the whole tendrl-ansible playbook.
service-startedallows one to run just ansible tasks which enables (or starts) all services which Tendrl consists of. This is useful for checking that all services are running as expected.
firewalldallows one to run firewalld setup only, making sure that all ports are enabled. Note that the tag doesn't override ansible variable
configure_firewalld_for_tendrl, and if you have set it to
False, all firewalld tasks will be skipped.
- All yum tasks are tagged with
rpm-installation. This is useful for testing purposes only and there is no reason to use it in production.
Example: The following command will check that all ports are open via firewalld after installation of Tendrl. If all tasks are reported as "ok", the ports has been already opened as expected.
$ ansible-playbook -i inventory_file site.yml --tags firewalld
Distributed under the terms of the GNU LGPL, version 2.1 license, tendrl-ansible is free and open source software.