Ansible Automated Operations

0.0 Requirements

0.1 Python Virtualenv

cd "$(git rev-parse --show-toplevel)"
# note: selinux-enabled machines (e.g., Fedora, CentOS, OpenSUSE) may require
# the --system-site-packages flag
python3 -m venv ./.venv
source ./.venv/bin/activate
pip install ansible

0.2 System Configuration

cd "$(git rev-parse --show-toplevel)/ansible"
ansible-playbook bootstrap-controller.yml

1.0 Conventions

1.1 environments

An environment is a collection of servers which has its own dedicated set of Ansible resources. Environments are for creating parallel sets of servers which are configured nearly exactly the same with the minimum possible amount of differences in order to test changes on less stable sets of servers prior to deploying them onto more stable sets of servers. Per-environment resources consit of:

• inventory file & ssh_config
• variables file
• secrets vault
• playbook runner utility

1.2 inventories

Each environment has its own inventory file which is located at ansible/inventory/{environ}. These inventory files should never contain variables; they are only for listing and grouping servers which are members of that environment.

Hostname/IP address information and other connection details should be stored in the environment ssh_config, which is located at ansible/inventory/ssh_config.d/{environ}. This file will also be written to by ansible in cases where a machine is provisioned by a playbook.

1.3 variables

Aside from the standard variable locations under group_vars and host_vars, each playbook will also source variables from an environment-specific vars file located at ansible/inventory/env_vars/{environ}.yml. Variables in these files will override values specified in group_vars and host_vars.

1.4 secrets

Each playbook will source an ansible-vault file located at ansible/inventory/vaults/{environ}.yml. The password used to decrypt the vault will be loaded from ansible/inventory/vaults/{environ}.password.

Vault files should only contain variable names prefixed with vault_, and the prefix should be followed by the variable name which will reference the vaulted value. Variables within vars files which reference secrets will then derefrence this vault variable name. For an example, see the linode_api_token variable in provider_linode.yml.

2.0 Utilities

Some helper utilities for working with local operational conventions are located at ansible/bin.

2.1 playbook runner

Usage:

ansible-playbook-{environ} [ansible-playbook-args ...] <playbook> [playbook ...]

Each environment must have its own playbook runner utility named ansible-playbook-{environ}. Playbooks should only be run using this utility, and never using the standard ansible-playbook command.

The playbook runner ensures that ansible-playbook is called with the correct inventory file, that the vault file is decrypted using the correct password, and sets up a special env_name variable which is used to load additional environment-specific resources.

2.2 envcp

Usage:

envcp <base-environ> <new-environ>

The envcp utility is used to copy a set of environment-specific resources from an existing environment into a new environment. The utility will also update the environment name within these resources at a few locations where it is known to appear. It is a good idea to double check the work of this utility and ensure that the base environment name does not appear in any unexpected locations within the newly copied resources.

2.3 envrm

Usage:

envrm <environ>

The envrm utility is used to effectively delete the passed environment by removing all of its environment-specific resources. Note that this utility only operates on local filesystem resources– it makes no attempt to tear down any servers or other provider resources which are managed under the environment.

3.0 Tasks

All commands assume $(git rev-parse --show-toplevel)/ansible as the working directory and a set ENV_NAME variable

View environment secrets

ansible-vault view --vault-password-file inventory/vaults/$ENV_NAME.password inventory/vaults/staging.yml

Add or change environment secrets

ansible-vault edit --vault-password-file inventory/vaults/$ENV_NAME.password inventory/vaults/$ENV_NAME.yml