149 lines
4.3 KiB
Markdown
149 lines
4.3 KiB
Markdown
# Abstract
|
|
## List of services
|
|
# 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
|
|
```
|
|
|
|
## Usage
|
|
```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
|
|
***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;
|
|
```yaml
|
|
# -> force handlers to run:
|
|
- 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 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;
|