Infrastructure Management

Abstract

This project, actively maintained and used, was originally created as a fun pet project to learn Ansible. It means that I did reinvent the wheel for many roles or tasks but that's the point. Because of that, roles are not published on Galaxy for now but that may change in the future.

I try to make things as secure and hardened as I can or care to but use this repository at your own risks. Bug reports are welcome, PRs too but will be under heavy scrutiny and may take a long time before being accepted or even acknowledged.

Usage

Prerequisites

• curl or similar,
• python3.9+,
• go-task (or follow the instructions below to install it),

# 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

# 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

Below is a description and some examples on what tasks are available. Most of them rely on a status mechanism to know whether they should run or not. In case you need to force the re-execution of a task you can pass the --force flag, like so: task --force <task_name>.

Tasks

Tip

Tasks marked with ♻️ are tasks that may require the --force flag to work as intended.

molecule

Execute a molecule command.

Examples:

# Run molecule up to the converge step
task molecule -- converge

# Run the destroy steps with one verbosity level enabled
task molecule -- -v destroy

nosey

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

setup ♻️

Run all the setup tasks described below, in the following order:

1. setup:requirements,
2. setup:venv,
3. setup:ansible,
4. setup:galaxy,
5. vault:init.

setup:ansible ♻️

Create an ansible.cfg file at the apex of the project. Should be called with the --force flag if the project is moved or if the Ansible base configuration should be actualized.

setup:dev

Install required Ansible Galaxy collections. Call with the --force flag if new dependencies have to be installed.

setup:galaxy

Install Ansible dependencies from Galaxy. Call with the --force flag if new dependencies have to be installed.

setup:requirements

Install required system dependencies (only Debian is supported / tested at the moment).

setup:venv ♻️

Set up the python virtual environment and install the required dependencies. Call with the --force to completely reinstall it.

venv

Execute a command using the Python wrapper that activates the virtual env. Examples:

# Execute the Ansible playbook internal.yml with the verbose flag, only for the host myhost and only for tasks tagged
# with dotconf:
task venv -- ansible-playbook -v ./playbooks/internal.yml -l myhost -t dotconf

# Run the Ansible setup module on localhost to list all available facts
task venv -- ansible -m setup localhost | less

ansible:​new:collection:<namespace>.<collection>

Create a new collection <collection> in the directory ansible_collections/<namespace>. Example:

task ansible:new:collection:my_namespace.my_collection

ansible:​new:role:<name>

Create a new role <name> in the default or specified collection. Examples:

#New role for the default collection (nullified.infrastructure)
task ansible:new:role:my_new_role

# New role the collection "my_namespace.my_collection"
COLLECTION_NAME=my_namespace.my_collection task ansible:new:role:my_new_role

docker:build ♻️

Warning

Deprecated: molecule now uses Vagrant instead of Docker.

Build all docker images available in /images

molecule:purge

Nuke everything molecule uses to run tests. Useful when Vagrant / libvirt won't restart the VM or the firewall rules are messed up. It will:

1. destroy all existing domains and volumes in libvirtd,
2. run the molecule destroy command,
3. restart nftables (and thus purging it),
4. restart libvirtd (recreates firewall rules),
5. restart docker (recreates firewall rules as well).

test:collections

Warning

Unmaintained: only molecule tests are used for now, and only one collection exists.

Execute 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:module:github_artifact

Warning

Unmaintained: only molecule tests are used for now, and only one collection exists.

test:modules

Warning

Unmaintained: only molecule tests are used for now, and only one collection exists.

Run Ansible's sanity tests on each collections declared in ansible_collections.

vault:init

Note

Requires that a password store repository has already been initialized.

Initialize a password-store entry and create a random password; no-op if the vault has already been initialized.

vault:encrypt

Encrypt all vault.yml files found anywhere in the project, except for files in the .venv directory, using the password-store entry created by vault:init. Will print an error if a vault is already encrypted but will continue nonetheless.

vault:decrypt

Same as vault:encrypt but will instead decrypt files.

Roles

• caddy: install Caddy, a powerful web server,
• common: all configurations and tools that are deployed everywhere, e.g. basic utilities, common QoL tweaks, shell customization,
• crowdsec: install Crowdsec, a participative security solution,
• deluge: install Deluge, a daemon and web UI solution for using Torrents,
• development: everything I use for development purposes, e.g. development tooling, assets and documentation creation, compilers and toolchains,
• dotconf: install .conf related files (e.g. emacs, zsh, ...),
• forgejo: install Forgejo, a lightweight software forge that replaces Git{hub,lab},
• gaming: gaming on linux, e.g. Steam and Heroic Games Launcher.
• golang: install Golang and related binaries,
• helm: install Helm, a package manager for Kubernetes,
• k3s: install k3s, a simplified Kubernetes stack from Rancher and the CNCF,
• kubectl: install kubectl, a CLI tool to manage K8s clusters,
• mariadb: install MariaDB, an open source fork of MySQL,
• nginx: install Nginx, a common web server,
• postgresql: install Postgres, a powerful multipurpose database,
• provisioner: configure systems that will act as deployment origins for all Ansible playbooks; used for persistent states (e.g. terraform states) and coordination for more complicated roles,
• searxng: install SearxNG, a metasearch engine that yields better results than common search engines,
• security: security-related softwares and tweaks, e.g. applying custom system limits, installing an antivirus.
• valkey: install Valkey, an open source fork of Redis,
• vault: install Vault, a secrets manager,
• workstation: tooling and configuration for an X11 graphical workstation.
• xbackbone: install XBackBone, a file manager used for sharing files with people.