OmniChannel Ansible Playbooks

Overview

Ansible playbooks are a set of Ansible tasks or imported roles that are used to automate tasks. Playbooks are written in YAML and are used to define a set of plays. Each play is a set of tasks that are run primarily via ssh on servers, however we also support a number of playbooks using the local connection type. Playbooks are run from the command-line using the ansible-playbook command, or from AWX. Playbooks are used to automate tasks such as installing packages, configuring services, and deploying applications, setting up and configuring load-balancers, interacting with APIs, and more. Logic is expressed through a rich set of control structures, including conditionals, loops, and exception handling.

Playbook Directory Structure

An Ansible playbook has a predefined directory structure. A playbook directory structure contains directories: defaults, vars, tasks, files, templates, meta, handlers, etc. Each directory must contain a main.yml file which contains relevant content.

Example:

ansible_playbooks/
├── inventories/ # Ansible Inventories - inventory.ini, insights-controller.yml etc.
│ ├── group_vars/ # Group Variables - see [roles-overview.md](roles-overview.md) for more info
│ │ ├── cl1/ # Group Variables for cl1
│ │ ├── cl2/ # Group Variables for cl2
│ │ └── cl3/ # Group Variables for cl3
├── roles/ # Ansible Roles
│ └── requirements.yml # File to sync roles
├── ansible.cfg # Ansible Configuration File
├── playbook1.yml # Ansible Playbook 1
├── playbook2.yml # Ansible Playbook 2
├── templates/ # Jinja2 Templates
├── files/ # Files to be copied to the remote server
├── handlers/ # Handlers
├── vars/ # Variables
├── defaults/ # Default Variables
├── meta/ # Meta Data
├── tasks/ # Tasks
├── library/ # Custom Modules
├── filter_plugins/ # Custom Filters
├── plugins/ # Custom Plugins

Using Playbooks

To use playbooks from our shared playbooks repository, you can clone the repository and run the playbooks from the command-line. You can also use AWX to run or schedule playbooks, that's out of scope for this document however. To get started follow the instructions below. More on AWX can be found here.

1. Clone the repository

# Use this command if you don't have a registered SSH key with GitHub
git clone https://github.com/optum-omnichannel/ansible_playbooks.git

2. Install the ansible roles used by the playbooks

cd ansible_playbooks/roles
ansible-galaxy install -r requirements.yml --force -p .
cd ..

3. Run the playbooks - CLI

# For example, for running the playbook to display VM specs and details
# without disclosing data in the command-line

cat > inventory << EOF
[all]
localhost
EOF

cat > creds.yml << EOF
username: jdoe1
password: secret
EOF

cat > params.yml << EOF
serverName: myserver
EOF

ansible-playbook pb_specs_details_vm.yml -i inventory -e @creds.yml -e @params.yml

# If your ansible control host is private and disclosure is not a concern

ansible-playbook pb_specs_details_vm.yml \
  -i "localhost,"                        \
  -e {'userName': 'jdoe1', 'password': 'secret', 'serverName': 'myserver' }

4 Insights Inventory via CLI

To use the Insights datasource as an inventory on the CLI, you need to use the inventory configuration called insights-controller.yml in inventories. With it we can use the Ansible Insights or any other AWX inventory as a dynamic inventory source in cli playbook runs to aid in development of playbooks while templating jobs in awx, or just running playbooks from the CLI.

Step 1: run the following

ansible-galaxy collection install awx.awx

Step 2: add the following lines to your ~/.ansible.cfg

[inventory]
enable_plugins = awx.awx.controller, host_list, script, auto, yaml, ini, toml

Step 3: get your token

export CONTROLLER_USERNAME=<msid> # msid is your username without the domain
export CONTROLLER_PASSWORD='msid_password' # msid_password is your password
export CONTROLLER_HOST=https://omniawx.uhc.com # omniawx.uhc.com is the fqdn of the awx controller
export CONTROLLER_VERIFY_SSL=false # set to true if you have a valid cert on the awx controller
awx login -f human | tee token # this will prompt you for your password

Step 4: configure the following ENV vars accordingly in your .profile or .bashrc or create a separate file called awx.env you can source

export CONTROLLER_OATH_TOKEN=<your token> # this is the token you got from the last step
export CONTROLLER_HOST=https://omniawx.uhc.com/ # omniawx.uhc.com is the fqdn of the awx controller
export CONTROLLER_VERIFY_SSL=false

Step 5: After sourcing your .bashrc/.profile/awx.env from step 4, test the inventory

ansible-inventory -i ~/pathto/ansible_playbooks/inventories/insights-controller.yml --graph

If you get the inventory list at step 5, everything is working and you can use insights-controller.yml like any inventory source via command-line tools like 'ansible' and 'ansible-playbook' like so:

ansible -i ~/pathto/ansible_playbooks/inventories/insights-controller.yml -m ping -l VXML