SPICE | Ansible Getting Started Guide - UMCST/SPICE-user-info GitHub Wiki


Ansible is an IT automation tool that leverages the readability of YAML to make writing automation tasks straightforward. The SPICE project uses Ansible to automate repetitive tasks across the various hosts, most notably with the SPICE-autopatching playbook.

Beginning Resources:

  1. Playbooks, lists of tasks to run on remote machines, are written in YAML language. Begin with reading YAML Syntax - Ansible Documentation. For comprehensive information on playbooks, view Intro to playbooks - Ansible Documentation.
  2. Look at existing playbooks: view the SPICE-autopatching playbook on the SPICE github, including the surface-level main.yml and through the roles/ directory.

Directory structure

A playbook can just be a .yml file that details all of the hosts, variables, and tasks inside, but a cleaner and more common approach is with a directory structure, with separate locations for variables files and roles, which are separate groups of tasks that can be played on different hosts.

Ansible Directory Structure

Figure 1. Common Ansible Directory Structure

Creating a playbook

Begin with a main.yml file. This is the entry point to the playbook. The main.yml needs some things to be defined before tasks can be ran:

  1. hosts: Give the playbook a list of hosts to run with or give it a group of hosts outlined in an inventory.ini or inventory.yml, depending on which format you use. View How to build your inventory - Ansible Documentation to see formatting for this file.
  2. remote_user: When running tasks on remote machines, a user for Ansible to use will need to be specified. Hosts across the SPICE platforms have the user deployer reserved for Ansible activities, and passwords and ssh keys for using this user may be found on the current Ansible control host, tarragon. Ansible by default assumes an ssh key will be used to gain access to a remote user, so set this up from the user running the playbook to the deployer user on a host before running the playbook there.
  3. vars_files: Here, use a YAML list to list out the variables files being used, and their locations. Ex. ./vars/variables_file1.yml.
  4. roles: Use a YAML list to list out the roles to be run on the aforementioned hosts. Separately, if roles are not being used, use tasks: to start listing out the tasks to be run.

Common tasks

  • shell: or command: — used to execute a remote command on the host. Capture the command’s output using the register directive, detailed below. Use command: for simple, single commands and use shell: to use features like piping or redirection. Before using these modules, see if there are other modules Ansible provides to accomplish your specific task.
  • debug: — used to print debug info or otherwise information the user should see to Ansible’s output. Supply var: to print the contents of a variable, and supply msg: and a string to print a message.
    • To include a variable in a string, surround the name of the variable with two curly brackets in the middle of the string.
    • Ex. “Value of the variable: {{ test_variable }}”
  • set_fact: — Used to create / set a variable mid-play, to be used in later tasks. Supply the name of the variable and a value.
  • service: — Used to manage services, similar to how one would manage services with the linux systemctl command. Supply a name: and a state:.

Task directives

Control the occurrences and results of tasks with task directives, listed under Ansible’s Directives Glossary. Common task directives include:

  • become: — used to enable privilege escalation, for when a command would regularly be run with sudo privileges. Set to yes to achieve this.
  • register: — used when the output of an Ansible task needs to be captured as a variable. Supply a name for the register, and optionally, try examining the register with debug: to find where the information you are interested in is.
  • when: — controls when a task happens when supplied with a condition. The task executes when the condition evaluates to true, and is skipped when it isn’t. Variables in a conditional do not have to be enclosed in curly braces ( { } ) except when in a string.
  • until: — repeats a task until the condition is true.
  • with_items: used to repeat a task with a list of items. Supply a list of items to be acted on, and in the task reference the item to be acted on with {{ item }}.

Use with Docker

Ansible has many modules to interact with docker images and containers. These can be found listed at Community.Docker - Ansible Documentation. Some useful modules to use for managing docker include docker_image, docker_container, and docker_image_info.

⚠️ **GitHub.com Fallback** ⚠️