Ansible Getting Started Guide

ansible-logo

Overview

Automation is one of the most critical areas of improvement in most organizations. Today, most companies are in the process or re-inventing themselves in one way or another to add software development capabilities and as such, take full advantage of the digitalization of everything. Software development release cycles are changing in order to release faster. Continuous delivery, where every change is potentially it’s own release is becoming the new standard. Infrastructure is following suit, after all, continuous delivery is not about just software changes but all changes and infrastructure plays a key roll. For any of this to work of course, 100% automation is required. To achieve that goal, an automation language that is easy and applicable to development and operations is needed. Ansible is that language and if you are not on-board yet, now is your chance not to miss the train because it is leaving the station. Ansible is easy, Ansible is powerful and Ansible is flexible. This guide will show that and get you up and running with Ansible before your coffee gets cold.

In this article we will dive into Ansible and learn the basics to get up and running faster, creating playbooks the right way. This article will focus on those who are new to Ansible but it may also provide value to those that are already writing their own playbooks.

Pre-requisites

  • Several VMs or hosts, I recommend 5. One to be Ansible management host and other four managed nodes.
  • RHEL or CentOS 7.3

Ansible Basics

  • Ansible Engine – The Ansible runtime and CLI which executes playbooks. The engine runs on a management node, from where you want to drive automation.
  • Playbook – A series or group of tasks that automate a process. Playbooks are written in YAML.
  • Inventory – Determines what hosts you want to run playbook against. Inventories can be dynamic or static.
  • Configuration – The configuration for Ansible is stored in ansible.cfg by default under /etc/ansible/ansible.cfg. It determines default settings for Ansible, where the inventory is located and much more. You can have many ansible.cfg files.
  • Role – Ansible way to build re-usable automation components. A role groups together playbooks, templates, variables and everything needed to automate a given process in a pre-packaged unit of work.
  • Ansible Galaxy – Ansible roles provided by the Ansible community. Not only can you get access to 1000s of roles but you can share as well.
  • Ansible Modules – Used in Ansible to perform tasks, install software, enable services, etc. Modules are provided with Ansible (core modules) and also provided by the community. They are mostly written in python which is used by Ansible itself.
  • Ansible Tower – API and UI for Ansible to handle scheduling, reporting, visualization and support teamwork for organizations running many playbooks across many teams.

All exercises and examples should be carried out on the Ansible management node.

Install Ansible

In order to install Ansible you need minimum python 2.6 or greater.

Check Python version.

# yum list installed python

Create Ansible user.

# useradd ansible -h /home/ansible
# passwd ansible

Install Ansible.

$ sudo yum install -y ansible

Create Inventory file.

The inventory file stores managed nodes and is used to execute playbooks or commands against a group of hosts. You can have nested groups and add variables but let’s just start with a simple inventory.

$ vi inventory

[servers]
server1.lab.com
server2.lab.com
server3.lab.com
server4.lab.com

ADHOC Commands

Ansible can be used to run adhoc commands against an inventory of servers. We will use Ansible adhoc commands to create a user on our four managed nodes for Ansible that can sudo.

Create Ansible user on managed nodes.

$ ansible -m user -a 'name=ansible shell=/bin/bash generate_ssh_key=yes \
state=present' -u root --ask-pass -i ./inventory servers

The above command uses the Ansible user module to create a new user on the four hosts listed in our inventory group servers. It will use root as ssh user and prompt for root password.

Create a suders file to allow ansible sudo permissions.

$ ansible -m lineinfile -a "dest=/etc/sudoers.d/ansible \
line='ansible ALL=(ALL) NOPASSWD: ALL' create=yes state=present" \
-u root --ask-pass -i ./inventory servers

The above command will use the lineinfile module to create the sudoers file for Ansible and add the line to allow Ansible user sudo permissions.

You may be interested in running other modules. Thankfully Ansible modules are wonderfully documented.

Generate list of all Ansible modules.

$ ansible-doc -l

Read documentation for user module.

$ ansible-doc user

Now we come to best practice #1. You might discover a module called command or shell. These modules can be used to execute any remote commands. While convenient, always try to find a purpose based module instead of using command or shell. Using specific modules is much cleaner, more readable and should always be the first choice.

Playbook Basics

Now that we understand how inventories work and how to run basic adhoc commands it is time to explore playbooks. In order to run a playbook you need Ansible, an inventory, a remote user and of course the playbook itself. A playbook simply put is just one or more tasks. Above we saw how to execute individual adhoc commands or tasks using our inventory servers. Now let us bring those tasks together in a playbook.

Create playbook.

$ vi add_user.yml
---
- name: Add a privileged user for Ansible
  hosts: servers

  tasks:
    - name: Add a user
      user:
        name: ansible
        shell: /bin/bash
        generate_ssh_keys: yes
        state: present
    - name: Configure sudo permission
      lineinfile:
        dest: /etc/sudoers.d/ansible
        line: 'ansible ALL=(ALL) NOPASSWD: ALL'
        create: yes
        state: present

 

Now we come to best practice #2. The name parameter is optional, don’t be lazy, always name the playbook and all tasks. This is important for reading what was done and also to let other’s know what your playbook is supposed to be doing.

You can see how the inventory group is used and also how the tasks are invoked. Again a task just invokes and Ansible module with a set of parameters. Everything is documented in ansible-doc. With just what we have covered here, probably took you 10-15 minutes you can start automating everything with Ansible. Hopefully a light as gone on.

Run playbook.

Assuming you ran the adhoc commands a ansible user already exists that can sudo. If not you need to run the adhoc commands.

$ ansible-playbook add_user.yml -u ansible -b -i ./inventory

We can use the newly created Ansible user and the -b option (become root) to elevate permissions.

Variables

Variables allow for dynamic input. In Ansible variables can be defined in many ways such as: playbook itself, inventory file via host or group vars, cli via extra_vars or in a separate vars file that can be included in playbook. Let’s take a look at these options in more detail. Instead of hard-coding the username we created above let’s explore doing so using the different variable options.

Vars via inventory file.

Variables can be defined for a host or group in the inventory file itself. Here we will define a variable username for the group servers.

Update inventory file and add vars for group servers.

$ vi inventory

[servers]
server1.lab.com
server2.lab.com
server3.lab.com
server4.lab.com

[servers:vars]
username=ansible

Update playbook to use variables.

$ vi add_user.yml
---
- name: Add a privileged user for Ansible
  hosts: servers

  tasks:
    - name: Add a user
      user:
        name: "{{ username }}"
        shell: /bin/bash
        generate_ssh_keys: yes
        state: present
    - name: Configure sudo permission
      lineinfile:
        dest: /etc/sudoers.d/{{ username }}
        line: 'ansible ALL=(ALL) NOPASSWD: ALL'
        create: yes
        state: present

Notice that the variable {{ username }} needs quotes only when it starts a line.

Run playbook.

$ ansible-playbook add_user.yml -u ansible -b -i ./inventory

Variables in playbook

Variables can be defined directly in the playbook.

$ vi add_user.yml
---
- name: Add a privileged user for Ansible
  hosts: servers
  vars:
    username: ansible

  tasks:
    - name: Add a user
      user:
        name: "{{ username }}"
        shell: /bin/bash
        generate_ssh_keys: yes
        state: present
    - name: Configure sudo permission
      lineinfile:
        dest: /etc/sudoers.d/{{ username }}
        line: 'ansible ALL=(ALL) NOPASSWD: ALL'
        create: yes
        state: present

Run playbook.

$ ansible-playbook add_user.yml -u ansible -b -i ./inventory

Variables imported from vars file.

Similar to above example, variables can be defined in a separate file and then imported into playbook.

Create vars file.

$ vi my_vars.yml
---
username: ansible

Update playbook.

$ vi add_user.yml
---
- name: Add a privileged user for Ansible
  hosts: servers
  vars_files:
    - ./my_vars.yml

  tasks:
    - name: Add a user
      user:
        name: "{{ username }}"
        shell: /bin/bash
        generate_ssh_keys: yes
        state: present
    - name: Configure sudo permission
      lineinfile:
        dest: /etc/sudoers.d/{{ username }}
        line: 'ansible ALL=(ALL) NOPASSWD: ALL'
        create: yes
        state: present

The best practice #3 is to use inventory file to define key/value type variables that should be parameterized. Variables that are dynamically generated or utilize nested data structures should use vars_files and be included. Avoid using vars in playbook directly if possible.

Run playbook.

$ ansible-playbook add_user.yml -u ansible -b -i ./inventory

Ansible Facts

Each time Ansible is run unless disabled the setup module is also run. The setup module gathers Ansible facts. These are variables that give us valuable information about the managed host and they can be acted upon within playbooks.  Anything from a hosts network, hardware and OS information are gathered. It is also possible to define custom facts that would be gathered.

View ansible facts for a host.

$ ansible -m setup -u ansible -b -i ./inventory servera.lab.com

Use ansible facts in playbook.

Here we will print the memory and number of cpu cores in our playbook by adding a new task.

$ vi add_user.yml
---
    - name: Print Memory and CPU Cores
      debug:
        msg: "Host {{ ansible_hostname }} has {{ ansible_memtotal_mb }} MB Memory and {{ ansible_processor_cores }} CPU Cores."
---

Run playbook.

$ ansible-playbook add_user.yml -u ansible -b -i ./inventory

Controlling Playbooks

We have seen how to use modules to drive tasks and even parameterize them with variables. Next we will understand how to better control tasks within those playbooks.

When Conditional

This acts as an if statement in common programming languages. In Ansible we use when statement to run a task based on a condition being met.

Execute add user only when username is defined.

$ vi add_user.yaml
---
    - name: Add a user
      user:
        name: "{{ username }}"
        shell: /bin/bash
        generate_ssh_keys: yes
        state: present
      when: username is defined
---

Run playbook.

$ ansible-playbook add_user.yml -u ansible -b -i ./inventory

Loops

In Ansible loops are very useful when the same task or module need to execute against a list. In our playbook let’s update it to take action on many users and thus show how to use a loop.

Update vars file.

$ vi my_vars.yml
---
users:
  - ansible
  - bob
  - joe
  - keith

Update playbook.

$ vi add_user.yml
---
- name: Add a privileged user for Ansible
  hosts: servers
  vars_files:
    - ./my_vars.yml

  tasks:
    - name: Print Memory and CPU Cores 
      debug: 
        msg: "Host {{ ansible_hostname }} has {{ ansible_memtotal_mb }} MB Memory and {{ ansible_processor_cores }} CPU Cores."
    - name: Add a user
      user:
        name: "{{ item }}"
        shell: /bin/bash
        generate_ssh_keys: yes
        state: present
      with_items: "{{ users }}"
      when: item is defined
    - name: Configure sudo permission
      lineinfile:
        dest: /etc/sudoers.d/{{ item }}
        line: 'ansible ALL=(ALL) NOPASSWD: ALL'
        create: yes
        state: present
      with_items: "{{ users }}"
      when: item is defined

Run playbook.

$ ansible-playbook add_user.yml -u ansible -b -i ./inventory

Handlers

In order to couple tasks or have a task executed from another task, a handler is required. Here we will look at converting the “configure sudo permission” task into a handler that can be triggered by the “add a user” task.

Update playbook.

$ vi add_user.yml
---
- name: Add a privileged user for Ansible
  hosts: servers
  vars_files:
    - ./my_vars.yml

  tasks:
    - name: Print Memory and CPU Cores 
      debug: 
        msg: "Host {{ ansible_hostname }} has {{ ansible_memtotal_mb }} MB Memory and {{ ansible_processor_cores }} CPU Cores."
    - name: Add a user
      user:
        name: "{{ item }}"
        shell: /bin/bash
        generate_ssh_keys: yes
        state: present
      with_items: "{{ users }}"
      when: item is defined
      notify:
        - 'Configure sudo permission'

  handlers:
    - name: Configure sudo permission
      lineinfile:
        dest: /etc/sudoers.d/{{ item }}
        line: 'ansible ALL=(ALL) NOPASSWD: ALL'
        create: yes
        state: present
      with_items: "{{ users }}"
      when: item is defined

Now sudo permissions will only be set when a new user is actually added. It is very important to understand behavior with handlers, a notifer will only run when the task made a change.

Run playbook.

$ ansible-playbook add_user.yml -u ansible -b -i ./inventory

Tags

It may be desired to only run certain tasks and to control which tasks get run from cli. This is done in Ansible via tags. Lets set a tag which will only run the task that prints memory and cpu info.

Update playbook.

$ vi add_user.yml
---
- name: Add a privileged user for Ansible
  hosts: servers
  vars_files:
    - ./my_vars.yml

  tasks:
    - name: Print Memory and CPU Cores 
      debug: 
        msg: "Host {{ ansible_hostname }} has {{ ansible_memtotal_mb }} MB Memory and {{ ansible_processor_cores }} CPU Cores."
      tags:
        - info
    - name: Add a user
      user:
        name: "{{ item }}"
        shell: /bin/bash
        generate_ssh_keys: yes
        state: present
      with_items: "{{ users }}"
      when: item is defined
      notify:
        - 'Configure sudo permission'

  handlers:
    - name: Configure sudo permission
      lineinfile:
        dest: /etc/sudoers.d/{{ item }}
        line: 'ansible ALL=(ALL) NOPASSWD: ALL'
        create: yes
        state: present
      with_items: "{{ users }}"
      when: item is defined

Run playbook using tag ‘info’.

$ ansible-playbook add_user.yml -u ansible -b -i ./inventory --tags 'info'

Blocks

In order to handle errors in Ansible blocks are often used. The block statement defines the main task to run. The rescue statement defines a task that should run if an error is encountered inside the block. Here we will setup error handling for our add user task.

Update playbook.

$ vi add_user.yml
---
- name: Add a privileged user for Ansible
  hosts: servers
  vars_files:
    - ./my_vars.yml

  tasks:
    - name: Print Memory and CPU Cores 
      debug: 
        msg: "Host {{ ansible_hostname }} has {{ ansible_memtotal_mb }} MB Memory and {{ ansible_processor_cores }} CPU Cores."
      tags:
        - info
    - block:
        - name: Add a user
          user:
            name: "{{ item }}"
            shell: /bin/bash
            generate_ssh_keys: yes
            state: present
          with_items: "{{ users }}"
          when: item is defined
          notify:
            - 'Configure sudo permission'
      rescue:
        - name: revert user add
          user: 
            name: "{{ item }}" 
            state: absent 
          with_items: "{{ users }}" 
          when: item is defined         
  handlers:
    - name: Configure sudo permission
      lineinfile:
        dest: /etc/sudoers.d/{{ item }}
        line: 'ansible ALL=(ALL) NOPASSWD: ALL'
        create: yes
        state: present
      with_items: "{{ users }}"
      when: item is defined

The playbook will now attempt to remove users if an error occurs with the add user task. You can simulate this by adding a new user to my_vars.yml file and running without the -b (become root) option.

Run playbook.

$ ansible-playbook add_user.yml -u ansible -i ./inventory

Templates

In Ansible templates are used mostly to parameterize configuration files. Ansible uses the jinja2 templating system. A template module is provided that defines the template and where it should be placed. Variables are automatically substituted for their values when the template is copied to its destination. We will add a new task to the playbook which sets the motd using hostname as a dynamic variable from a motd jinja2 template.

Create a jinja2 template for motd.

$ vi motd.j2
Ansible Rocks!!! This is host {{ ansible_hostname }}.

Update playbook.

$ vi add_user.yml
---
- name: Add a privileged user for Ansible
  hosts: servers
  vars_files:
    - ./my_vars.yml

  tasks:
    - name: Configure MOTD using template
      template:
        src: ./motd.j2
        dest: /etc/motd
        owner: root
        group: root
        mode: 0644
    - name: Print Memory and CPU Cores 
      debug: 
        msg: "Host {{ ansible_hostname }} has {{ ansible_memtotal_mb }} MB Memory and {{ ansible_processor_cores }} CPU Cores."
      tags:
        - info
    - block:
        - name: Add a user
          user:
            name: "{{ item }}"
            shell: /bin/bash
            generate_ssh_keys: yes
            state: present
          with_items: "{{ users }}"
          when: item is defined
          notify:
            - 'Configure sudo permission'
      rescue:
        - name: revert user add
          user: 
            name: "{{ item }}" 
            state: absent 
          with_items: "{{ users }}" 
          when: item is defined         
  handlers:
    - name: Configure sudo permission
      lineinfile:
        dest: /etc/sudoers.d/{{ item }}
        line: 'ansible ALL=(ALL) NOPASSWD: ALL'
        create: yes
        state: present
      with_items: "{{ users }}"
      when: item is defined

Run playbook.

$ ansible-playbook add_user.yml -u ansible -b -i ./inventory

The playbook will now update motd based on our jinja2 template. The hostname will be dynamically applied based on the variable.

Check MOTD.

$ ssh -l ansible server1
Ansible Rocks!!! This is host server1.

Roles

Now that we have a good understanding about playbooks it is time to move on to roles. In Ansible roles allow Ansible to be reusable. The Ansible community provides galaxy which allows community members to share roles. There are 1000s of roles so often if you want to do something in Ansible, there is probably already a roll that exists in galaxy to do so. You can also easily modify roles to fit intended purpose. We now come to best practice #4, don’t be lazy, always create roles. Not only will roles allow you to share your playbook packages with others, but will also enforce good structuring , clean code and allow you to re-use role components in ways that were not even considered. We will now restructure our playbook tasks, variables, handlers and templates into a add user role.

Create empty role structure.

The ansible-galaxy command allows lists, installs and removes roles from galaxy. It also generates the empty structure of a role, useful for creating your own roles. Here we will create the empty structure for our new add_user role.

$ ansible-galaxy init --offline -p roles add_user

 Create role tasks.

Now we will move the tasks from our playbook into the role. A simply copy/paste and delete of the first four empty spaces of each line will suffice.

$ vi roles/add_user/tasks/main.yml
---
- name: Configure MOTD using template
  template:
    src: ./motd.j2
    dest: /etc/motd
    owner: root
    group: root
    mode: 0644
- name: Print Memory and CPU Cores 
  debug: 
    msg: "Host {{ ansible_hostname }} has {{ ansible_memtotal_mb }} MB Memory and {{ ansible_processor_cores }} CPU Cores."
  tags:
    - info
- block:
    - name: Add a user
      user:
        name: "{{ item }}"
        shell: /bin/bash
        generate_ssh_keys: yes
        state: present
      with_items: "{{ users }}"
      when: item is defined
      notify:
        - 'Configure sudo permission'
  rescue:
    - name: revert user add
      user: 
        name: "{{ item }}" 
        state: absent 
      with_items: "{{ users }}" 
      when: item is defined

Create role handlers.

Similar to tasks handlers also have a specific location within a role. Again copy/paste and delete of the first four spaces of each line.

$ vi roles/add_user/handlers/main.yml
---
- name: Configure sudo permission
  lineinfile:
    dest: /etc/sudoers.d/{{ item }}
    line: 'ansible ALL=(ALL) NOPASSWD: ALL'
    create: yes
    state: present
  with_items: "{{ users }}"
  when: item is defined

Create role vars.

Variables for a role can be stored under vars or default. In this case we will put them under vars.

$ vi roles/add_users/vars/main.yml
--- 
users: 
  - ansible 
  - bob 
  - joe 
  - keith

Create role templates.

Templates simply need to be copied to the correct location.

$ cp motd.j2 roles/add_user/templates

Create playbook that uses role.

$ vi add_user_using_role.yml
---
- name: Add user using role
  hosts: servers
  roles:
    - add_user

Run playbook.

$ ansible-playbook add_user_using_role.yml -u ansible -b -i ./inventory

The playbook will now execute our role. As you have seen roles provide a pre-defined structuring and packaging of playbook tasks that greatly enhances re-usability.

Summary

In this article we have discussed the need and great opportunity automation provides. We have explored the basics of Ansible and why Ansible has become the standard language of automation. This article attempts to provide a pragmatic approach to learning Ansible, from installation, adhoc commands, creating your first playbook , learning fundamentals and finally putting it all together in a role. The greatest thing you can do for yourself and your organization is to automate everything.

Happy Automating!

(c) 2017 Keith Tenzer

 

 

 

 

 

 

 

 

 

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s