Ansible Build

Vercel .github/workflows/test.yml matrix-badge

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 or task 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

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]

Some Ansible roles can be deployed to a Kubernetes Cluster.

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, sozialinfo@.vault_pass_sozialinfo

Or as an environment variable:

export ANSIBLE_VAULT_IDENTITY_LIST="mint_system@.vault_pass_mint_system, sozialinfo@.vault_pass_sozialinfo"

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

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

To decrypt single strings run this command:

task encrypt-string sozialinfo "vault_rolename_varname: secret"

Deploy

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

List hosts in inventory.

task list-hosts inventories/setup

Load virtualenv.

source task source

Test connection.

ansible all -m ping -i inventories/odoo

Deploy multiple inventories.

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

Deploy Odoo stack.

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

Deploy role only.

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

Deploy without dependencies.

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

Deploy role to specific host.

task play -i inventories/setup plays/setup.yml -t docker -l host.example.com

Deploy role to specific group with non-default user.

task play -i inventories/setup plays/setup.yml -t docker -l host.example.com -u username

Clean Odoo stack.

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

Clean role only.

task play -i inventories/setup plays/clean.yml.yml -t docker_network

Clean dry run.

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

List all Odoo databases.

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

Kubernetes

Setup the following and the role's Kubernetes variables in your localhost inventory.

k8s_kubeconfig: /home/$USERNAME/.kube/config
k8s_namespace: default

Run the Kubernetes playbook for localhost.

task play -i inventories/k8s plays/k8s.yml.yml -l localhost

Development

This section is about developing the Ansible Build project.

Quality

Lint the project using Ansible lint.

task lint

Configuration

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

To persist data use Docker volumes.

Volume Mount

Mount the folder without subfolder.

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

For Ansible config files use file mounts.

Bind Mount

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

Docs

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.

Role 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

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.
  • int: Staging environment.
  • dev: Development and test environment.
  • upgrade: Upgrade environment.
  • dep: Deprecated environment.

Here is an example of an host with two aliases:

all:
  hosts:
    zeus_web:
      ansible_host: zeus.mint-system.com
    zeus_main:
      ansible_host: zeus.mint-system.com