thulium_drake.ansible_controller

Build Status

Controller setup

This role sets up a system with a dedicated Ansible user for use as a Ansible Control Node.

It will:

  • Enable Ansible repository
  • Install ansible, ansible-merge-vars, ARA client
  • Download the Ansible Utils repository to your system (https://github.com/thulium-drake/ansible-utils)
  • Create a new user
  • Setup GPG agent for this user (Add your own GPG key, see below)

If you have a proxy, you need to set http_proxy_url, so this role is able to download all dependencies from PyPi.

EL 8.6+

In RHEL starting with 8.6 the ansible-core package is now included in the Appstream repository. As this role is intented to be used with Ansible Core (which only seems available in RPM format via these Appstream, Ansible Engine or Ansible Automation Platform repos), it will not configure any other repositories.

Should you desire to run Ansible Community edition, please install it from PyPi. And you still need to enable EPEL on your system for the following dependencies:

  • python-jmespath
  • pytho-netaddr

Ansible additional Python versioned dependencies

This role tries to autodetect the version on Ansible used to install the corresponding Python Packages. However, if it isn't able to detect the proper version of Python Ansible uses (e.g. when you have multiple versions installed from Pip), please set ansible_controller_python_version manually:

ansible_controller_python_version:
  major: 3
  minor: 12
  micro: 1

Ansible Projects

The Controller uses the concept of 'Ansible Projects', these are folders containing everything Ansible needs to do it's job. They should have the following structure:

.
|-- ansible.cfg                         # Ansible config
|-- cache                               # Fact cache
|-- collections                         # Collections required for the project
|-- files -> playbooks/files            # Convenience symlink to files
|-- group_vars -> inventory/group_vars  # Convenience symlink to inventory vars
|-- host_vars -> inventory/host_vars/   # Convenience symlink to inventory vars
|-- inventory                           # Directory with inventory files
|-- library                             # Any extra modules/plugins etc.
|-- playbooks                           # Playbooks
|-- requirements.yml                    # Ansible Galaxy requirements (roles and collections)
|-- roles                               # Roles required for the project
`-- scripts                             # Auxillary scripts for the project

The projects are stored in /opt/ansible/projects/<name-of-project> and are symlinked to the 'ansible' users' homedir.

If a project has extra resources (which are not stored in Git), those can be found in /opt/ansible/resources

Ansible Vault

Most (if not all) Ansible projects use secrets, it is very important to save the secrets in a safe, encrypted manner. Ansible provides ansible-vault for this purpose.

After creating a new project that has secrets (either encrypted vars files or encrypt_string vars in regular files), do the following to set up the project:

  • Set up retrieve_vault.sh
cd ~/projects/<name-of-project>
ln -s ../../vaults/retrieve_vault.sh .ansible_vault
echo 'my-ansible-vault-key' | gpg -e -r ansible@localhost > /opt/ansible/vaults/<name-of-project>
  • Set the vault_password_file to .ansible_vault in ansible.cfg

GPG Key

In order to allow for unattended runs, the 'ansible' user is set up to use GPG agent to hold a key once unlocked. A cronjob that checks if any keys are locked is run once per hour, it will generate a cron mail when locked keys are found.

In order to unlock the GPG key, run the gpgkey -u command and provide the passphrase.

To create a GPG key compatible for the Ansible Controller, follow the procedure below:

First you need a new (sub)key, note that if you want to add a EC key, your master key must be EC as well.

  • Generate a new key (if you already have one, skip these steps)
 gpg --expert --full-gen-key
  • Select 'ECC and ECC'
 9
  • Select 'Curve 25519'
 1
  • Set the expiration date (below sets the key to never expire)
 0
  • Accept the notification that the key will never expire
 y
  • Put in your name, email address and a comment (if you so desire)
 Ansible
 ansible@localhost
 Ansible Controller GPG key
  • Accept the changes
 o
  • Type in a strong passphrase

Now add a new subkey with the Authenticate flag

  • Open the GPG utility
 gpg --expert --edit-key KEYID
  • Add a new subkey
 addkey
  • Select 'ECC (set your own capabilities)'
 11
  • Disable 'Sign'
 s
  • Enable 'Authenticate'
 a
  • Exit the menu
 q
  • Select 'Curve 25519'
 1
  • Set the expiration date (below sets the key to never expire)
 0
  • Accept the notification that the key will never expire
 y
  • We really are sure...
 y
  • Put in your passphrase
  • Save and exit
 save
  • Create a new backup of the GPG keys
 gpg --armor --export-secret-keys > gpg-key.txt

Running Ansible jobs

After preparing the Controller, you can run Ansible jobs as follows:

Usage: /usr/local/bin/runansible [-p project] [-i inventory] [-s] playbook.yml

    -g           Update git checkout before running
    -p project   Name of the project to run the playbook from
    -i project   Name of the inventory to use, can be provided multiple times
    -r           Update roles before running playbook
    -s           Make Ansible's output sparse
    -h           This text

You can run this script with cron rules like the following:

0 0 * * * /usr/local/bin/runansible -sp <name-of-project> playbook.yml

The -s flag will reduce all output from playbook runs to stuff that has changed or is failed. Very useful for cron mails :-)

About

Ansible Controller with gpg-agent support

Install
ansible-galaxy install thulium_drake.ansible_controller
GitHub repository
License
gpl-3.0
Downloads
3.3k