For our first example, let's do the most important initial setup I do on new computers: installing and configuring Emacs! To make it as simple as possible, let's just assume that package caches are updated and ready for use.

---
- hosts: all
  become: true

  tasks:
    - name: Make sure Emacs is installed
      package: 
	name:
	  - emacs
	  - git
	state: present

    - name: Download Emacs  config
      become: false
      git:
	repo: https://github.com/themkat/.emacs.d.git
	dest: ~/.emacs.d

(this assumes that the user who we have configured in the inventory file is the user who will use the emacs config)

Here we have two tasks; installing Emacs and Git, and cloning my git config into the users home directory (the user we configured in our inventory). You might notice the become: true and become: false, which denotes if a task should be run as the root user or not (true for root user, false for the normal user). If you don't have password-less sudo access, you will have to run your playbook with the –ask-become-pass option.

The two modules used here is package and git, which both have away more options than used here. Package is a generic package management module, that will use the operating systems underlying package manager to do its work. If you need more advanced package management operations that are exclusive to your package manager (updating cache where needed etc.), there are packages for others as well (e.g, homebrew, apt, and yum). From above we see that, with the current settings, the module makes sure the packages are present on the system. If they are, then we do nothing (i.e, no changes), and if they're not we install them.

The git module works as you would expect: clones the git repository to the selected destination. If we don't always want the newest version from origin, we could add the update: no option.

Next, let's make it a bit more advanced to introduce more concepts. We'll make a simple FTP server. Let's update package caches if we use a Debian based system (because apt requires that we have updated package archives to install a program).

---
- hosts: all
  become: true

  vars:
    username: ftpuser

  pre_tasks:
    - name: Update package archives (Debian-based)
      apt:
	update_cache: true
	cache_valid_time: 7200
      when: ansible_os_family == "Debian"

  tasks:
    - name: Set up user we want to use for FTP access
      user:
	name: "{{ username }}"
	password: "{{ username | password_hash('sha512', 'saltval') }}"
	state: present

    - import_tasks: ftp_server_tasks.yml

(a better way to handle the password would be to use something like Ansible Vault)

You might wonder how the tasks from the import_tasks operation looks like? Just a lists of tasks to do:

---
- name: Install vsftpd
  package: name=vsftpd state=present

- name: Make sure bftpd is started and active at startup
  service: name=vsftpd state=started enabled=true

You might have noticed the variable ansible_os_family above. How do Ansible know which operating system family their hosts have? Do you have to set it yourself? No, you don't! If you have tried running a playbook, you might have noticed a stage called gather facts. In this stage, Ansible collects facts about your system and populates various variables. You can also run this step manually using the setup module and see all the information Ansible collects in this stage:

ansible -i inventory.ini mygroup -m setup 

You might also notice that we declare a username variable above? Ansible provides many different ways of creating and interacting with variables.

We are also introduced to two new modules above: user and service. The user module handles exactly that, users, and in this case we make sure a user account is present. If it is not, we make it with the given password (here hashed with the password_hash operation). Service will in the case above make sure the service is started and enabled at startup.

Beyond those features, the other features probably explains themselves. when runs something when a given condition is true, and Ansible provides you with several such conditional to control the flow of your playbooks. We also see the import_tasks above, and there are several ways we can put our tasks in separate files. import_tasks are done during playbook initialization, while include_tasks are done during execution, so we would use include_tasks if we depended on dynamic variables above (i.e, created during execution)

So far we've seen a several features, and got them explained briefly. In this section, we will look at a loop construct, specifically with_items. In my own playbooks I usually use with_items or with_indexed_items, but loop does the same in a more modern way.

---
- hosts: all
  become: true

  vars:
    users:
      - themkat
      - arttheclown
      - leatherface

  tasks:
    - name: Make sure Emacs is installed
      package: 
	name:
	  - emacs
	  - git
	 state: present

     - name: set up users
       user:
	 name: ""
       with_items: ""

     - name: Download Emacs  config
       git:
	 repo: https://github.com/themkat/.emacs.d.git
	 dest: "/home/.emacs.d"
       with_items: ""

Here we iterate on the users variable, running the module user and git for each of them. The end result is that the users themkat, arttheclown and leatherface all have themkat's Emacs setup ready to be used! (authors remark: I'm indeed very happy I don't share any computers with Art the Clown or Leatherface…)

There are many Ansible modules you can use, and if you don't find what you need you will probably find it in a collection (see below). Some useful highlights include:

• package, apt, yum
• user
• file (creating/touching files, making directory, setting modes etc.)
• lineinfile (edits single lines in files, and make sure they are at in given state. Uses regular expressions to find the line to edit, and adds it if its not present)
• template (make a file from a Jinja2 template. Useful to configure various programs like webservers)
• get_uri (download a file to the server. Can include checksums to validate correctness)
• service
• k8s and k8s_info (handling of Kubernetes clusters)

There are one very useful thing we have not covered above: setting environment variables. This is quite simple in Ansible, just add a environment section in addition to the name and module, and fill it with the name and values or your environment variables.

The interested reader might also check out blocks, which provide logical groupings. If you need fault tolerance like rollbacks, they also provide a try-catch-finally like structure to use (i.e, try=try to do something, catch=do if it fails, finally=always do).

Maybe you manage a lot of computers, create new ones quickly, and find it tedious to update your inventory file? It grows big too! Do I really need to write all my IPs/hostnames in a file? No! There are actually plugins that can help you dynamically fetch the inventory based on certain parameters. Also, AWS EC2 plugin, Azure plugin, and many more exists, even if you sometimes have to use ansible-galaxy to install them. Maybe you have tagged your virtual machine or something similar to identify them? Then use those specific tags to put them into host groups, and you are all set!

If you can't find what you are looking for somewhere else, you can always make your own!

There are indeed tools you can use to test your playbooks, and to work in a more test driven approach. My approach so far has been the following:

1. Use a virtual machine to define the basic setup. Here I use yamllint and ansible-lint to fix basic best practices and possible issues (ansible-lint is quite clever here!).
2. Use Molecule to write basic tests, fix idempotency issues missed earlier, make sure that setup works possibly more bare bones setups than the VMs etc. Molecule config is YAML, and the tests themselves are written in Ansible Playbook syntax. You may wonder what the it tests your playbooks on? You can choose VMs (using Vagrant), containers (using Docker) or probably something else. I use Docker for my tests, and it works great.

Testing playbooks is a topic in itself, so to not clutter up the entire article we will save that for a possible later article :) I will say that yamllint and ansible-lint together filters out the worst syntax related mistakes, and ansible-lint also checks for some best practices that can help you avoid mistakes.

Both roles and collection can be installed and handled with the ansible-galaxy tool.

Roles are "packages" of tasks we can import. Think of it as include_tasks on steroids! A role we use can have its own variables, files, templates etc., making it a powerful way of making the closest thing we have to "Ansible packages". To use a role, we simply install it with ansible-galaxy, and use it like this in our play:

---
- host: myhost

  roles:
    - namespace.rolename

That's it! Then all tasks in the namespace.rolename role will run!

Collections are, like the name suggests, collections of roles, plugins, modules and similar. Why do we need it when we have roles? Roles can have plugins included after all… Well, roles are not really made for that, but are made for executing tasks (i.e, it happens at default when importing roles in a playbook). Collections, on the other hand, makes including different resource types easier. If that sounds interesting, I suggest reading the documentation. Collections, like roles, is a topic in itself, and I would not make it justice in a single blog article.