====== Ansible ======

**General Information**

Ansible is a tool for performing remote tasks on systems. (either ad-hoc or via "playbooks")

You will need to use ansible as a user that has ssh keys setup on systems so you are not prompted for passwords during parallel command operations. 

\\
If you already have Ansible installed/configured, [[linux_wiki:ansible_playbook_downloads|playbook downloads can be found here]].

**Checklist**
  * Distro(s): Any

----

====== Install ======

Ansible comes in many distributions repos already.

CentOS 7
<code bash>
yum install ansible
</code>

----

====== Configure ======

Main Ansible config file
  * /etc/ansible/ansible.cfg
    * Edit this file to point Ansible to your inventory files.

===== Repo Controlled =====

It is highly recommended to put Ansible playbooks, roles, and inventory into version control. (Example: git or svn)

One suggested directory structure/workflow is:
  * Shared, read-only/production use at:
    * /ansible/
  * Each system administrator would then clone a copy of the repo into their home directory for local changes/testing before committing working modifications to the repo.
  * Have an automated job sync the shared location every so often.
    * Example: Have cron perform a git pull for /ansible/ every 30 mins.

\\
Model content tree under /ansible/ after [[http://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html#alternative-directory-layout|Ansible's best practices alternative structure]].

----

===== Inventory =====

Inventory setup is the most important configure task.

\\
In order for Ansible to send commands to systems, they must be listed in inventory.

\\
Suggested directory structure (after [[http://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html#alternative-directory-layout|Ansible's best practices alternative structure]])
  * Production Inventory: /ansible/inventories/production/hosts
  * Systest Inventory: /ansible/inventories/systest/hosts
  * Development Inventory: /ansible/inventories/development/hosts

==== Auto Generated Inventory ====

You will not want to introduce a manual inventory process.

Suggested workflow for auto generating your inventory files:

  * Cron Job to execute inventory generation script: /etc/cron.d/ansible-generate-inventory
    * Example: Executes every 30 minutes. (*/30 * * * *)

  * Script that generates inventory files: /ansible/scripts/inventory-file-gen.py
    * Source: The script should contact some sort of system via APIs that all newly deployed systems automatically register to. (Such as Spacewalk, Foreman/Katello, etc)

  * Target directory for auto generated inventory files: /root/repos/ansible/inventories/
    * Files are generated here and any changes committed to the repo (svn/git). 
      * Example: If there were committed changes, a repo sync job will pick them up and place them in /ansible/inventories/ at the top of every hour. (0 *)

  * Example User Accounts Involved
    * autorepo -> Repo user account with read/write access to an ansible repo for inventory file changes.
    * autoadmin -> API user account for contacting the inventory source.

----

====== Ansible Commands ======

Examples of Ansible commands.

**Note: All host-patterns check the inventory files for matches ONLY. If a system is not in the inventory file(s), Ansible can't send a command to it.**

General Ansible command syntax<code bash>ansible <host-pattern> [-m module-name] [-a arguments] [options]</code>
  * see 'man ansible' for more details

----

===== List Hosts =====

Listing hosts matched by the given pattern and do nothing else.

\\
List hosts in the webservers_nginx group from dev inventory<code bash>ansible webservers_nginx -i /ansible/inventories/development/hosts --list-hosts</code>

\\
List all hosts from dev inventory<code bash>ansible all -i /ansible/inventories/development/hosts --list-hosts</code>

\\
List all hosts in the "webservers_nginx" group (**from any inventory**)<code bash>ansible webservers_nginx --list-hosts</code>

\\
List all hosts matching "web*" pattern (**from any inventory**)<code bash>ansible "web*" --list-hosts</code>

----

===== Test Connection =====

The module 'ping' is **not an ICMP echo command**; it tests a remote login (ssh) to the system and verifies a working remote python environment.

\\
Test connection to webservers_nginx in dev inventory only<code bash>ansible webservers_nginx -i /ansible/inventories/development/hosts -m ping</code>

\\
Test connection to all systems in dev inventory<code bash>ansible all -i /ansible/inventories/development/hosts -m ping</code>

\\
Test connection to **all** webservers_nginx (**from any inventory**)<code bash>ansible webservers_nginx -m ping</code>

\\
Test connection to all systems in the "webservers_nginx" group (**from any inventory**)<code bash>ansible webservers_nginx -m ping</code>

\\
Test connection to systems matching a pattern (**from any inventory**)<code bash>ansible "web*" -m ping</code>

\\
Test connection to all systems (**from any inventory**)<code bash>ansible all -m ping</code>

----

===== Ad-Hoc Commands =====

Ad-hoc commands are for one off commands that are not saved in a playbook.

  * Ad-hoc Intro: http://docs.ansible.com/ansible/intro_adhoc.html
  * Module Index: http://docs.ansible.com/ansible/latest/modules_by_category.html

----

==== Modules: Command and Shell ====

If no module is specified, the "command" module is used.
  * The command module can execute basic commands, **but cannot do shell specific functions** such as piping and redirects
  * If you need that type of shell functionality, **specify the "shell" module**

\\
Check uptime of the group 'webservers_nginx' from dev only<code bash>ansible webservers_nginx -i /ansible/inventories/development/hosts -a 'uptime'</code>

\\
Check uptime of all systems in dev<code bash>ansible all -i /ansible/inventories/development/hosts -a 'uptime'</code>

\\
Check uptime of the group 'webservers_nginx' (**from any inventory**)<code bash>ansible webservers_nginx -a 'uptime'</code>

\\
Check the last 10 lines in /var/log/messages (using sudo)<code bash>ansible "web*" -a 'tail /var/log/messages' -b</code>
  * -b => or 'become', uses the default privilege escalation, which is sudo on Linux systems.

Equivalent command as the above<code bash>ansible "web*" -a 'sudo tail /var/log/messages'</code>

\\
Piping example; the shell module must be specified<code bash>ansible "web*" -m shell -a 'cat /var/log/messages | grep -i error' -b</code>

----

==== Modules: Copy and File ====

Transferring files over scp using Ansible to multiple servers at once.

\\
Copy a local file (src=) to all systems in the 'webservers_nginx' group (dest=)<code bash>ansible webservers_nginx -m copy -a "src=/etc/yum.conf dest=/tmp/yum.conf"</code>

\\
Set a file's ownership and permissions<code bash>ansible webservers_nginx -m file -a "dest=/tmp/yum.conf mode=750 owner=root group=root"</code>

\\
Remove a file<code bash>ansible webservers_nginx -m file -a "dest=/tmp/yum.conf state=absent"</code>
  * This same command will recursively delete if a directory is the target

----

==== Modules: Packages ====

Managing packages with Ansible.

\\
Ensure a package is installed, do not update the package if it is installed<code bash>ansible my_group -m yum -a "name=dstat state=present"</code>

\\
Ensure package is the latest version (update if not)<code bash>ansible my_group -m yum -a "name=dstat state=latest"</code>

\\
Ensure package is not installed (remove if it is)<code bash>ansible my_group -m yum -a "name=dstat state=absent"</code>

----

==== Modules: Services ====

Managing system services with Ansible.

Compatible with SysV and Systemd.
  * **Note**: For systemd specific commands such as "mask", you will need to use the [[http://docs.ansible.com/ansible/latest/systemd_module.html|systemd Ansible module]] instead.

\\
Ensure httpd is started (start if not)<code bash>ansible my_group -m service -a "name=httpd state=started"</code>

\\
Restart a service<code bash>ansible my_group -m service -a "name=httpd state=restarted"</code>

\\
Ensure a service is stopped<code bash>ansible my_group -m service -a "name=httpd state=stopped"</code>

----

====== Ansible Playbooks ======

"Playbooks are Ansible’s configuration, deployment, and orchestration language. They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process."

More Details: http://docs.ansible.com/ansible/playbooks.html

----

===== Playbook Directory Structure =====

Playbooks should be repo controlled.

Following the examples on this page:
  * /ansible/playbooks

\\
**Playbooks map ansible groups to roles**
  * Example playbook<code yaml># File: webservers_nginx.yml
# Description: Nginx Webservers
# Last Updated: 2018-04-08
# Recent Changes:-Initial release

# hosts: group_name or 'all'
- hosts: webservers_nginx

  # roles: located in ../roles/
  roles:
    # role: role to assign to hosts, tags: tag(s) to give entire role
    - { role: webservers-nginx, tags: webservers-nginx }

  # Gather host facts for this playbook
  gather_facts: yes</code>
  * All systems in the ansible group "webservers_nginx" are given the roles:
    * webservers-nginx

  * When a playbook is executed, all tasks in the assigned roles are run (unless only specific tasks/actions are selected using tags and/or limits).

\\
**Gather a subset of facts**

If you do need to gather facts, consider gathering a subset of facts instead of everything in order to keep the fact collection fast.
  * Example: Collect only the ansible_distribution facts<code yaml># Gather host facts for this playbook
  gather_facts: yes
  # Gather only ansible_distribution info (OS attributes)
  gather_subset:
    - '!all'
    - '!min'
    - 'distribution'</code>
    * Facts returned by the above subset<code bash>"ansible_distribution": "CentOS",
        "ansible_distribution_file_parsed": true,
        "ansible_distribution_file_path": "/etc/redhat-release",
        "ansible_distribution_file_variety": "RedHat",
        "ansible_distribution_major_version": "7",
        "ansible_distribution_release": "Core",
        "ansible_distribution_version": "7.5.1804",
        "ansible_os_family": "RedHat",</code>
  * You can test your subset commands like this
    * ad-hoc<code bash>ansible -m setup -a 'gather_subset=!all,!min,distribution' localhost</code>

**Available Fact Subsets**:
  * all
  * min
  * hardware
  * network
  * virtual
  * ohai
  * facter

\\
**See the Roles section** for what happens next.

----

===== Roles Directory Structure =====

Roles contain all of the tasks that will be run when a playbook is executed against it.

\\
Roles should be repo controlled. Top level directory example is:
  * /ansible/roles

An example role called "webservers-nginx" is located:
  * /ansible/roles/webservers-nginx

The contents of a role directory are:
  * files
    * Files to be used with the 'copy' or 'script' resource. Files located in this directory can be referred to by just the filename without directory path in task yml files.

  * handlers
    * Actions that are only executed when certain tasks report changes. Requires 'main.yml' to execute.

  * meta
    * Role dependencies. Requires 'main.yml' to execute.

  * **tasks**  -> The main section to work with
    * Tasks/actions to take when the role is executed via a playbook. Requires 'main.yml' to execute.

  * templates
    * Files to be used with the 'template' resource. Templates end in '.j2' (jinja2)

  * vars
    * Variables associated with the role. Requires 'main.yml' to execute.

----

===== Playbook/Role Creation =====

How to create a new playbook and role.
  * Playbook: Maps Ansible group(s) to role(s)
  * Role: Defines tasks to complete against the hosts

External References
  * Intro to Playbooks: http://docs.ansible.com/ansible/playbooks_intro.html
  * Intro to modules: http://docs.ansible.com/ansible/modules_intro.html
  * All modules index: http://docs.ansible.com/ansible/list_of_all_modules.html

  - Navigate to your local copy of the version controlled ansible repo. Example:<code bash>cd ${HOME}/repos/ansible/</code>
  - Update your local copy of the version controlled ansible repo to the latest version<code bash>#git
git pull

#svn
svn update</code>
  - **New Role**
    - Navigate to the roles directory, then copy your role template directory to a new name<code bash>cd roles/
cp -R template-role/ my-new-role</code>
    - Modify the role's files as needed to create tasks, files, handlers, etc.
      - Download zip archive of an {{ :linux_wiki:role-template.zip |example role template}}.
  - **New Playbook**
    - Navigate to the playbooks directory<code bash>cd ${HOME}/repos/ansible/playbooks/</code>
    - Copy your playbook template to a new playbook yaml file.<code bash>cp TEMPLATE_PLAYBOOK.yml my_new_playbook.yml</code>
      - Playbook Template<code yaml TEMPLATE_PLAYBOOK.yml># File: TEMPLATE_PLAYBOOK.yml
# Description: PLAYBOOK DESCRIPTION HERE
# Last Updated: 2018-03-15
# Recent Changes:-Initial release

# hosts: group_name or 'all'
- hosts:
    - group_name_here

  # roles: located in ../roles/
  roles:
    # role: role to assign to hosts, tags: tag(s) to give entire role
    - { role: role-name, tags: tag-name }

  # Do not gather host facts for this playbook (comment out/remove if you need facts)
  gather_facts: no
</code>
    - Edit the new playbook (vim ansible/playbooks/my_new_playbook.yml)<code yaml>
- hosts: my_ansible_group
  roles:
    - { role: my-new-role, tags: my-new-role }</code>
      - In the above example, the playbook "my_new_playbook" states that the group "my_ansible_group" has the role of "my-new-role", and all tasks in the role "my-new-role" has the tag "my-new-role"
        - The tag can be anything, but keeping it the same as the role name is useful if you want to limit the execution of a playbook to a specific role using the "tags" command line argument to ansible-playbook
        - Tags are inherited at all tasks below it.
      - When the playbook is executed, the tasks defined in the role will be executed against the group
  - **Test Playbook**
    - See the next section for details on testing the playbook before committing changes to a repo.

----

==== Playbook Testing ====

Test your playbook before committing it to a repo.

  * Add these functions to your shell's config<code bash>#bash = ~/.bashrc
#zsh = ~/.zshrc

# Enable Ansible test environment
ansible_local_enable(){
  export ANSIBLE_INVENTORY="${HOME}/repos/ansible/inventories"
  export ANSIBLE_ROLES_PATH="${HOME}/repos/ansible/roles"
  echo -e "Ansible environmental variables set to:"
  env | grep ANSIBLE
}
# Disable Ansible test environment
ansible_local_disable(){
  unset ANSIBLE_INVENTORY
  unset ANSIBLE_ROLES_PATH
  echo -e "Ansible environmental variables have been unset. There should be no variable results after this line."
  env | grep ANSIBLE
}</code>
  * Source the file<code bash>#bash
source ~/.bashrc

#zsh
source ~/.zshrc</code>
  * Enable local variables<code bash>ansible_local_enable</code>
  * Test playbook locally
    * Syntax check<code bash>ansible-playbook --syntax-check ${HOME}/repos/ansible/playbooks/my_new_playbook.yml</code>
    * List tasks<code bash>ansible-playbook -b -i ${HOME}/repos/ansible/inventories/development/dev ${HOME}/repos/ansible/playbooks/my_new_playbook.yml --list-tasks</code>
    * Run against a test system<code bash>ansible-playbook -b -i ${HOME}/repos/ansible/inventories/development/dev ${HOME}/repos/ansible/playbooks/my_new_playbook.yml --limit mytestsystem</code>
  * Tests successful, disable local variables<code bash>ansible_local_disable</code>
  * Commit playbook/role to the repo

----

===== Playbook Commands =====

Different methods to run playbooks.

\\
**WARNING**: If you do **NOT** specify an inventory file with "-i PATH", the playbook will run against **ALL HOSTS** in the group, which is probably not what you want.

\\
**NOTE**: If you need to use group_vars per inventory type (dev/test/prod), the full path to the inventory file needs to be used. (Example: /ansible/inventories/development/hosts )

----

==== Playbook Commands: Syntax Check ====

After creating a playbook, it is useful to check the syntax before running it to catch obvious errors.

Run a syntax check (will NOT execute the playbook)<code bash>ansible-playbook --syntax-check /ansible/playbooks/my_playbook.yml</code>

----

==== Playbook Commands: Aliases ====

Playbook commands can get rather long, some useful aliases to shorten them.

Put in your ~/.bashrc or ~/.zshrc file
<code bash># Ansible aliases
alias apd='ansible-playbook -b -i /ansible/inventories/development/hosts'
alias apt='ansible-playbook -b -i /ansible/inventories/systest/hosts'
alias app='ansible-playbook -b -i /ansible/inventories/production/hosts'
</code>

\\
Additionally, create a symlink to playbooks
<code bash>
ln -s /ansible/playbooks /playbooks
</code>

\\
Now, your playbook commands can look like this
<code bash>
# Dev inventory
apd /playbooks/myplaybook.yml

# Test inventory
apt /playbooks/myplaybook.yml

# Prod inventory
app /playbooks/myplaybook.yml
</code>
  * limits, tags, etc can also be appended as normal.

----

==== Playbook Commands: List ====

Preparation/sanity check commands to do before running a playbook.

\\
**List** what hosts the playbook will run against (**from dev inventory**)<code bash>ansible-playbook -i /ansible/inventories/development/hosts /ansible/playbooks/my_playbook.yml --list-hosts</code>
  * -i or --inventory -> Path to the inventory (alternative is a comma separated list of hosts or single hostname with a trailing comma)

\\
**List** what tasks the playbook will execute (**from dev inventory**)<code bash>ansible-playbook -i /ansible/inventories/development/hosts /ansible/playbooks/my_playbook.yml --list-tasks</code>

----

==== Playbook Commands: Run ====

Commands to actually run a playbook. You SHOULD do the list commands first to make sure what you are about to run is expected.
  * The list commands (--list-hosts and --list-tasks) can be appended to any of the following commands to check them first before running.

\\
**Run playbook (dev env; all in group)** against all system groups defined in playbook **from dev inventory** using sudo for privilege escalation<code bash>ansible-playbook -b -i /ansible/inventories/development/hosts /ansible/playbooks/my_playbook.yml</code>
  * -b or --become -> Use privilege escalation (default of sudo)

\\
**Run playbook (dev env; all in group; only configure)** against all groups defined in playbook **from dev inventory** using sudo for privilege escalation, only execute actions with the matched tags "configure"<code bash>ansible-playbook -b -i /ansible/inventories/development/hosts /ansible/playbooks/my_playbook.yml --tags configure</code>
  * --tags configure -> Only execute tasks in the playbook that have been tagged "configure"
    * roles, import_tasks, or individual tasks can be tagged

\\
**Run playbook (dev env; range of systems)** against all groups defined in playbook **from dev inventory** using sudo for privilege escalation, further limit to hosts web01-05"<code bash>ansible-playbook -b -i /ansible/inventories/development/hosts /ansible/playbooks/my_playbook.yml --limit "$(echo web{01..05})"</code>
  * --limit "$(echo web{01..05})" -> Filter results of host match to only include these systems

\\
**Run playbook (dev env; one system)** against all groups defined in playbook **from dev inventory**, limit to a single hostname (MYHOSTNAME)<code bash>ansible-playbook -i /ansible/inventories/development/hosts /ansible/playbooks/my_playbook.yml --limit MYHOSTNAME</code>

----