# Abstract
## List of services
# Usage
## Prerequisites
***Required dependencies***
- Python3.9+,
- PIP,
- Virtualenv
- [Task](https://taskfile.dev/),
- Debian packages:
  - libcurl4-openssl-dev,
  - libssl-dev,
  - libcairo2,
  - libcairo2-dev,
  - libffi-dev,
  - python3-dev,
  - python3-virtualenv

***Optional, dev-related dependencies***
- Docker

## Installation
```shell
# Debian amd64

TASK_VERSION=3.29.1;
sudo apt install -y \
  libcurl4-openssl-dev \
  libssl-dev \
  libcairo2 \
  libcairo2-dev \
  libffi-dev \
  python3-virtualenv \
  python3-dev;
wget https://github.com/go-task/task/releases/download/v"${TASK_VERSION}"/task_linux_amd64.deb;
sudo dpkg -i task_linux_amd64.deb;
task venv;
```

## General Setup
```shell
mkdir -p collections/ansible_collections
cd collections/ansible_collections
ansible-galaxy collection init nullified.infrastructure
cd nullified/infrastructure/roles
ansible-galaxy collection init tooling
```

---

## Cheatsheet
### Ansible usage
***validate files***
`ansible-playbook --syntax-check <file>`

***gather facts***
`ansible <target> -m setup`

***handlers***
invoked by a task through `notify`, executed only if caller triggered a state change; runs at the end of the play in the order
they are declared;
-> force handlers to run:
```yaml
- name: some task
  meta: flush_handlers
```

***looping***
looping in task by using the `loop` array with items to loop over;

***runtime grouping***
```yaml
name: coin
hosts: all
gather_facts: true
tasks:
  - name: group by OS
    group_by:
      key: "{{ ansible_facts.distribution }}"
```

***builtin vars***
- hostvars: {hostname => kvp_vars, ...},
- inventory_hostname(_short)?: name of current host,
- group_names: list of groups assigned to current host,
- groups: {groupname => [hostX, ...], ...},
- ansible_check_mode: isRunningInCheckMode ?,
- ansible_play_batch: list inventory hostnames active in current batch,
- ansibble_play_hosts: ist inventory hostnames active in current play,

### Python modules
***argument options***
> *NOTE*
> Ansible Up and Running, page 503

- *default*: default value if arg is required,
- *choices*: list of possible values for an array arg,
- *deprecated_aliases*: deprecate aliases; `dict(name, version, date, collection_name)`,
- *aliases*: aliases for given argument,
- *type*: arg type,
- *elements*: set type of list elements if arg is array,
- *fallback*: tuple of a lookup function and a list to pass to it,
- *no_log*: mask arg value in logs for sensitive data,
- *options*: complex args; create list of suboptions,
- *mutually_exclusive*: list of mutually exclusive suboptions,
- *required_together*: list of names of sub options,
- *required_one_of*: list of required mutually exclusive suboptions,
- *required_if*: sequence of sequences,
- *required_by*: dic mapping option names to seqs of option names

---

### Notes / Todo
***dir layout***
- collections: ansible root dir for all modules, playbooks and collections
- configuration: <DEPRECATED> ansible root dir for inventory
- images: docker images, mostly used for ansible-test / molecule
- scripts: scripts used by go-task

### Setup
```shell
cp configuration/group_vars/vault.yml.dist configuration/group_vars/vault.yml
# encrypt vault
ansible-vault encrypt configuration/group_vars/vault.yml
# decrypt vault
ansible-vault decrypt configuration/group_vars/vault.yml
# run ansible command with vault-encrypted data
ansible-playbook --ask-vault-password -i inventories/test playbooks/test.yml
```