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.
- ***workstation***: tooling and configuration for an X11 graphical workstation.

# Usage
## Prerequisites
- curl or similar,
- python3.9+,
- [go-task](https://github.com/go-task/task) (or follow the instructions below to install it),

```shell
# To install Task for a Debian (amd64) based system you can execute the following
TEMP_WORKDIR=$(mktemp -d)
cd "${TEMP_WORKDIR}"
# retrieve the latest available version's tag
TASK_VERSION=$(curl -fsSL -XGET https://api.github.com/repos/go-task/task/releases/latest | grep tag_name | tr -d ' ",' | cut -d ':' -f 2)
# retrieve the Debian archive
curl -fsSLO https://github.com/go-task/task/releases/download/"${TASK_VERSION}"/task_linux_amd64.deb
# retrieve the checksums file
curl -fsSLO https://github.com/go-task/task/releases/download/"${TASK_VERSION}/"task_checksums.txt
# ensure the downloaded archive is OK
sha256sum -c task_checksums.txt --ignore-missing
# install the tool
sudo dpkg -i ./task_linux_amd64.deb
cd -
rm -r "${TEMP_WORKDIR}"
unset TEMP_WORKDIR
```

## Setup
```shell
# Generate default ansible configuration
./scripts/generate_ansible_config.sh ./ansible.cfg

# Setup the project
task setup
# additionally install the dev dependencies if you need them
task setup:dev

# Prepare and edit your inventory as needed
cp inventory/inventory.yml.dist inventory/inventory.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 virtual env, e.g. `task venv -- `

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

#### module:\<module_name\>
Directly execute a Python module located in `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 `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 `ansible_collections`.

#### nosey
Run `noseyparker`, a tool that aims to find potential data leak such as passwords and security token.

#### ansible:new:collection:\<name\>
Creates a new collection `<name>` and add an exception in .gitignore in order to let git track it.
Example:
```shell
task ansible:new:collection:my_org.my_collection
```

#### ansible:new:role:\<name\>
Creates a new role `<name>` in the default or specified collection.
Examples:
```shell
#New role for the default (nullified.infrastructure) collection
task ansible:new:role:my_new_role
# New role the collection "my_org.my_collection"
COLLECTION_NAME=my_org.my_collection task ansible:new:role:my_new_role
```

### 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
```

## Advanced Configuration
### Global variables
Global variables are defined in `inventory/group_vars/all/vars.yml` and are used in multiple roles and playbooks.
- `dns.type`: what type of DNS configuration should be performed; also works as a selector for type related parameters;
- `dns.default`: default type of DNS configuration to setup; will use the corresponding `dns.<type>` dictionary retrieve corresponding data;
- `dns.udp`: IP addresses for basic DNS configuration;
- `dns.dot`: IP addresses for DNS-over-TLS configuration;
- `dns.doh`: IP addresses and HTTPS addresses for DNS-over-HTTPS configuration; 

## Notes
***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;