installation.md

title: Install Ansible Docker Framework 
repo: https://gitlab.lakedrops.com/ansible/playbooks/ansiblemaster
issues: https://gitlab.lakedrops.com/ansible/playbooks/ansiblemaster/-/issues
tags:
- ansible

Installation and configuration

Preparation

You can define certain variables which will be made available to all inventory containers automatically.

Global variables go into /etc/ansible.yml and may contain information about GitLab and Mattermost but also many other things you will need globally, e.g.:

gitlab_issue:
  url: 'https://gitlab.lakedrops.com'
  token: '[PRIVATETOKEN]'

inventories:
  - 'name1'
  - 'name2'

mattermost_hooks:
  name1: 'https://mattermost.lakedrops.com/hooks/[TOKEN1]'
  name2: 'https://mattermost.lakedrops.com/hooks/[TOKEN2]'

In this example, name1 and name2 are examples/placeholders for real inventory names that you're working with. You can find the list of available inventories to you by going to https://gitlab.lakedrops.com/ansible-inventories and grab the name(s) for each inventory. The [TOKENs] for Mattermost are available from each of the inventories project pages.

The [PRIVATETOKEN] can be generated at https://gitlab.lakedrops.com/profile/personal_access_tokens

Host specific variables, that only should be used on specific Ansible masters, go into /etc/ansible/facts.d/ansiblemaster.fact. Those require JSON specification, e.g.:

{"host_is_scheduler": true}

If you don't know what to put into this, just ignore that part.

Install Docker

If Docker is not yet installed on your host, please refer to https://docs.docker.com/install

Install Ansible Docker Framework

docker pull registry.lakedrops.com/ansible-playbooks/ansiblemaster:latest

# On Ubuntu and other Linux systems:
docker run -it --rm \
    --volume ~/.a:/root/.a \
    --volume /etc/ansible.yml:/etc/ansible.yml \
    --volume /etc/ansible/facts.d:/etc/ansible/facts.d \
    --volume /usr/local/bin:/usr/local/bin \
    registry.lakedrops.com/ansible-playbooks/ansiblemaster:latest

# On MacOS:
docker run -it --rm \
    --volume ~/.a:/root/.a \
    --volume /private/etc/ansible.yml:/etc/ansible.yml \
    --volume /private/etc/ansible/facts.d:/etc/ansible/facts.d \
    --volume ~/bin:/usr/local/bin \
    registry.lakedrops.com/ansible-playbooks/ansiblemaster:latest

This process is setting up your localhost as the Ansible master based on Docker and it creates 2 scripts (dans and dans-all) in your /usr/local/bin (or ~/bin on MacOS) directory. Those 2 scripts are used to operate Ansible tasks on all your different inventories you have access to.

Notes on MacOS: Probably the ~/bin directory is not included in your search path for executables. If so, please make sure to add it first.

Usage

Login to the LakeDrops Docker repository

The Ansible Docker images for the inventories are private and can only be downloaded and used by authenticated users.

docker login registry.lakedrops.com

This asks for your username and password for that registry which is the same as your credentials for https://gitlab.lakedrops.com - you only need to login once, your authentication is persistent on your localhost and normally you shouldn't have to re-login in the future, unless Docker asks you to do so again in case the authentication expired.

Download and later update your Docker container

For each inventory you will get an individual Docker container which is running in the background and those containers bring everything with them, you don't have to configure anything. To initially download and later update any of your inventory containers, call

dans INVENTORYNAME update

This will download the Docker image for that inventory and start a Docker container for it which you can then start using for all your Ansible operations. If you operate with mutliple inventories, you can also update them all at once with the second script

dans-all update

This works for all commands also explained below, dans INVENTRORYNAME works for the fiven inventory only where dans-all works for all available inventories at once.

Running Ansible commands

To get a list of all prepard Ansible scripts, call

dans INVENTORYNAME

without any further arguments. This will give you a long list of scripts and to learn more about any of them just call

dans INVENTORYNAME SCRIPT --help

To run a playbook which isn't covered by a script (yet), you can use the script called playbook which even allows you to run a custom playbook that's only available for a specific inventory, e.g.

dans INVENTORYNAME playbook deploy --custom=yes

In general terms, all the commands that have been documented as apb PLAYBOOK ...args... can be called in the Docker context as dans INVENTORYNAME playbook PLAYBOOK ...args...

Shell into Ansible inventory containers

Sometimes, e.g. for testing or debugging purposes, you may want to get into one of the containers which is easy with

dans INVENTORYNAME exec

Trouble shooting

This suite has been tested on Ubuntu and MacOS but of course, things can still go wrong. IN this section we are collecting recommendations on what you can do in case, things are not working.

Ansible is very slow

By default, Ansible send log messages to your host on port 24224 where a FluentD service could be listening which stores those logs for later investigation. If no service is listening, this is usually ignored but we've seen some hosts where this slows down Ansible startup time significantly. For those cases, you should explicitly turn off FluentD logging with these steps:

Edit or create the file ~/.a/environment and add a line FLUENTD_LOGGING=no. Then force updating your containers by calling dans INVENTORYNAME forceupdate.

Ansible reports errors UNREACHABLE

This can have a lot of reasons. Please check the following options:

• Are your credentials (remote username and password) correct? You know, typos can happen. So please check the files ~/.a/environment for the username and ~/.a/variables.yml for the password. If one of them contained a mistake, please correct that and update your container with dans INVENTORYNAME update
• Is your private key contained in ~/.ssh/id_rsa the correct one for the hosts in your inventory? If not, please correct that and update the containe.

If none of that helps, please run dans INVENTORYNAME debug and copy the very verbose output into an issue here in this project, so that we can analyze the problem further.

SSH ControlMaster not working in your environment

In some environments, the SSH ControlMaster is not working properly so that we included the option to disable it. To do that, edit the file /etc/ansible.yml on your host and add the following definition:

custom_disable_controlmaster: true

Save the file, Update your Ansible Docker Framework and then update your container with dans INVENTORYNAME update which should from then on always ignore the ControlMaster.