Ansible Repository by PARAGON

This repository is a collection of playbooks, roles, plugins and inventories for multiple clients that PARAGON supports. It is build such that multiple clients could be installed on a single control host. However, by default the setup script installs the framework for an individual custumer so that those can use it for themselves too.

Installation

Before you can checkout the repositories from the server, you have to add your public SSH key to your user profile on the GitLab server. To do so, please go to https://gitlab.lakedrops.com/profile/keys and follow the instructions there. Please also note the link to instructions on how to generate it which also describes on how to prepare your local host to securly access the GitLab repositories.

Once that's been completed, proceed with these steps:

# Install Ansible: http://docs.ansible.com/ansible/intro_installation.html
# There you can find the relevant instructions for your local environment.
# The following example is for Ubuntu (for others refer to the link above):
sudo apt-get install software-properties-common python2.7 git
sudo apt-add-repository ppa:ansible/ansible
sudo apt-get update
sudo apt-get install ansible

# Patch Ansible, if required
# For this, see the next chapter with advise on which patch is required for which Ansible version.

# Create your Ansible home directory (e.g. /opt/ansible)
mkdir /opt/ansible

# Checkout the main repository
git clone git@gitlab.lakedrops.com:ansible-playbooks/general.git /opt/ansible --recurse-submodules
cd /opt/ansible

# Optionally install other OS requirements, only if it fails in subsequent ansible-script.py setup-local task
# Then you should also use the parameter --skip-os-tasks in the next step
# How to find out the requirements: please look into the playbooks/setup/ directory and look
# into the right file for your OS to see which components need to be installed 

# Setup or update
./ansible-script.py setup-local COMPANY [--username=REMOTEUSERNAME] [--skip-os-tasks]

Patching

From time to time there might be problems with an Ansible core update and if there is no other way, i.e. modifying our Ansible playbooks and roles, then we may have to patch Ansible core and here is a list of availables patches and the information which of them needs to be applied to which Ansible version:

You can find the patches in the files/patches sub-directory of this repository and the Ansible core directory, that needs to be patched, depends on the operating system and might be something like /usr/share/pyshared/ansible/

So, you may have to execute these steps:

cd /usr/lib/python2.7/dist-packages/ansible
patch -p1 < /opt/ansible/files/patches/FILENAME.patch

Again, the directories depend on your local installation.

Configuration

The above installation configures Ansible such that everything is good to go and you can call the ansible-script.py setup-local script again at any time to grab updates or restore settings if something got broken.

When using ansible-script.py setup-local the first time there will be two new files being created that you can use again in the future as shortcuts:

• /opt/ansible/update.sh which will update your installation by pulling all changed repositories and also running configuration of the current user
• /opt/ansible/config.sh which will just update the configuration for the current user

Important: if your remote username is different from your local username, you should call those scripts (ansible-script.py setup-local, update.sh, config.sh) with an additional parameter --username=[REMOTE USER NAME]. This will write that username into the ~/.ansible.cfg for future usage so as long as that name remains the same, you no longer have to use that parameter again.

Additional settings make the usage of Ansible more convenient and we're describing them here with detailed descriptions.

Ansible configuration

You'll find a file .ansible.cfg in your home directory after the setup from above and there are certain additional settings that could be usefull:

Working with a vault for automatic sudo password input

When using Ansible with this repository you'll get asked for your remote sudo password every single time. If you want to avoid that, you can store that password in a vault so that Ansible grabs it from there automatically.

Warning: Only use that if you have full control over the Ansible control host because otherwise someone else could get access to your whole server farm.

1. Create your vault password file Create a file named ~/.ansible/vault.pwd and edit that file so that it contains your local password for your Ansible vault.
2. Configure your vault password file To make sure Ansible is going to utilize your password file, insert the line vault_password_file = ~/.ansible/vault.pwd into .ansible.cfg in your home directory.
3. Create your vault Use the command ansible-vault create ~/.ansible/secrets and include one line ansible_sudo_pass: YOURSUDOPASS. This is using your default editor for the console but you can configure that like export $EDITOR=nano to use the nano editor as an example. When saving the file, ansible-vault will encrypt that file with your vault password contained in the vault.pwd file.
4. (Optional) Edit your vault file later on If you later want to edit your secrets, use ansible-vault edit ~/.ansible/secrets

AWS EC2: Boto configuration

If you want to use the dynamic AWS EC2 inventory, you should provide your access keys in a file /etc/boto.cfg with the following content:

[Credentials]
aws_access_key_id = <access key>
aws_secret_access_key = <secret key>

Note: The access key and secret key should be provided without the < brackets >.

In a multi-company environment the configuration file should provide different sections for each company that has hosts in AWS EC2:

[profile COMPANY1]
aws_access_key_id = <access key>
aws_secret_access_key = <secret key>

[profile COMPANY2]
aws_access_key_id = <access key>
aws_secret_access_key = <secret key>

Here you should replace COMPANY# with the lower case name of the relevant company.

JiffyBox configuration

If you are using a JiffyBox inventory, you have to provide your API token in a file /etc/jiffybox.cfg with the following content:

[Credentials]
api_token = <api token>

Note: The api token should be provided without the < brackets >.

In a multi-company environment the configuration file should provide different sections for each company that has hosts in JiffyBox:

[profile COMPANY1]
api_token = <api token>

[profile COMPANY2]
api_token = <api token>

Here you should replace COMPANY# with the lower case name of the relevant company.

Linode configuration

If you are using a Linode inventory, you have to provide your API key in a file /etc/linode.cfg with the following content:

[Credentials]
api_key = <api key>

Note: The api key should be provided without the < brackets >.

In a multi-company environment the configuration file should provide different sections for each company that has hosts in Linode:

[profile COMPANY1]
api_key = <api key>

[profile COMPANY2]
api_key = <api key>

Here you should replace COMPANY# with the lower case name of the relevant company.

Creating shortcuts for the scripts

All the scripts in this repository are written in a way that they can be called from everywhere, you don't have to chdir into the repository directory first.

For better convenience, we recommend to create shortcuts in a directory which is part of your PATH environment variable. Examples:

cd /usr/local/bin
sudo ln -s /opt/ansible/directory/ansible.py a
sudo ln -s /opt/ansible/directory/ansible-playbook.py apb
sudo ln -s /opt/ansible/directory/ansible-script.py ascr

Since version 1.2, the setup script is creating those links by default for you.

Preparing access to existing hosts

Ansible knows the hosts by name and the company specific naming convention should be reflected on each local host that wants to use Ansible to manage them. You'll find the hostnames in the file called inventory (if you have a static inventory) or for dynamic inventories this is an executibale file that you can call and it will list the known hosts to your console.

You should make sure that your local host knows all your remote hosts by name and their IP address. For this, add a new line for each of those hosts into your /etc/hosts file starting with the IP address followed by a space and the hostname from the inventory file.

You can also run ansible-script.py hosts and Ansible will update your local hosts file automatically.

Next, and this is the final piece before you can start using Ansible to access your hosts, make sure that you can access your hosts via SSH. This repository is built with security at the forefront and therefore access is only available through a PKI infrastructure. To configure your system for easy access, you should have a file $HOME/.ssh/config with some content similar to the following:

StrictHostKeyChecking yes
ForwardAgent no

Host *
  User [YOUR REMOTE USERNAME]
  IdentityFile ~/.ssh/id_rsa

The above setting applies to all hosts and the definition of the remote user name is only neccessary if that remote username is different from your local one. Please note that you should define the same username also in $HOME/.ansible.cfg

Where to go next?

The best place to continue reading is by heading over to the Wiki