Ansible is one of the most popular automation platforms. You can connect to dozens of servers and execute hundreds of tasks with just a couple config files.

Table of Contents

Documentation

This is just a basic tutorial. You can find more info about how to use Ansible in the official documentation.

Also check Ansible cheat sheet guide.

Installation

You can install Ansible on your host in several ways:

  • With pip (recommended): 
    pip install --user ansible

    python3 -m pip install --user ansible
  • With your operating system package manager: 
    # Arch Linux
pacman -S ansible-core

You don’t need to install anything special on your “nodes” (the servers you want to manage), just Python.

After installation, create a directory to save Ansible config files and, inside that directory, run the following command to generate the main configuration file (with all the entries disabled):

ansible-config init --disabled > ansible.cfg

You can view the file and uncomment the options you want to enable. Check the Documentation.

Inventory

You need to create an “inventory” file to list your nodes. Inside the created directory, create and edit a file named hosts. The basic syntax of an inventory file is this:

[group1]
192.168.122.5

[group2]
example.rs1.es
  • Create groups of nodes adding the group name between brackets and the IP or hostname of the nodes below.
  • You can add more parameters for each node (separated by spaces). Check Documentation: 
    192.168.122.5 ansible_user=ricardo

    example.rs1.es ansible_user=admin ansible_ssh_private_key_file=/home/user/Documents/keys/key.pem
  • You can use this format or YAML, check the documentation for more info.
  • Ansible does not support typing passwords for SSH keys, add the key to ssh-agent instead.
  • You can also add the private key at runtime, add --private-key=<key path> to ansible or ansible-playbook commands.

Check that you can connect to your nodes:

ansible -i hosts <group name> -m ping
# e.g.: ansible -i hosts group1 -m ping
  • -i <hosts file> allows to specify the path of your hosts file.
  • You can replace the group name with all to check all nodes.
  • If the remote user requires a password, add --ask-pass. If a private key is required, add ``–private-key=`.

Playbook

Playbooks are the files where you add the tasks you want to execute on your nodes. Playbooks are formated in YAML an easy-to-use plain text format. This is an example of a playbook file (e.g.: playbook.yml):

---
- name: Playbook with group1
  hosts: group1

  tasks:
  - name: id command
    tags: inactive
    command: id
    register: out2

  - name: Update the system
    tags: active
    become: yes
    apt:
      name: "*"
      state: latest

  - name: APT autoremove
    tags: active
    become: yes
    command: apt autoremove -y

  - debug: var=out2.stdout_lines
    tags: active
  • Identation is very important in YAML. Use two spaces to identate.
  • It’s a common practice to add --- at the beginning.
  • First, add a name for the playbook. Then, specify the node group in which you want to execute the tasks (you can add several groups separated by commas).
  • Inside tasks, add each task in the order you want to execute them: specify a name and use one of the available modules, such as apt (check the Documentation). The simplest task you can define is: ```
  • name: Test task command: some_command ```
    • This will run some_command on the nodes.
  • Add optional tags. This is useful when you want to run only some tasks in the playbook.
  • become: yes indicates Ansible to run the task as root, using “sudo”. If “sudo” requires a password, add this parameter to ansible-playbook (check folowing section): --ask-become-pass.
  • To view the output (stdout) of the commands, you need to add a register: <name> to the task and then create a debug task with the value: var=<register name>.stdout_lines.

Execute the tasks

To run a playbook, execute:

ansible-playbook -i hosts playbook.yml
  • To verify the syntax of the playbook without executing it, add -C or --check.
  • To run the tasks with the specified tag, add -t <tag> or --tags <tag>.
  • To specify a remote user name, add -U <remote user>.
  • If you need to further limit selected hosts, use -l <subset pattern>.
  • If the remote user requires a password, add --ask-pass. If a private key is required, add ``–private-key=`.
  • If a task requires “sudo”, and “sudo” requires a password, add --ask-become-pass.
  • To print more debug messages, add -v or --verbose. Add multiple v to increase the “verbosity”.

Variables

You can create a file to store variables, so you don’t need to edit the playbook. Create a folder called ‘vars’. Inside that folder, create and edit a YAML file:

mkdir vars
nano vars/default.yml

First, add --- at the beginning of the file. In the next lines, add your variables:

---
myvar1: somevalue
myvar2: 800
  • Add comments with #.

After that, in your playbook add (below hosts line) this:

vars_files:
  - vars/default.yml

This is an example of the beginning of a playbook:

- name: My Playbook
  hosts: group1
  vars_files:
    - vars/default.yml

To refer to a variable in the playbook, use this syntax:

{{ variable_name }}

For example:

  user:
    name: {{ username }}
    state: present

More

  • Execute commands on nodes, without a playbook: 
    ansible -i <hosts file> <group name or all> -a "<command>"
# e.g.: ansible -i hosts group1 -a "uname -a"

Examples

Check https://github.com/do-community/ansible-playbooks or https://github.com/ansible/ansible-examples for some Ansible playbook examples.

If you have any suggestion, feel free to contact me via social media or email.