ansible_config_repo_scripts

A collection of useful scripts for ansible config repos

This is intended to be included as a submodule in an ansible config repo.

Requirements

• Ansible
• git
• Python 3 with the modules PyYAML, netaddr, and JMESPath

Ubuntu/Debian or other APT based systems

sudo apt install ansible git python3 python3-netaddr python3-jmespath python3-yaml

Nix/NixOS

If you have Nix, then nix-shell automatically makes the requirements available. The playbook script will automatically call nix-shell if it's present or you can launch it in a shell yourself. You may want to link/copy the shell.nix to the root of your config repo.

Usage

Ansible config repos are typically heavily based on git submodules. To update them (and also initialize them if they are not initialized yet), the script submodules may help.

---

The playbook.sh script is designed to run playbooks from anywhere.

$ # Syntax
$ playbook.sh <ansible_args> <playbook_name_without_yml>
$
$ # Example
$ playbook.sh -l hypervisor01 all

The special playbook all is generated by scripts/mkplaybook.py and doesn't exist physically.

mkplaybook

mkplaybook generates a playbook based on group memberships and roles.yml. For every role in the roles/ directory, a host group with the same name is assumed and a proper play is generated. The facts are only gathered once. For every role a tag is generated named _ROLENAME.

The roles.yml contains a dict with the role name as key and settings as values.

Name	Description
early	Run this role before all other non-early roles
late	Run this role after all other non-late roles
hosts	Also run this role on these hosts/groups
excludes	Short form for hosts: [ !HOST ]
after	Always run this role after the specified roles
tags	Apply these additional tags

Expected directory structure of parent repo

The script in this repository expect the following directories in the parent repo:

hosts

hosts should contain all host files with their variables. Each host has an own file hosts/<hostname>.yml. Additionally you can add files in hosts/<hostname>/. For example,

hosts/myhost/first.yml
hosts/myhost/second.yml

will result in a host myhost with the variables from first and second merged.

There is the special variable _groups which is the list of names of groups which the host is a member of. Every other variable is just passed to Ansible as variables applying to that host.

groups

groups/ should contain group files which specify group variables Each group has an own file, called groups/<groupname>.yml. Just as with hosts, you can additionally add files in groups/<groupname>/

There are three special groups:

• all contains all hosts (even though they don't list all in their _groups). Therefore groups/all.yml contains the default variables which apply to all hosts.
• ungrouped contains all hosts without any groups. This should however never be the case.
• virtual contains all hosts with a vm variable defined.

playbooks

All Playbook files should be located in groups/playbooks/. Each one should begin with a comment describing what it's supposed to do.

roles

All roles (typically as submodules) used in the repo.

files

Files which are used in the repo (e.g. config files used by roles).

modules

Custom modules used in the repo.

user.yml

The file user.yml is used to configure user specific settings like the ansible_user. This file should be in the .gitignore

roles.yml

A file containing some rules about the order of roles in the repo

Example:

---
# All roles with non-default values.
# Please sort the keys alphabetically within the three sections.

#####
# Early roles
#####

apt_sources:
  early: true
  hosts:
    - all
  after:
    - fstab
  tags:
    - common

fstab:
  early: true
  hosts:
    - all
  tags:
    - common

sudo:
  early: true
  hosts:
    - all
  tags:
    - common

#####
# Late roles
#####

upgrade:
  late: true
  hosts:
    - all

#####
# Normal roles
#####

grub2:
  after:
    - crypttab
    - fstab

icinga2-client:
  hosts:
    - all
  after:
    - icinga2-master
    - icinga2-scripts
  tags:
    - common

ansbile.cfg

The ansible config. It is important that the variable inventory is set to <path-to-this-submodule>/inventory.py

environment

A file with some environment variables. See below.

Special variables

Some important special variables are:

• _groups is a mandatory variable per host and is a list of groups that host is a member of
• ansible_host is a mandatory variable per host and is the IP address which ansible uses to connect to that host
• ansible_user is the username used to connect to the server.

The Ansible documentation lists more variables which are recognized by Ansible.

Environment

To ensure consistent playbook executions, the entire environment is dropped before the Playbook is ran. However, as some environment variables are needed for correct playbook exection, they can be set from files in the repository. There are two files both located in the repository root: ./environment and ./environment.local. While environment must exist and has to be committed, environment.local is optional and must not be committed. Both work in the same way having simple assignments in bash style. Lines may be empty or start with # to indicate a comment. Comments after assignments are treated as parts of the assignments. Assignments may contain blank characters.

Example:

# This is a comment followed by an empty line

SOME_VAR=some value
LANG=

Assignments with an empty value are filled from the parent environment (your shell). If the variable doesn't exist in the parent environment, it is ignored.

Ansible Galaxy Collections

The playbook.sh script takes a variable ANSIBLE_GALAXY_COLLECTIONS and installs the contained collections (separated by spaces) if they do not already exist in $HOME/.ansible/collections/ansible_collections. The ANSIBLE_GALAXY_COLLECTIONS variable can be given

• as an environment variable when, or
• as a variable in the environment file.

Example:

# ./environment
ANSIBLE_GALAXY_COLLECTIONS=community.general community.crypto community.mysql