Ansible Build¶

The Mint System collection of Ansible playbooks and roles.

Requirements¶

• Setup uv
• bash/zsh alias task='./task' with optional completion

Usage¶

Clone this repository.

git clone git@github.com:Mint-System/Ansible-Build.git

See task help for details about the project commands.

Setup¶

Navigate into the project folder.

cd Ansible-Build

Generate an Ansible vault id and password.

task generate-vault-password $VAULT_ID $PASSWORD

Create an Ansible configuration from the template.

cp ansible.cfg.template ansible.cfg

Install Ansible and Python dependencies.

task install

Create an inventory folder and configure a role.

Ansbile Documentation > Build Your Inventory

Roles¶

All Ansible roles are separted into

• system: OS runtime (docker, network, internet-related)
• environment: OS config (motd, packages, timezone, locale, etc.)
• service: Middleware/supporting services
• application: End-user applications

See roles for details or list the roles with:

task list-roles

Targets¶

All Ansible roles can be deployed to a Linux Server via SSH.

flowchart TD
    A[Host] -->|SSH| B[Server]

Ansible Vault¶

If you encrypt secrets with multiple vault identities, you can specificy the vault list in the ansible.cfg like this:

[defaults]
vault_identity_list = mint_system@.vault_pass_mint_system, example@.vault_pass_example

Or as an environment variable:

export ANSIBLE_VAULT_IDENTITY_LIST="mint_system@.vault_pass_mint_system, example@.vault_pass_example"

Alternatively you can configure the --vault-id parameter of the Ansible playbook command:

task play --vault-id mint_system@.vault_pass_mint_system ...

You can generate a secret with this command:

task encrypt-string mint_system "vault_postgres_password" "$(pwgen -c 20 1)"

Deploy¶

Deploy the roles to the target hosts with the following commands.

List hosts in inventory.

task list-hosts inventories/mint_system

Load virtualenv.

source task source

Test connection.

ansible all -m ping -i inventories/mint_system

Deploy multiple inventories.

task play -i inventories/mint_system plays/odoo.yml

Deploy Odoo stack.

task play -i inventories/mint_system plays/odoo.yml

Deploy role only.

task play -i inventories/mint_system plays/odoo.yml -t postgres

Deploy without dependencies.

task play -i inventories/mint_system plays/setup.yml --skip-tags depends

Deploy role to specific host.

task play -i inventories/mint_system plays/setup.yml -t docker -l server1

Deploy role to specific group with non-default user.

task play -i inventories/mint_system plays/setup.yml -t docker -l server1 -u username

Cleanup Odoo stack.

task play -i inventories/mint_system plays/cleanup.yml -t odoo,odoo_volume,odoo_data,postgres,postgres_volume

Cleanup role only.

task play -i inventories/mint_system plays/cleanup.yml -t docker_network

Cleanup dry run.

task play -i inventories/mint_system plays/odoo.yml -t odoo --check

List all Odoo databases.

ansible all -i inventories/mint_system -a "docker-postgres-list -c {{ postgres_hostname }}"

Development¶

This section is about developing the Ansible Build project.

New role¶

The easiest way to create a new role is to copy the postgres role. Then search and replace the variable prefix within the role folder and remove unecessary files.

cp -r postgres pgbouncer
cd pgbouncer
rm -r templates files
find . -type f -exec sed -i 's/postgres/pgbouncer/g' {} \;
mv tasks/postgres.yml tasks/pgbouncer.yml

Edit the role files manually and add the roles to the playbooks.

Quality assurance¶

Lint the project using Ansible lint.

task lint

Mapping environment variables¶

Whenever possible use env variables to configure the container.

Env Config

env:
  POSTGRES_USER: "{{ postgres_user }}"
  POSTGRES_PASSWORD: "{{ postgres_password }}"
  POSTGRES_DB: "{{ postgres_db }}"

Data persistence¶

To persist data use Docker volumes.

Volume Mount

Mount the folder without subfolder.

volumes:
  - "{{ postgres_volume_name }}:/var/lib/postgresql"

For Ansible config files use file mounts.

Bind Mount

volumes:
  - "{{ nginx_data_dir }}/:/etc/nginx/conf.d/:ro"

Role documentation¶

Every role folder must contain a README.md file.

Mark fix-me-comments with #FIXME: <your text>.

Naming conventions¶

Role names must be lower case and may contain an _.

Vars that are stored in vaults are prefixed with vault_.

Template for role vars:

# Url to Docker repsitory
rolename_image:
rolename_hostname:
rolename_port:
rolename_volume_name: "{{ rolename_hostname }}"
rolename_data_dir: "/usr/share/{{ rolename_hostname }}"
rolename_password: "{{ vault_rolename_password }}"

The reference roles are postgres and odoo.

Roles and tags¶

Roles can have multiple tags.

Example one tag

To define a Postgres role, you would:

• Create role postges
• Assign the tag postgres
• Create a task file postgres.yml

Example multiple tags

To define a Nginx role with a config tag, you would:

• Create role nginx
• Assign the tags nginx and nginx_config
• Create the task files nginx.yml and nginx_config.yml

In the main.yml you would include the tasks as followed:

- name: "Include {{ role_name }} config tasks"
  include_tasks: "{{ role_name }}-config.yml"
  when: nginx_data_dir is defined
  tags:
    - nginx
    - nginx_config

- name: "Include {{ role_name }} tasks"
  include_tasks: "{{ role_name }}.yml"
  when: nginx_image is defined
  tags:
    - nginx

Host aliases¶

Whenever a role is applied to the same host multiple times, you can create multiple aliases for the same host. Append a selected suffix to make a distinction between the aliases:

• main: Production environment.
• staging: Staging environment.
• dev: Development and test environment.
• upgrade: Upgrade environment.

Here is an example of an host with two aliases:

all:
  hosts:
    server_web:
      ansible_host: server.example.com
    server_main:
      ansible_host: server.example.com