This repository is a framework around Ansible to make the daily usage more simple and straight forward. In this Wiki we're going to describe the usage of the main parts of it and show use cases on how you can get the most out of it.
The following instructions assume that you've created the shortcuts as described on the modules installation instructions on the front page. If not, please adjust the commands below accordingly.
There are admins and jail users that are all defined in the inventory and they are all available on all hosts of the inventory ready to go. Accessing the hosts is possible through SSH sessions only when you have the private key matching the public key that got installed for your user on each of the hosts.
As an admin you also can sudo into other user context including the root user. The same thing happens when you are running Ansible playbooks or Ansible commands - this is utilizing SSH and switches to root via sudo for most of the work that needs to be done remotely.
So, the first thing you should always do is to set your user password for each of the remote hosts:
You have to provide your current password first, before you can set a new one. For all new users on every host, this initial password set by Ansible during setup is My First Password.
Using prepared scripts
There is a framework in place that makes regular tasks really easy by preparing simple scripts that predefine all the command line arguments such that you only have to call the script to get the right things done.
Those scripts are stored in the scripts/ subdirectory and you call them with ansible-script.py or the shortcut ascr.
To get a list of all available scripts, simply call ascr list. All of those script support the Python help functionality so that you can easily find out all available options for each of those script by calling ascr SCRIPTNAME --help.
Using Ansible Playbooks
In general, Ansible playbooks get called by apb followed by the name of the playbook and optionally some additional parameters.
Display a list of all host name and their IP address
Limit the above list to the webservers only
apb list --limit=webserver
Copy a MySQL database from one host to another
apb mysqlcopy --extravars="sourcehost=DBHOST1 targethost=DBHOST2 dbname=DBNAME"
Move content from Swap back to RAM on a specific host
apb swap2ram --limit=HOSTNAME
Enable XDebug on all Drupal servers
apb xdebug --limit=webserver_drupal --extra-vars="enable=1 port=9000"
Disable XDebug on all Drupal servers
apb xdebug --limit=webserver_drupal --extra-vars="enable=0"
More prepared use-cases will be described below in a separate chapter. Also, the official Ansible documentation is a great source for further reading.
Using Ansible Commands
Sometimes you want to execute some commands on one or many remote hosts without writing a playbook for that as it is something you probably only want to execute once. This is possible by using the a command.
Check the accessibility of all remote hosts (they should all respond with a "pong")
a -m ping
Read the setup from all remote hosts
a -m setup
Update all settings on your ServerDensity account
a -m serverdensity
Read the settings from your ServerDensity account (write output to sd.json)
a -m serverdensity -a "readonly=true output=sd.json"
More details about all the modules and options available can be found over at the official Ansible documentation
On a daily basis you may want to call ascr sanity check which is reaching out to all your hosts and provide information about available updates. If any updates are available, you can call ascr sanity upgrade and Ansible will update all your hosts, checking that everything is OK. Sometimes, such updates require a reboot of the hosts and in such cases that requirement willl be displayed by Ansible. Then, call ascr sanity reboot and Ansible will reboot only those hosts that require it.
Setting up a new host
To setup a new host call ascr inithost HOSTNAME [OPTIONS] and this will call the inithost playbook and preparing your local environment as well as the remote host with all the basic configuration. In detail:
Configuring a host or your complete host farm
The most powerful piece is the farm playbook. If you call apb farm Ansible will configure all you hosts in the inventory according to the roles and their definitions. You can also run that on selected hosts by calling apb farm --limit=HOSTNAME or for a group of hosts like apb farm --limit=webserver.