ansible-infra/README.md

# Abstract
## Presentation
This project aims to help me deploy and manage my homelab and a few other machines / services that I use, only for a personal purpose.
It is also an opportunity for me to learn and improve my knowledge of Ansible,the IaC side of operations and systems administration.

**What does it mean?**
The implications are that I will not be using external roles and collections unless they cover a part of my workflow that
I do not wish to implement or have low value for me.
The result of this premise is that this repository will probably not cover your use case and you should definitely not use this project as-is unless you
thoroughly reviewed it, especially the system hardening and security tweaks that are implemented.

## Roles
- ***common***: all configurations and tools that are deployed everywhere, e.g. basic utilities, common QoL tweaks, shell customization.
- ***development***: everything I use for development purposes, e.g. development tooling, assets and documentation creation, compilers and toolchains.
- ***gaming***: gaming on linux, e.g. Steam and Heroic Games Launcher.
- ***security***: security-related softwares and tweaks, e.g. applying custom system limits, installing an antivirus.
- ***server***: common tooling for servers, e.g. monitoring, altering, firewall rules.

# Usage
## Prerequisites
***Required dependencies***
- Python3.9+,
- PIP,
- Virtualenv

***Dependencies installed using the `Installation` instructions***
- [Task](https://taskfile.dev/),
- Debian packages:
  - curl
  - libcurl4-openssl-dev,
  - libssl-dev,
  - libcairo2,
  - libcairo2-dev,
  - libffi-dev,
  - python3-dev,
  - python3-virtualenv

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

## Installation
```shell
# Debian amd64
sudo apt install -y \
  curl \
  libcurl4-openssl-dev \
  libssl-dev \
  libcairo2 \
  libcairo2-dev \
  libffi-dev \
  python3-virtualenv \
  python3-dev;
TASK_VERSION=$(curl -fsSL -XGET https://api.github.com/repos/go-task/task/releases/latest | grep tag_name | tr -d ' ",' | cut -d ':' -f 2)
curl -fsSLO https://github.com/go-task/task/releases/download/"${TASK_VERSION}"/task_linux_amd64.deb;
sudo dpkg -i task_linux_amd64.deb;
rm task_linux_amd64.deb;
```

## Setup
```shell
# Generate default ansible configuration
./scripts/generate_ansible_config.sh > "${HOME}"/.ansible.cfg

# Setup Python virtualenv
task venv:setup

# Prepare and edit your inventory as needed
cp inventory/inventory.yml.dist inventory/inventory.yml

# Prepare and edit the global vault as needed
cp inventory/vault.yml.dist inventory/vault.yml
```

## Using Tasks
### Tasks
All tasks are available in `Taskfile.yml` and are executed at the root of the project.

#### molecule
Execute a molecule command, e.g. `task molecule -- converge` to create and populate a test container.

#### venv
Execute a command using the Python wrapper that activates the virtualenv, e.g. `task venv -- `

#### docker
*build*: build all docker images available in `/images`, e.g. `task docker:build`

*push*: push built images to docker hub, e.g. `task docker:push`

#### module:<module_name>
Directly execute a Python module located in `collections/ansible_collections/nullified/infrastructure/plugins/modules` with its default configuration
(typically the path to a test YAML file). Used only for debugging purpose.
Example call: `task module:github_artifact`.

#### test:collections
Executes molecule tests on each collections declared in `collections/ansible_collections`. Requires the collection to have a working molecule configuration.
Useful to ensure playbooks behave as expected using a Docker container.

#### test:modules
Run Ansible's sanity tests on each collections declared in `collections/ansible_collections`.

### Examples
```shell
# encrypt vault
task venv -- ansible-vault encrypt configuration/host_vars/vault.yml
# decrypt vault if needed
task venv -- ansible-vault decrypt configuration/host_vars/vault.yml
# run ansible command with vault-encrypted data for one specific host
task venv -- ansible-playbook --ask-vault-password -l my_host playbooks/test.yml
# run a specific role, e.g. security, for a host
task venv -- ansible --ask-vault-password -m import_role --args 'name=nullified.infrastructure.security' my_host
```

### Generic collection / roles commands
```shell
mkdir -p collections/ansible_collections
cd collections/ansible_collections
task venv -- ansible-galaxy collection init nullified.infrastructure
cd nullified/infrastructure/roles
task venv -- ansible-galaxy collection init tooling
```

---

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

# gather facts of a docker container
ansible <target> -m setup
```

```yaml
# 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:
- name: execute all handlers
  meta: flush_handlers
```

***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 collections to reside in;
- images: docker images, mostly used for ansible-test / molecule;
- inventory: all inventory related files are stored here;
- playbooks: top level playbooks, describe the way the infrastructure is laid out;
- scripts: various scripts and helpers;