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.:
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.:
```json
{"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
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:
```yaml
custom_disable_controlmaster:true
```
Save the file, [Update your Ansible Docker Framework](#install-ansible-docker-framework) and then update your container with `dans INVENTORYNAME update` which should from then on always ignore the ControlMaster.
