In this short post I wanted to show you how to use the ansible package module. Have you ever ended up writing a bunch of when statements for different distributions just to use the right package manager? You can use the ansible package module instead, it will automatically choose the right package manager for you:

- hosts: all
  tasks:
    - name: Install vim
      ansible.builtin.package:
        name: vim
        state: present
        update_cache: true

As the module is used as "proxy module" and redirects all parameters you specify to it to the target module (apt, yum...) we can add "update_cache" to update the specific package manager cache.

ansible.builtin.package module – Generic OS package manager — Ansible Community Documentation

EDIT: update_cache was not missing in docs - the package module interacts as proxy module which can pass all parameters to the target module.

Hope you find this useful!

Best regards

Mow

In the last few days I needed to use lists in ansible which are extended and manipulated at runtime. So I will leave a short code snipped here - maybe it is useful for you too:

- hosts: localhost
  connection: local
  vars:
    my_list: [ "Hello", "World", "this", "is", "just", "a", "list", "of", "strings" ]
  tasks:
    - name: build list with all items with an 'i' in it
      set_fact:
        my_dynamic_list: "{{ my_dynamic_list|default([]) + [ item ] }}"
      loop: "{{ my_list }}"
      when: "'i' in item"
      
    - name: print results
      debug:
        msg: "{{ my_dynamic_list }}"

PLAY [localhost] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [localhost]

TASK [build list with all items an 'i' in it] ********************************************************************************************************************************************************
skipping: [localhost] => (item=Hello) 
skipping: [localhost] => (item=World) 
ok: [localhost] => (item=this)
ok: [localhost] => (item=is)
skipping: [localhost] => (item=just) 
skipping: [localhost] => (item=a) 
ok: [localhost] => (item=list)
skipping: [localhost] => (item=of) 
ok: [localhost] => (item=strings)

TASK [print results] ********************************************************************************************************************************************************
ok: [localhost] => {
    "msg": [
        "this",
        "is",
        "list",
        "strings"
    ]
}

PLAY RECAP ********************************************************************************************************************************************************
localhost                  : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

Short explanation

First, a list of sample values "my_list" is defined. The first task then iterates through all elements of "my_list". In addition, the task is given the condition

if: "'i' in item"

In other words, the task will only be executed if the item contains the letter "i". If the condition is true, the item will be added to the target list. The Jinja2 filter 'default':

my_dynamic_list: "{{ my_dynamic_list|default([]) + [ item ] }}"

basically intercepts the first run for which the list "my_dynamic_list" does not yet exist, and returns an empty list in this case. Since you can only append another list - and not a string - to a list, we define the string in a list with a single item:

... [ item ] ...

Maybe some of you will find this little code snippet useful :)

Regards!

In our Ansible 101 guide, we learned about roles. But there is another thing in Ansible called collections. In this blog post I want to explain what collections are used for and what an FQCN (Fully Qualified Collection Name) is.

So what is a collection? Basically, it is a distribution format for shipping packaged Ansible content. It can contain:

• Modules
• Plugins
• Roles
• Playbooks
• Documentation
• Dependencies (information of required other roles, collections...)

FQCN (Fully Qualified Collection Name)

You may have already noticed the way that Ansible modules are called, such as

- name: install apache2
  ansible.builtin.apt: # <-- FQCN
    name: apache2
    state: present

This is the FQCN for the apt module. The collection name is "ansible.builtin" and we are using the "user" module contained in that collection. The "builtin" is the default ansible internal collection containing the ansible "core".

Community collections

The cool thing about collections is that they can be built and shared by the Ansible community. There are many collections out there. For example the community.general collection:

Community.General — Ansible Community Documentation

You will find really a lot of collections on ansible galaxy or GitHub:

Ansible Galaxy

Collection Structure

Like in a role (feel free to check out my blog post about roles here) a collection is sturctured by directories. The basic structure looks like this (source: Ansible docs):

collection/
├── docs/
├── galaxy.yml
├── meta/
│   └── runtime.yml
├── plugins/
│   ├── modules/
│   │   └── module1.py
│   ├── inventory/
│   └── .../
├── README.md
├── roles/
│   ├── role1/
│   ├── role2/
│   └── .../
├── playbooks/
│   ├── files/
│   ├── vars/
│   ├── templates/
│   └── tasks/
└── tests/

Example: Call the terraform module from community collection

Let's say we want to use ansible to manage some terraform deployments. There is a terraform module in the community.general collection. So first we need to install that collection using ansible galaxy:

ansible-galaxy collection install community.general

Then we can start using the installed collection in our playbooks (source: ansible docs):

- hosts: my_tf_host
  tasks:
    - name: Basic deploy of a service
      community.general.terraform:
        project_path: '{{ project_dir }}'
        state: present

This is a very simple example, but it should show you how you can use collections. You can also create your own collections using the structure shown above!
That's it for now. The best way to learn this stuff is to try it out! Feedback is always appreciated!

Mow

We are slowly approaching the end of the "Ansible 101", the basics of Ansible. However, we still have one big topic to cover: Roles.

So far, we have been writing and running our Ansible code in playbooks. Now, if we want to write Ansible code that we want to use across projects - or even publish, for example - we quickly reach the limits of playbooks. This is where Ansible roles come in. They allow us to create reusable and parameterizable Ansible content. We can then integrate one - or more - playbooks into a role.

The structure of an Ansible role is represented by a directory structure. A typical role looks like this:

# playbooks
webservers.yml
roles/
    my-webserver-role/
        tasks/
          - main.yml
        handlers/
          - main.yml
        files/
        templates/
        vars/
          - main.yml
        defaults/
          - main.yml
        meta/
          - main.yml

In this example we see a role called "my-webserver-role". Let me briefly explain each subdirectory:

• tasks - Here are files where we define our tasks
• handlers - Here are handlers defined if our role needs them
• files - This is where we put files we want to use with the copy module, for example
• templates - If we need Jinja2 templates, we put them here
• vars - This is where we store role-internal variable definitions
• defaults - Here we can define default values for variables, which can be overridden by the "role user"
• mta - This is where we store meta information about the role itself

An example of a more detailed web server role can be found here:

https://github.com/dermow/ansible-role-httpd

For our guide, however, I want to make the example a little simpler. Let's define the following tasks for the role:

Support limited to Ubuntu
Install the Apache web server
Providing a custom index.html
Starting and enabling the Apache service

First, it is important to note that by default, Ansible searches for roles in defined locations. These include "./roles" in your project directory. Let's start by creating the directory structure:

mkdir ~/ansible-guide-roles
cd ~/ansible-guide-roles
mkdir -p ./roles/my-webserver-role
cd ./roles/my-webserver-role
mkdir tasks templates handlers vars defaults

What's missing is an inventory - I'll use our test environment again. Of course, being the smart guy that I am, I took a snapshot beforehand and didn't have to reinstall it (chrm chrm).

[webservers]
ansible-guide-1 ansible_ssh_user=ansible ansible_host=192.168.0.11
ansible-guide-2 ansible_ssh_user=ansible ansible_host=192.168.0.12

The next step is to create a file for our variable definitions:

---
packages_to_install:
  - apache2
  - libapache2-mod-php

We have defined a list in which we specify which packages we want to install later. The next step is to create the corresponding task:

---
- name: install packages
  become: true
  ansible.builtin.apt:
    name: "{{ item }}"
    state: present
  loop: "{{ packages_to_install }}"

Now we have a first version of the role that we can test. To do this, we will create a playbook with the following code:

---
- hosts: webservers
  roles:
    - my-webserver-role

Lets start the playbook:

ansible-playbook -i inventory.txt playbook.yml

PLAY [webservers] ********************************************************************************************************************************************************

TASK [Gathering Facts] ********************************************************************************************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [my-webserver-role : install packages] ********************************************************************************************************************************************************
changed: [ansible-guide-1] => (item=apache2)
changed: [ansible-guide-1] => (item=libapache2-mod-php)
changed: [ansible-guide-2] => (item=apache2)
changed: [ansible-guide-2] => (item=libapache2-mod-php)

PLAY RECAP ********************************************************************************************************************************************************
ansible-guide-1                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 
ansible-guide-2                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 

Great, it worked: The Apache web server and the PHP module should now be installed on both target machines. The next step is to make sure that the web server service is started and running:

---
- name: install packages
  become: true
  ansible.builtin.apt:
    name: "{{ item }}"
    state: present
  loop: "{{ packages_to_install }}"
  
- name: start and enable apache
  become: true
  ansible.builtin.systemd:
    name: apache2
    state: started
    enabled: true
    

Now we want to ship our own config with the role. To do this, I simply stole the "default.conf" from the default installation and removed the comments:

cat /etc/apache2/sites-available/000-default.conf | grep -v "#"
<VirtualHost *:80>

	ServerAdmin webmaster@localhost
	DocumentRoot /var/www/html


	ErrorLog ${APACHE_LOG_DIR}/error.log
	CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

Let's say we only want the "ServerAdmin" to be configurable. So we create the appropriate template:

<VirtualHost *:80>

	ServerAdmin {{ my_server_admin }}
	DocumentRoot /var/www/html


	ErrorLog ${APACHE_LOG_DIR}/error.log
	CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

Now we just have to define the variable "my_server_admin". Since this should be overridden by the "user", it makes sense to do this under "defaults":

my_server_admin: me@example.com

Now all you need are the tasks to deploy the template:

---
- name: install packages
  become: true
  ansible.builtin.apt:
    name: "{{ item }}"
    state: present
  loop: "{{ packages_to_install }}"
  
- name: start and enable apache
  become: true
  ansible.builtin.systemd:
    name: apache2
    state: started
    enabled: true
    
- name: template web config
  become: true
  ansible.builtin.template:
    src: 000-default.conf
    dest: /etc/apache2/sites-available/000-default.conf
    

Now, of course, it would be great if the web server could be restarted automatically when changes are made to the configuration. We already discussed a suitable tool for this in Part 4: Handler.

So we create a handler...

---
- name: restart-apache
  become: true
  ansible.builtin.systemd:
    name: "apache2"
    state: restarted
  

... And adapt our mission accordingly:

---
- name: install packages
  become: true
  ansible.builtin.apt:
    name: "{{ item }}"
    state: present
  loop: "{{ packages_to_install }}"
  
- name: start and enable apache
  become: true
  ansible.builtin.systemd:
    name: apache2
    state: started
    enabled: true
    
- name: template web config
  become: true
  ansible.builtin.template:
    src: 000-default.conf
    dest: /etc/apache2/sites-available/000-default.conf
  notify: restart-apache # <---- HANDLER
    

And go:

ansible-playbook -i inventory.txt playbook.yml

PLAY [webservers] ********************************************************************************************************************************************************

TASK [Gathering Facts] ********************************************************************************************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [my-webserver-role : install packages] ********************************************************************************************************************************************************
ok: [ansible-guide-1] => (item=apache2)
ok: [ansible-guide-1] => (item=libapache2-mod-php)
ok: [ansible-guide-2] => (item=apache2)
ok: [ansible-guide-2] => (item=libapache2-mod-php)

TASK [my-webserver-role : start and enable apache] ********************************************************************************************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [my-webserver-role : template web config] ********************************************************************************************************************************************************
changed: [ansible-guide-1]
changed: [ansible-guide-2]

RUNNING HANDLER [my-webserver-role : restart-apache] ********************************************************************************************************************************************************
changed: [ansible-guide-1]
changed: [ansible-guide-2]

PLAY RECAP ********************************************************************************************************************************************************
ansible-guide-1                  : ok=5    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
ansible-guide-2                  : ok=5    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

That looks good :) All that remains is the last part of our to-do list: Provide our own index.html. With what we've learned so far, this shouldn't be a problem: we simply create another template:

<html>
  <head>
    <title>{{ my_website_title }}</title>
  </head>
  <body>
    {{ my_website_content }}
  </body>
</html>

So we created another template in which we want to use two new variables. We also create default values for them:

my_server_admin: me@example.com
my_website_title: "Ansible 101"
my_website_content: "Hello World"

Finally, the task to deliver the index.html:

---
- name: install packages
  become: true
  ansible.builtin.apt:
    name: "{{ item }}"
    state: present
  loop: "{{ packages_to_install }}"
  
- name: start and enable apache
  become: true
  ansible.builtin.systemd:
    name: apache2
    state: started
    enabled: true
    
- name: template web config
  become: true
  ansible.builtin.template:
    src: 000-default.conf
    dest: /etc/apache2/sites-available/000-default.conf
  notify: restart-apache # <---- HANDLER
  
- name: template index.html
  become: true
  ansible.builtin.template:
    src: index.html
    dest: /var/www/html/index.html
    

But let's say we want to use our own value for our title instead of the default from the role:

ansible-playbook -i inventory.txt -e "my_website_title='My fancy title'" playbook.yml

 PLAY [webservers] ********************************************************************************************************************************************************

TASK [Gathering Facts] ********************************************************************************************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [my-webserver-role : install packages] ********************************************************************************************************************************************************
ok: [ansible-guide-1] => (item=apache2)
ok: [ansible-guide-1] => (item=libapache2-mod-php)
ok: [ansible-guide-2] => (item=apache2)
ok: [ansible-guide-2] => (item=libapache2-mod-php)

TASK [my-webserver-role : start and enable apache] ********************************************************************************************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [my-webserver-role : template web config] ********************************************************************************************************************************************************
changed: [ansible-guide-1]
changed: [ansible-guide-2]

TASK [my-webserver-role : template index.html] ********************************************************************************************************************************************************
changed: [ansible-guide-1]
changed: [ansible-guide-2]

RUNNING HANDLER [my-webserver-role : restart-apache] ********************************************************************************************************************************************************
changed: [ansible-guide-1]
changed: [ansible-guide-2]

PLAY RECAP ********************************************************************************************************************************************************
ansible-guide-1                  : ok=5    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
ansible-guide-2                  : ok=5    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

Done! Now a quick test to see if it all worked:

curl 192.168.0.11

 <html>
  <head>
    <title>My fancy title</title>
  </head>
  <body>
    Hello World
  </body>
</html>

Note: In a real scenario, you should define the variables you want to override in your groupvars, hostvars, or in the playbook using the role instead of setting them in the ansible command.

Pro tip

Ready made rolls are available for many applications. Take a look here:

https://galaxy.ansible.com/

THE END

This concludes the 101 Guide. You should now be able to continue learning on your own and just work with it in your own environment. I'm not sure yet if I'll start an "Advanced Guide" in the same style, or if I'll just cover certain topics as they come up.

Of course I would be very happy to get some feedback. See you soon

Mow

In this part of the Ansible guide, I want to introduce you to the Ansible Vault. We can use it to encrypt data in Ansible. Many tasks require credentials that we do not want to store in plain text as a variable.

The Ansible Vault is included with the installation of Ansible, so it does not need to be installed separately.
Creating a new vault
First we need to generate a password for the vault, I like to use the "pwgen" tool for this. I have the password written directly to a hidden file in my home directory.

sudo apt install pwgen

# 1 Passwort mit 12 Zeichen erstellen
pwgen 12 1 > ~/.vaultpw

Now we can create a vault as follows. In this example, we store the vault in host vars:

cd ~/ansible-guide
mkdir -p host_vars/ansible-guide-1

ansible-vault create host_vars/ansible-guide-1/vault.yml --vault-password-file ~/.vaultpw

With the above command, we have created a new file and encrypted it with the password we created earlier. An editor should open immediately after the command.

The contents of this file can be arbitrary; in the simplest example, we can simply define variables here. Let's say we want to create a new user on our host and store his password in the vault:

user_password: geheim1337

Save the file and you have successfully created your first Vault Secret :)

If we look at the contents of the file, it should look something like this:

$ANSIBLE_VAULT;1.1;AES256
32363637353431323335313831306531653461353135303736343138336238393861663962396139
6637636264613234326461316539636231353537666538370a663266346333643430313538646332
30663139653637313935646130366530363361646565313436633430363935613532313966323536
6632313462383464640a346538656131353038383338313337346365396131343336666466326566
38393836636437333939363330323033613535376661333330613934663066303639

As we can see, the contents of the vault are cryptic and unreadable. So we can load the file into a source manager, for example, without storing the credentials in plain text.

In this case, we can use the secret as a normal variable:

- hosts: ansible-guide-1
  tasks:
    - name: create user
      ansible.builtin.user:
        name: me
        password: "{%raw%}{{ user_password }}{%endraw%}"
        state: present

If we now try to run the playbook as usual, the result should look something like this:

PLAY [localhost] *********************************************************************************
ERROR! Attempting to decrypt but no vault secrets found

That's right! We need to enter the Vault password:

ansible-playbook --vault-password-file ~/.vaultpw playbook.yml

And it works. But how exactly? Ansible will search the variable directories (host_vars, group_vars) at startup as usual, find the encrypted vault, and decrypt it.

An Ansible vault does not have to be an encrypted YAML file of variables. In principle, we can use it to encrypt any file.

Example: Storing a certificate and key in a vault

Let's assume we want to deliver an SSL certificate including a key to a web server.

We put both files in a subfolder called "files":

-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIJnDBOBgkqhkiG9w0BBQ0wQTApBgkqhkiG9w0BBQwwHAQI3mHrY1wSLzgCAggA
MAwGCCqGSIb3DQIJBQAwFAYIKoZIhvcNAwcECPZFWT3K2GKaBIIJSHVxKQ3lvbwa
kh+ENQhmFQrxau5IZSeiw+D9QVFUCNc02AquLg4Pp0eBUnNtMzyGHl1w/yncdZwB
mw4ycH6Rfs0JJtP23nlcDJzTCqTeyHMQExkeQbVLADuPteoQFsjdvGLPbA5Sq5+w
WNAflSac61x3Hk9ND8y+2twISqyokixdgLWmlx72QvJ2znBA1BwRTkPzdwuvKVrA
Up5Zl82lOWzcDhRmQNxqHoH/P0h4oUfudt2RCTELX/OS/97PqMGIvu1BtcGdW+UO
DW+K+TIr/1JlfuqrUP7D3VTi5FP5nY8CgiQc5JfIY2s6K74VYfDZ1EwoUj8FJ1FX
QToErFfTm54tJ1yBpIHQjqXGGQGs1s3S3OnGztsTEZWNNgT5PzQXZN+pL4Bl0Zg5
0OubP1XJRrTjQLLpb2r+cYFnyw9vSUZ6iopA0h49nY8GatkUu39QzSg32wg4HJDh
oACRVKthGIjLyJYYeYDKc96cgKgpSEsuC5bCUzt0AmZbjgvdsBdNRq1R3dN/mZL6
Vr35I3hqHZ/HcomFYrLCy8LEMChiHMUsZA0nuWYiJXpj17so8k7gGA65U9iGjK5M
Me+mOSRIprlwW1bTHZ9OTq+IlWBrswHF0l+YXWPEfV2B9R0mBrt5Cmvf29cbjl4G
xgMDH5daXW2c0y4kDcZJ33Vw7wk7Dv7efKQqUUFKhXlSoI8gZ4zCFiflL3ZunzCe
6Uz8jscifY07U9MwEeBDTh1SG6Hc8bJJ31509D+zDrb5bwBXQHr6QojSxyHd/2WT
a4QM8Qqtk7PfLbUXIP2S1h69e6oGLBFH77VSLzzAnPuPW0/uCILabp4ekaeOJ99x
Q9wk1JrcKZk8TEom6o2hKVZ8goM3fxXvRulstoowl1MmTIlNf67iUn5/j42jnIkO
Bmvsv5J2VERyxm4ZR7Qz/kpANUkZPYunSRE1VeHWzK/dvkajnoHfrA1u/wL+C4QS
bB4GwE8O8RFS9mkLwvfRl8dHKhvoFil7hml/5MFIGWHJ40PJ+4xRFMMOq74+gnqr
eOlhOF1NG8+4dNVQhrltHdNrgXX18GXtG8qbGONrCgPGRFniB1V8T/ZV84Y7S2yt
kfTCNWpTTr2JoFo36jsyNQ+DOAZh8CryVxgTlsyG9g0m7GZL/6Smyl1RB20TV0UU
ZQAPAy6WawGTPZmJ4RJu5ijtseCu9wmHZqTPd1ORTnadAIWS7HVTAcVtfL1aH4eo
LRxBz1utryvIiV1nNibmDDNzNbCpt7UfMAyWNDeGkDIb6BQXvvixjjWmOs5KzLkr
jcIMbECAJrKyk/hzGGQBDD5NHL3S+Q2QlMgnkfZ9Gjbr69XcNMieMi2LKslzYKmw
X/t91y6eKSgFw+BF3ZmhzG1jH/vAccXG2IBzweIuUXeLigDk+3Rp+TEKxHa88sVm
2nNpL8M7jdoyYdkaejx9UQ==
-----END ENCRYPTED PRIVATE KEY-----

-----BEGIN CERTIFICATE-----
MIIFazCCA1OgAwIBAgIUFiGHe0Hh1w5uxMsAITAC0loQ044wDQYJKoZIhvcNAQEL
BQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM
GEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAeFw0yMTA5MjQxMTA5MjFaFw0yMjA5
MjQxMTA5MjFaMEUxCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEw
HwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwggIiMA0GCSqGSIb3DQEB
AQUAA4ICDwAwggIKAoICAQDHOgqyCi80NikeXGX101mjWUeJfejBw87KS1VXxtOk
L1tIAMFi36FYF+dGZ95e0hWBRJiE7hbMxLN21rt+P3v3EMOXVgLKkED1ME0W5EbJ
wUOcJ1Dh/MV9dF1WUakgopNU8CgJLGgS/VBdncUwWnsUjHOxf0j6XZ7dqGaresrp
3xRy69NBeqzXwjQCh58OpXo0lv6zZVeHxGh6mHkBPUTkbrk0/2YuObvvxF6DsiRu
zpN/s3GRZ927iMxViEj5DDEVMKpXJze2ScFml5V99zpSJvw/mOb2ieKmvT7atAZW
vI/O/fM/lO9RkhZwAaoV3Wn+MXlfXFbP9sDV441ENgU0sjkRJv8eyclkeEIM9wg6
XSX8LraFfaszWCtSphTLB+tX01FOGrkOm3lpf8OGEMr4RXVnjEvB/k3JMNrmzpSf
R5LjtAqaoD4rg3wAVnyLlWEOOtEcAZFBoVSY5TMDA9yb1akGiNBvj1WNryO0bcUI
yQ4xENJ/q/yJ7pbtqbuccL1UIWhcvQrvI9OTuQCNNfD+KWBZat7aEP79c7hQuZqA
1GN9ZFZv7xBXDjmV6GZwRy+wjvFHAmW0qCzXwpS0+ibHtWD2qBbulpZD+K0WdfVu
22tEFUOP5Lni7mJVqqIjL77yLswnldxZoF3qXHkEbQexds8FgqiSPm19uY/mW4L6
IQIDAQABo1MwUTAdBgNVHQ4EFgQUPHQPwK0qKdiP5C78p2urUn0IGA8wHwYDVR0j
BBgwFoAUPHQPwK0qKdiP5C78p2urUn0IGA8wDwYDVR0TAQH/BAUwAwEB/zANBgkq
hkiG9w0BAQsFAAOCAgEAf1WDaODUcxatC10Aa/iG1BSQeFwwIibHsP8uoR4rhvOc
32FPivbk6q/Fv5WgeBkZvpjTKglMJBV8EtbDO8aAH3/7cEe8ycchSgOvX64RgzZY
e6a2HJwQ8KIPGlKcgU57CHu6aaEW3BFzvw6j0GdQHKTw8eiYKuYW8bO/4fKRxr+F
w/bV2Cg4yyor87CSgLLawS+4yPzMCFlIOr8AMswV9VIqIlem3mWyf13WS0JAEQwe
dohfa2KGeccqTudTS9NfEJRoSt7ufXHS937gtVgimCJIdt08p5eSfznvhtHVAntl
yF0Irp1DxC+IyalWielLTxwSVsyyEu8oL4zX46C6yGG4rfZv7T6rBJOonoYEmRyv
fyFfhOI8N3CaxOk8S0FTe06HsR9caAfmGE3Qz8yDRR7qgZvaufYPgO7PjGzzvPWV
c4cevlKuGuW2IzHkzq1kQThNF74lbrBTa1QAaC6JbTBuFFwyZYAE7r4+zHx+1yFr
DY5haeOZaikakxwHaaTzGwCeQMufbIJ4kfu1zxNDvOlZVtfA7DyGcnSd763/nS5E
Kl4fE8YzHWPvQJNIpx27REXE4dEs1/soMZFWokHsjg2HmYlL4M8fH9PU8sBl/MLb
8UwAg369islBzup+yn1RrLl5iRITSkHyfuHyRv8Sgs6P29MuDraV91o23J8JAiU=
-----END CERTIFICATE-----

Now, we don't want to have both files lying around in plain text. So we encrypt them using the Ansible Vault:

ansible-vault encrypt files/*.pem --vault-password-file ~/.vaultpw

Encryption successful

In our playbook, we can use the Copy module as usual to copy both files. Because Ansible recognizes that these are vaults, it decrypts both files.

- hosts: webserver-1
  tasks:
    - name: copy certificate and key
      ansible.builtin.copy:
        src: "files/{%raw%}{{ item }}{%endraw%}"
        dest: /etc/ssl/certs
      loop:
        - cert.pem
        - key.pem

Run the playbook:

ansible-playbook playbook.yml --vault-password-file ~/.vaultpw

Done! Both files should be on the server in decrypted form 😄

Encrypt single strings

Instead of encrypting entire files, we can simply encrypt variable values:

ansible-vault encrypt_string "hello world" --vault-password-file ~/.vaultpw

!vault |
          $ANSIBLE_VAULT;1.1;AES256
          64613036333366373032623562333639646565303830653335366361373533663835666135343861
  3864316335646165633439656662666537653538623662320a346432353261636466353964633365
          61636463306537313137373630323633376465663938633130633637623866326639613235323262
          3665643535633739640a366162363664356337363062636535343463323263653934623434626664
          3233
Encryption successful

Within Ansible, we can then define the string as a variable like this:

my_encrypted_var: !vault |
          $ANSIBLE_VAULT;1.1;AES256
  64613036333366373032623562333639646565303830653335366361373533663835666135343861
          3864316335646165633439656662666537653538623662320a346432353261636466353964633365
          61636463306537313137373630323633376465663938633130633637623866326639613235323262
          3665643535633739640a366162363664356337363062636535343463323263653934623434626664
          3233

This brings us to the end of the article. I hope I was able to teach some of you something new :)

As always, I would love to hear your feedback!

See you soon,

Mow

Dictionaries

But before we return to our loops, I would like to introduce you to dictionaries, which were only briefly mentioned in Part 5. Simply put, dictionaries are lists whose elements can have multiple fields. A simple example:

people:
  - firstName: Ronald
    surName: Weasley
    age: 21
  - firstName: Gilderoy
    surName: Lockhart
    age: 40
  - firstName: Albus
    surName: Dumbledore
    age: 99

As in a simple "list", the hyphen marks the beginning of a new item. In this example, each of the two items has the fields "name", "last name", and "age".

We can also use dictionaries in loops. For example, if we wanted to print the information defined in our example, the playbook would look like this:

- hosts: localhost
  vars:
    people:
      - firstName: Gilderoy
        surName: Lockhard
        age: 43
      - firstName: Minerva
        surName: McGonnagal
        age: 67
      - firstName: Albus
        surName: Dumbledore
        age: 99
       
  tasks:
    - name: list people
      ansible.builtin.debug:
        msg: "First Name: {{ item.firstName }}, Surname: {{ item.surName }}, Age: {{ item.age }}"
      loop: "{{ people }}"

PLAY [localhost] ***********************************************************************************
TASK [Gathering Facts] ***********************************************************************************
ok: [localhost]

TASK [list people] ***********************************************************************************
ok: [localhost] => (item={'firstName': 'Gilderoy', 'surName': 'Lockhard', 'age': 43}) => {
    "msg": "First Name: Gilderoy, surName: Lockhard, Age: 43"
}
ok: [localhost] => (item={'firstName': 'Minerva', 'surName': 'McGonnagal', 'age': 67}) => {
    "msg": "First Name: Minerva, surName: McGonnagal, Age: 67"
}
ok: [localhost] => (item={'firstName': 'Albus', 'surName': 'Dumbledore', 'age': 99}) => {
    "msg": "First Name: Albus, surName: Dumbledore, Age: 99"
}

PLAY RECAP ***********************************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

If we use a dictionary as a loop variable, we can access the individual fields within the task with "{{ item.FIELDNAME }}}".

Loops and conditionals

If we use a loop and a condition in the same task, the condition will be validated for each loop item.

- hosts: localhost
  vars:
    people:
      - firstName: Gilderoy
        surName: Lockhard
        age: 43
      - firstName: Minerva
        surName: McGonnagal
        age: 67
      - firstName: Albus
        surName: Dumbledore
        age: 99

   tasks:
    - name: list people oder than 90
      ansible.builtin.debug:
        msg: "{{ item.firstName }} is older than 90"
      loop: "{{ people }}"
      when: "item.age > 90"

PLAY [localhost] **************************************************************************************************************************************************************************************************

TASK [Gathering Facts] ********************************************************************************************************************************************************************************************
ok: [localhost]

TASK [list people oder than 90] ***********************************************************************************************************************************************************************************
skipping: [localhost] => (item={'firstName': 'Gilderoy', 'surName': 'Lockhard', 'age': 43}) 
skipping: [localhost] => (item={'firstName': 'Minerva', 'surName': 'McGonnagal', 'age': 67}) 
ok: [localhost] => (item={'firstName': 'Albus', 'surName': 'Dumbledore', 'age': 99}) => {
    "msg": "Albus: is older than 90"
}

PLAY RECAP ********************************************************************************************************************************************************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 

As you can see, two characters (Gilderoy, Minerva) have been skipped because they do not meet the condition (age > 90). Only good old Albus is over 90 :)

Loop control

In some cases it is necessary to control the behavior of loops. For example, you can set the name of the index variable (default is "item"). This is interesting, for example, if we want to use a loop inside another loop.

Changing the name of the index variable

A loop inside another loop? Huh? Who would do that? In some cases, it may even make sense. For example, here we have a playbook that integrates a task file for multiple elements:

- hosts: all
  tasks:
    - name: include tasks for every list item
      include: my-tasks.yml
      loop:
        - "A"
        - "B"
        - "C"

For example, the my-tasks.yml file might look like this in its simplest form:

- name: print item
  ansible.builtin.debug:
    msg: "{{ item }}"

During execution, the my-tasks file is included for each item listed in the loop in the playbook. The content of the loop variable is output to the my-tasks.yml file.

However, if we now want to use another task with a loop in my-tasks.yml, we have a small problem: the "item" variable is already used by the "outer" loop. This can be solved with loop_control:

- name: print item
  ansible.builtin.debug:
    msg: "{{ item }}"
    
 - name: another loop
   ansible.builtin.debug:
     msg: "{{ item_2 }}"
   loop:
     - "D"
     - "E"
     - "F"
   loop_control:
     index_var: item_2

Pause between items

We can alos use the loop control to specify, for example how long ansible should pause between processing each element:

- hosts: localhost
  tasks:
    - name: include tasks for every list item
      ansible.builtin.debug: 
        msg: "{{ item }}"
      loop:
        - "A"
        - "B"
        - "C"
      loop_control:
        pause: 5

So that's it for now. See you then!

Mow

I was just reading through the previous posts in the Ansible guide and realized that I forgot to mention two important Ansible features. One is check mode, which allows us to run playbooks in test mode. Changes are only shown in the output, not actually executed. Second, there is diff mode, which shows changes in "before and after" mode in the output.

Check Mode

To use the check mode, we simply need to append a "--check" to our command. Here is an example from our setup-postgres.yml playbook from the last part:

ansible-playbook -i inventory.txt setup-postgres.yml --check

PLAY [db] ***********************************************************************************
TASK [Gathering Facts] ***********************************************************************************
ok: [ansible-guide-3]
ok: [ansible-guide-4]

TASK [install postgresql on debian based systems (Ubuntu)] **************************************************************************************************************
changed: [ansible-guide-3]
skipping: [ansible-guide-4]

TASK [install postgresql on Redhat based systems (CentOS)] **************************************************************************************************************
skipping: [ansible-guide-3]
changed: [ansible-guide-4]

PLAY RECAP **************************************************************************************************************************************************************
ansible-guide-3                  : ok=2    changed=1    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0 
ansible-guide-4                  : ok=2    changed=1    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0 

The output is identical to that without check mode, but the changes have not been made on the hosts.

In principle, this works with any playbook, but there are a few special features:
Dependencies

If a task depends on a previous one, for example, because a package is installed and then the corresponding service is started, the following task in check mode will probably fail because the corresponding package has not actually been installed.

Shell commands

The command and shell modules will return the status "changed" as in normal mode, but the actual effect cannot be checked because the result of the shell command is independent of Ansible.

For such cases, we can skip individual tasks in check mode:

 - name: Skip this task in check mode
   ansible.builtin.lineinfile:
      line: "important config"
      dest: /path/to/myconfig.conf
      state: present
    check_mode: no

With the task parameter "check_mode: no", we tell Ansible not to run the corresponding task in check mode.

Diff Mode

Diff mode is independent of check mode, but can be used in conjunction with it. In diff mode, Ansible displays all changes from the original state. Here is a small example using the "lineinfile" module:

- hosts: ansible-guide-1
  tasks:
    - name: add entry to /etc/hosts
      ansible.builtin.lineinfile:
         path: /etc/hosts
         line: "192.168.0.3  ansible-guide-3"
         regexp: "^192.168.0.3"
      become: true

We will now run the playbook in check and diff mode:

ansible-playbook -i inventory.txt lineinfile_diff.yml --check --diff

PLAY [ansible-guide-1] ******************************************************************************************************************

TASK [Gathering Facts] ************************************************************************************************************
cok: [ansible-guide-1]

TASK [add entry to /etc/hosts] ****************************************************************************************************
--- before: /etc/hosts (content)
+++ after: /etc/hosts (content)
@@ -8,3 +8,4 @@
 ff00::0 ip6-mcastprefix
 ff02::1 ip6-allnodes
 ff02::2 ip6-allrouters
+192.168.0.3  ansible-guide-3

changed: [ansible-guide-1]

PLAY RECAP ************************************************************************************************************************
ansible-guide-1                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

If the result is OK for us, we can run the command again, this time omitting the "--check".

That's all there is to it! In the next part we will continue with part 2 of the loops!

Regards

Mow

We use a loop whenever we want to repeat a certain task several times. A classic example would be setting file permissions on a list of files and directories. With ten different paths, we would need ten different tasks, which is quite a lot of code. Loops allow us to do this in a single task definition. Loops also allow us to execute tasks on lists that we create at runtime.

Let's have a look at a task defined with a simple loop:

- hosts: all
  tasks:
    - name: task with loop
      ansible.builtin.debug: 
        msg: "I am: {{ item }}"
      loop:
        - "Loop-Item 1"
        - "Loop-Item 2"
        - "Item 3"
        - "Another Item"

There are two things of particular importance here. Firstly, the new task level parameter "loop". Here we can either specify a list of values directly (as in the example) or use a variable. More on this in a moment. Secondly, we use the variable "{{ item }}" in the message. This is always automatically available when we define a loop for our task and then contains the appropriate value from the list for each run.

The output of the above example would then look something like this:

PLAY [localhost] ********************************************************************************************************************************************************

TASK [Gathering Facts] **************************************************************************************************************************************************
ok: [localhost]

TASK [task with loop] ****************************************************************************************************************************************************
ok: [localhost] => (item=Loop-Item 1) => {
    "msg": "I am: Loop-Item 1"
}
ok: [localhost] => (item=Loop-Item 2) => {
    "msg": "I am: Loop-Item 2"
}
ok: [localhost] => (item=Item 3) => {
    "msg": "I am: Item 3"
}
ok: [localhost] => (item=Noch ein Item) => {
    "msg": "I am: Another Item"
}

PLAY RECAP **************************************************************************************************************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0  

So we have defined a task that runs once per item under "loop". And each time with the appropriate value from the loop in the 'item' variable.

Let's look at this with a practical example. Let's say we want to create several directories on our web servers:

/var/www/html/my_icons
/var/www/html/my_documents
/var/www/html/my_other_stuff

In this example, we do not want to define the 3 values directly under the "loop" parameter, but rather define them in a variable beforehand. This allows us to vary the content using the host and group variables, for example.

So we first create a variable in the groupvars for "webservers":

---
dirs_to_create: 
  - "/var/www/html/my_icons"
  - "/var/www/html/my_documents"
  - "/var/www/html/my_other_stuff"

The 'dirs_to_create' variable is of type 'list' and is now available to all hosts in the 'webservers' group. Now let's create an appropriate playbook:

---
- hosts: webservers
  tasks:
    - name: create directories
      ansible.builtin.file:
        path: "{{ item }}"
        state: directory
      loop: "{{ dirs_to_create }}"
      become: true

So we create a task with the "file" module. We can use this to manage files and directories. In this case, instead of specifying the list directly under "loop", we specify the variable "dirs_to_create". Ansible recognises that this is a list and applies "loop" to it. The list contains all the paths we want to create. So we specify the loop variable "item" in the module parameter "path" and use "state: directory" to specify that Ansible should create a directory.

Then we run the playbook:

ansible-playbook -i inventory.txt loops1.yml

PLAY [webservers] ********************************************************************************************************************************************************

TASK [Gathering Facts] **************************************************************************************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [create directories] ***********************************************************************************************************************************************
changed: [ansible-guide-1] => (item=/var/www/html/my_icons)
changed: [ansible-guide-1] => (item=/var/www/html/my_documents)
changed: [ansible-guide-1] => (item=/var/www/html/my_other_stuff)
changed: [ansible-guide-2] => (item=/var/www/html/my_icons)
changed: [ansible-guide-2] => (item=/var/www/html/my_documents)
changed: [ansible-guide-2] => (item=/var/www/html/my_other_stuff)

PLAY RECAP **************************************************************************************************************************************************************
ansible-guide-1                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
ansible-guide-2                 : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

For the sake of completeness, we check that the directories were actually created on the server:

ssh ansible-guide-1
ls -rtl /var/www/html

mow@notebook:~/blog$ ls -rtl /var/www/html/
insgesamt 16
-rw-r--r-- 1 root root   22 Feb 21 10:33 index.html
drwxr-xr-x 2 root root 4096 Mai  4 17:02 my_icons
drwxr-xr-x 2 root root 4096 Mai  4 17:02 my_documents
drwxr-xr-x 2 root root 4096 Mai  4 17:02 my_other_stuff

Looks good! Now you have the basis for further work with loops. Of course, you can use them not only in the "file" and "debug" modules, but with almost any module!

That's it for this part. In the next post, I'll show you some special features and advanced uses for loops.

As always, I look forward to any kind of constructive feedback!

Mow

ansible-guide-4

OS: CentOS 8
IP: 192.168.0.14

Our new inventory looks like this:

[webservers]
ansible-guide-1 ansible_ssh_user=ansible ansible_host=192.168.0.11
ansible-guide-2 ansible_ssh_user=ansible ansible_host=192.168.0.12

[db]
ansible-guide-3 ansible_ssh_user=ansible ansible_host=192.168.0.13
ansible-guide-4 ansible_ssh_user=ansible ansible_host=192.168.0.14

Now we want to manage 4 hosts with Ansible. Three of them running Ubuntu and one running CentOS. Our two web servers are the same. However, we use 2 different operating systems for the database servers.

Example 1: Installing packages on different distributions

Let's assume we want to install the PostgreSQL server on both database servers. In the previous examples we used the "apt" module. This will still work on our Ubuntu server. However, CentOS uses a tool called "yum" to manage packages. Fortunately, Ansible comes with a module for this out of the box:

https://docs.ansible.com/ansible/latest/collections/ansible/builtin/yum_module.html

But how do we get Ansible to use the right module for each host? We do it with (... drum roll...) conditionals! In other words, we use two tools we already know. First, we need facts, because they contain information about the host operating system. On the other hand, we need conditionals to make the tasks depend on the facts.

- hosts: db
  gather_facts: true
  tasks:
    - name: install postgresql on debian based systems (Ubuntu)
      become: true
      ansible.builtin.apt:
        name: postgresql
        update_cache: true
      when: "ansible_os_family == 'Debian'"
      
    - name: install postgresql on Redhat based systems (CentOS)
      become: true
      ansible.builtin.yum:
        name: postgresql
      when: "ansible_os_family == 'RedHat'"

We use the fact 'ansible_os_family' which contains the base type of the distribution used. Ubuntu is based on a Debian operating system, while CentOS is based on a RedHat operating system. Other possible values here would be "Suse" or "Gentoo", for example.

Let's run our playbook:

ansible-playbook -i inventory.txt setup-postgres.yml

The output should look like this:

PLAY [db] ********************************************************************************************************************************************************

TASK [Gathering Facts] **************************************************************************************************************************************************
ok: [ansible-guide-3]
ok: [ansible-guide-4]

TASK [install postgresql on debian based systems (Ubuntu)] **************************************************************************************************************
changed: [ansible-guide-3]
skipping: [ansible-guide-4]

TASK [install postgresql on Redhat based systems (CentOS)] **************************************************************************************************************
skipping: [ansible-guide-3]
changed: [ansible-guide-4]

PLAY RECAP **************************************************************************************************************************************************************
ansible-guide-3                  : ok=2    changed=1    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0 
ansible-guide-4                  : ok=2    changed=1    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0 

As we can see, the host for which the condition did not apply has now been skipped for both installation tasks. So we can make tasks dependent on the operating system used. Especially for environments with different distributions, this makes our life much easier!
Example 2: Restricting a task to a specific host

Sometimes we want to run a task in the playbook on a specific host only. Let's say we want the second web server to be our development and test system, so we want to create another user for the developer.

To do this, I'm going to expand the playbook from Part 4, where we installed and started the web server:

 - name: webserver install 
   hosts: webservers
   tasks: 
     - name: install apache2
       become: true
       ansible.builtin.apt:
         name: apache2
         state: present
         update_cache: yes
       become: true

    - name: enable and start apache2 systemd service
      become: true
      ansible.builtin.systemd:
        name: apache2
        enabled: true
        state: started
    
    - name: add dev user on second webserver
      become: true
      ansible.builtin.user: 
        name: herbert
        state: present
      when: "inventory_hostname == 'ansible-guide-2'"

Here we use the Ansible variable "inventory_hostname", which exists in every run (even with fact gathering disabled) and contains the current host name as defined in the inventory. Important: This does not have to be the actual hostname of the system. This is contained in the fact (gathering must be enabled) "ansible_hostname".

In the example playbook above, the task will only run if the name of the current host is exactly "ansible-guide-2".

Example 3: Run a task only if the host is a member of a particular group

If we want to run a play for a specific group, we define that using the "hosts" parameter in the playbook. But even if we run a play on all hosts, for example, we can make the execution of individual tasks dependent on group membership if we need to.

 - name: webserver install 
   hosts: all
   tasks: 
     - name: add default user to all systems
       become: true
       ansible.builtin.user:
         name: technik
         state: present
       become: true
    
    - name: add dbadmin user on db servers
      become: true
      ansible.builtin.user: 
        name: dbadmin
        state: present
      become: true
      when: "'db' in group_names"

In this example, we run the game on all the hosts in our inventory. The user 'technik' will be created on all systems. For the user 'dbadmin' we have defined a condition that checks if the string 'db' is in the 'group_names' list provided by Ansible. This is a list that exists for each host in the current run and contains the names of all groups that the host belongs to.

Conclusion

By combining facts and conditions, we can make our playbooks very flexible, allowing us to use Ansible in heterogeneous infrastructures, for example. With Ansible, there are many ways to get to the same goal, so it is important to get a feel for which way is best for your particular use case. For example, do I use one playbook and work with conditions, or do I break the tasks into separate playbooks?

In the rest of this guide, I will try to include best practices and my own experiences whenever possible.

In the next part, we will look at another control structure in Ansible called loops. Hopefully the gap between posts will be a little shorter this time.

Till then!

Mow

If you don't understand some of the points or if I didn't express myself clearly, please drop me an e-mail. I'll try to clear it up :)
What are conditionals?

Conditionals are conditions to which we can link the execution of tasks. For example, we can run a task only if the target host has a certain operating system installed. When we use conditionals, we use variables and facts to define them.
A first example

Let's start with a very simple example.

- hosts: ansible-guide-1
  vars:
    my_number: 6
  tasks:
    - name: task with condition
      ansible.builtin.debug:
        msg: "Variable is greater then 5!!"
      when: "my_number > 5"

Conditionals are defined in the When parameter. This is a task level parameter. The when parameter can then contain a single condition or a list of conditions. The conditions are checked before the task is executed. If they match, the task is executed; if they do not, it is skipped and given the status "skipped".

What does this mean for the example playbook above? We defined a variable "my_number" above that has a value of 6. Then we defined a task that has the following condition:

"when: my_number < 5"

So we want to run the task only if the value of the "my_number" variable is greater than 5. In this case, we want the task to run. Now let's run the playbook:

ansible-playbook -i inventory.txt simple-conditional.yml

PLAY [ansible-guide-1] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]

TASK [task mit condition] ****************************************************************************
ok: [ansible-guide-1] => {
    "msg": "Variable is greater than 5!!"
}

PLAY RECAP ****************************************************************************
ansible-guide-1                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 

As you can see, the task ran normally. Now let's define another task:

- hosts: ansible-guide-1
  vars:
    my_number: 6
  tasks:
    - name: task with condition
      ansible.builtin.debug:
        msg: "Variable is greater than 5!!"
      when: "my_number > 5"

    - name: another task with condition
      ansible.builtin.debug:
        msg: "Variable is 8!!"
      when: "my_number == 8"

ansible-playbook -i inventory.txt simple-conditional.yml

PLAY [ansible-guide-1] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]

TASK [task mit condition] ****************************************************************************
ok: [ansible-guide-1] => {
    "msg": "Variable is greater than 5!!"
}

TASK [weiterer task mit condition] ****************************************************************************
skipping: [ansible-guide-1]

PLAY RECAP ****************************************************************************
ansible-guide-1                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 

What happened now? Ansible ran our first task because its condition is true. In the second task, it checked the condition and determined that the value of the variable "my_number" is not 8, so the condition does not apply, and skipped the task. We can see this in the "skipping" output: [ansible-guide-1]"

Operators and Jinja2

We use different operators for the two conditionals: '>' and '=='. Conditionals in Ansible are based on the Jinja2 templating language. So we can use all the operators available in that language. An overview can be found here:

https://jinja.palletsprojects.com/en/3.0.x/templates/

We will be working with Jinja2 a lot more when we get to the more advanced parts of the guide.

Multiple conditionals

As mentioned above, the "when" parameter can contain either a single condition or a list. It is important to note that conditions specified in lists are always in an "AND" relationship with each other. In short, this means that each list item under "when" must be true for the task to be executed.

Let me give you a quick example:

- hosts: ansible-guide-1
  vars:
    my_number: 5
    my_text: Hello World
    my_other_text: Nothing.
  tasks:
    - name: task with condition
      ansible.builtin.debug:
        msg: "This task will be executed if all conditions are true"
      when:
        - "my_number == 5"
        - "'Hello' in my_text"
        - "my_other_text == 'Nothing.'"

ansible-playbook -i inventory.txt multi-conditionals.yml

PLAY [ansible-guide-1] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]

TASK [task with condition] ****************************************************************************
ok: [ansible-guide-1] => {
    "msg": "This task will be executed if all conditions are true"
}

PLAY RECAP ****************************************************************************
ansible-guide-1                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

As we can see, all three conditions are true and the task is executed. Let's take a quick look at the three conditions:

• "my_number == 5".

This is the same principle as the first two examples. The test is "if my_number is 5".

• "'Hello' in my_text"

Here we use the "in" operator to check if the substring "Hello" is in the string my_text. The "in" operator checks whether there is a subset of elements in a list. Since a string is nothing more than a list of characters, we can use this here.

• "my_other_text == 'Blubb.'"

The == operator can also be applied to strings. So we check "Is the variable my_other_text equal to 'Blubb. This is also true.

AND OPERATOR

In the example above, we define conditionals in a list, which implies an AND relationship. However, we can also define AND and OR operators in a single line. We could also define the task from "multi-conditionals.yml" this way:

- hosts: ansible-guide-1
  vars:
    my_number: 5
    my_text: Hello World
    my_other_text: Nothing.
  tasks:
    - name: task with condition
      ansible.builtin.debug:
        msg: "This task will be executed if all conditions are true"
      when:
        - "my_number == 5 and 'Hello' in my_text and my_other_text == 'Nothing.'"

If we run this now, we should get the same result as above.

AND and OR combined

Things get a little more complicated when we want to combine AND and OR:
and-or.yml

- hosts: ansible-guide-1
  vars:
    my_number: 5
    my_text: Hello World
    my_other_text: Nothing.
  tasks:
    - name: task with condition
      ansible.builtin.debug:
        msg: "This task will be executed if all conditions are true"
      when:
        - "my_text == 'Hello World'"
        - "my_number == 5 or my_number > 3"

So we have defined two conditionals in a list. As we have learned, both list items must be true at the end for the task to be performed. The above example can be rewritten as follows:

If my_text is 'Hello world' AND my_number is 5 or greater than 3.

If we now run the playbook, the task will be executed:

ansible-playbook -i inventory.txt and-or.yml

PLAY [ansible-guide-1] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansbible-guide-1]

TASK [task mit condition] ****************************************************************************
ok: [ansible-guide-1] => {
    "msg": "This task will be executed if all conditions are true"
}

PLAY RECAP ****************************************************************************
ansible-guide-1                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 

As expected, the task runs. Now let's verify this by setting the value of my_number to 2:

- hosts: ansible-guide-1
  vars:
    my_number: 2
    my_text: Hello World
    my_other_text: Nothing.
  tasks:
    - name: task mit condition
      ansible.builtin.debug:
        msg: "This task will be executed if all conditions are true"
      when:
        - "my_text == 'Hello World"
        - "my_number == 5 or my_number > 3"

ansible-playbook -i inventory.txt and-or.yml

PLAY [ansible-guide-1] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]

TASK [task with condition] ****************************************************************************
skipping: [ansible-guide-1]

PLAY RECAP ****************************************************************************
ansible-guide-1                  : ok=1    changed=0    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

Try it out!

The best thing to do is to try it out for yourself and vary the variable values as you wish.

Now that we've looked at how conditionals work in this part, I'd like to go through some practical use cases with you in the next part.

I hope you enjoyed it again and look forward to your feedback!

Regards.

Mow

the Ansible Starter 101 continues. We have already reached part 7, which deals with task return values.

Now you're probably asking yourself: What the hell are return values and why do I need them?

Briefly summarized: When a task is executed, it produces a return value that contains information about the task result. We always need return values when we want to continue working in a task with the result of a previous task.

An example

As always, I will illustrate this with a small example. Let's say we want to check if a certain file exists on the remote system. We can check this with the "stat" module:

- name: Example for return values
  hosts: webservers
  tasks:
    - name: check if hosts file is there
      ansible.builtin.stat:
        path: /etc/hosts

When we now run this playbook, the result is initially very unspectacular:

PLAY [Example for return values] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [check if file is there] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

PLAY RECAP ****************************************************************************
ansible-guide-1                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 
ansible-guide-2                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 

As we can see, both tasks worked and returned the status "ok". And what do we get? Nothing so far. The "stat" module only collects statistics on a file (or path) and would return "ok" even if the file did not exist.

If we want to use the information collected for this file, we need to use the return value of the task. To record this, there is the "register" task parameter:

- name: Example for return Values
  hosts: webservers
  tasks:
    - name: check if hosts file is there
      ansible.builtin.stat:
        path: /etc/hosts
      register: my_var_with_return_value

This tells Ansible to store the return value of the "check if hosts file is there" task in a variable called "my_var_with_return_value". Now, the return value of each module contains different fields. However, we can find them in the official Ansible documentation for each module. For the stat module it is here:

https://docs.ansible.com/ansible/devel/collections/ansible/builtin/stat_module.html

The return value is stored in a dictionary. We have not covered this in detail yet, but it should be enough for now. To check if our file exists, we do the following:

- name: Example for return Values
  hosts: webservers
  tasks:
    - name: check if hosts file is there
      ansible.builtin.stat:
        path: /etc/hosts
      register: my_var_with_return_value

    - name: debug output
      ansible.builtin.debug:
        msg: "File exists is: {{ my_var_with_return_value.stat.exists }}"

If we run this playbook, we will get the following output:

PLAY [Example for return values] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [check if hosts file is there] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [debug output] ****************************************************************************
ok: [ansible-guide-1] => {
    "msg": "File exists is: True"
}
ok: [ansible-guide-2] => {
    "msg": "File exists is: True"
}

PLAY RECAP ****************************************************************************
ansible-guide-1                  : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 
ansible-guide-2                  : ok=3    changed=0    unreachable=0    failed=0   2skipped=0    rescued=0    ignored=0 

The file “/etc/hosts” therefore exists on both of our test web servers.

Another example

In the same way, we could display the output of a shell command that we run through the "command" module:

- name: Example for return values
  hosts: ansible-guide-1
  tasks:
    - name: get os version
      ansible.builtin.command: "uname -a"
      register: my_var_with_return_value

    - name: debug output
      ansible.builtin.debug:
        msg: "{{ my_var_with_return_value.stdout }}"

PLAY [Beispiel mit Return Values] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]

TASK [get os version] ****************************************************************************
changed: [ansible-guide-1]

TASK [debug output] ****************************************************************************
ok: [ansible-guide-1] => {
    "msg": ""msg": "NAME=\"Ubuntu\"\nVERSION=\"20.04.2 LTS (Focal Fossa)\"\nID=ubuntu\nID_LIKE=debian\nPRETTY_NAME=\"Ubuntu 20.04.2 LTS\"\nVERSION_ID=\"20.04\"\nHOME_URL=\"https://www.ubuntu.com/\"\nSUPPORT_URL=\"https://help.ubuntu.com/\"\nBUG_REPORT_URL=\"https://bugs.launchpad.net/ubuntu/\"\nPRIVACY_POLICY_URL=\"https://www.ubuntu.com/legal/terms-and-policies/privacy-policy\"\nVERSION_CODENAME=focal\nUBUNTU_CODENAME=focal"
}

PLAY RECAP ****************************************************************************
localhost                  : ok=3    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 

So we run another task and store the return value in a variable using "register". Then we look at the structure of the return value:

https://docs.ansible.com/ansible/latest/collections/ansible/builtin/command_module.html

Under "Return Values" we see that there is the field "stdout", i.e. the standard output of the called shell command. We will output this field again with the "debug" module.

Standard fields

In addition to the module-specific fields, there are some standard fields in every return value dictionary. Here are some examples:

Modified: Contains information as a Boolean (true/false) whether the task has returned the status "changed".

skipped: Contains information about whether the task was skipped.

failed: Hopefully false. Contains information about whether the task failed.

The full list can be found here:

https://docs.ansible.com/ansible/2.5/reference_appendices/common_return_values.html

What comes next

In the next part I would like to show you conditionals, which are conditions we can link to the execution of our tasks.

Best wishes and see you soon!

Mow

You may have noticed this part at the beginning of every playbook run:

TASK [Gathering Facts] *****************************************************************************
ok: [ansible-guide-1]

This is a task that Ansible performs by default when fact collection is enabled. Facts are variables that Ansible automatically sets at the start of a playbook. They contain all sorts of information about the current play, its target systems and the current environment.

Here are a few examples:

ansible_hostname: contains the hostname of the current host as determined by Ansible

inventory_hostname: contains the hostname of the current host as defined in the inventory

ansible_default_ipv4.address: Contains the first primary IPv4 address found by Ansible.

ansible_distribution: Contains the name of the target host's OS distribution, e.g. 'Ubuntu', 'Debian' or 'Suse'.

We can display all available facts about a system with a small ad-hoc command:

ansible ansible-guide-1 -i inventory.txt -m setup

The output is a very large block in JSON (JavaScript Object Notation) format, which I will not include here for the sake of clarity. Try it out for yourself!

Enable/Disable Fact Gathering

By default fact gathering is enabled for each playbook. However it takes its time and can be disabled if you are not using any facts:

- hosts: all
  gather_facts: no   # <-- disable fact gathering
  tasks:
    - name: task 1
      ansible.builtin.debug:
        msg: "fact gathering is off"

My recommendation is to activate the fact collection only when we really need to access it. This can significantly reduce the runtime of a playbook.

Accessing facts in a playbook

Since facts are ultimately variables, accessing them is identical. For example, we can display the current distribution and OS family:

- hosts: all
  tasks:
    - name: print current distribution
      ansible.builtin.debug:
        msg: "My distribution is {{ ansible_distribution }}

    - name: print current os family
      ansible.builtin.debug:
        msg: "My os family is {{ ansible_os_family }}"

In addition to the facts provided by Ansible, we can also define our own. This is useful whenever we want to set our own variables at runtime.

In addition to the facts provided by Ansible, we can also define our own. This is always useful when we want to set our own variables at runtime.

We use the set_fact module to do this:

- hosts: ansible-guide-1
  gather_facts: true
  tasks:
    - name: set facts
      ansible.builtin.set_fact:
        my_custom_fact_1: "First fact set at runtime"
        my_custom_fact_2: "Second fact set at runtime"
        another_custom_fact: "Hello World"

    - name: Output
      ansible.builtin.debug:
        msg: "{{ my_custom_fact_1 }}"

We can use the "set_fact" module to manually define one or more facts. When defining, we can also access facts or variables again:

- hosts: ansible-guide-1
  gather_facts: true
  tasks:
    - name: set facts
      ansible.builtin.set_fact:
        my_custom_fact: "My Distribution: {% raw %}{{ ansible_distribution }}{% endraw %}"

    - name: Output
      ansible.builtin.debug:
        msg: "{{ my_custom_fact }}"

PLAY [localhost] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]

TASK [set facts] ****************************************************************************
ok: [ansible-guide-1]

TASK [Output] ****************************************************************************
ok: [ok: [ansible-guide-1]] => {
    "msg": "My Distirubtion: Ubuntu"
}

PLAY RECAP ****************************************************************************
ok: [ansible-guide-1]                  : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

The facts defined with the "set_fact" module are only available AFTER the task has been executed. This means that we cannot access facts defined in the same task:

- hosts: ansible-guide-1
  tasks:
    - name: This is NOT working!
      ansible.builtin.set_fact:
        fact_1: "I am fact_1"
        fact_2: "fact_1: {{ fact_1 }}"

PLAY [ansible-guide-1] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]

TASK [This is NOT working!] ****************************************************************************
fatal: [ansible-guide-1]: FAILED! => {"msg": "The task includes an option with an undefined variable. The error was: 'fact_1' is undefined\n\nThe error appears to be in '/home/sseibold/blog/facts.yml': line 5, column 7, but may\nbe elsewhere in the file depending on the exact syntax problem.\n\nThe offending line appears to be:\n\n  tasks:\n    - name: Das hier funktioniert NICHT!\n      ^ here\n"}

PLAY RECAP ****************************************************************************
ansible-guide-1                  : ok=1    changed=0    unreachable=0    failed=1    skipped=0    rescued=0    ignored=0

The task fails because the fact_1 variable is not yet available. This is only the case after the task is run. So the playbook should look like this:

- hosts: ansible-guide-1
  tasks:
    - name: This works!
      ansible.builtin.set_fact:
        fact_1: "I am fact_1"

    - name: fact_2 in new Task
      ansible.builtin.set_fact:
        fact_2: "fact_1: {% raw %}{{ fact_1 }}"

    - name: Output
      ansible.builtin.debug:
        msg: "{% raw %}{{ fact_2 }}{% endraw %}"

PLAY [ansible-guide-1] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]

TASK [Das hier funktioniert] ****************************************************************************
ok: [ansible-guide-1]

TASK [fact_2 in neuem Task definieren] ****************************************************************************
ok: [ansible-guide-1]

TASK [Ausgabe] ****************************************************************************
ok: [ansible-guide-1] => {
    "msg": "fact_1 lautet: ich bin fact_1"
}

PLAY RECAP ****************************************************************************
ansible-guide-1                  : ok=4    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0  

Now that the fact "fact_1" has been defined in a previous task, we can access it in the next task.

Conclusion

This brings us to the end of this short chapter in which we have learned what facts are and how to access them. We will be using facts a lot in practical examples throughout this guide.

What happens next?

In the next part of this series, we will look at return values. As always, I hope this guide has been helpful to you so far.

I would love to hear your feedback. Just leave a comment here or send me an email!

See you soon!

Mow

The simplest use of variables is to store multiple values (such as file paths) in one variable.

Let's start with an example. Let's say we want to serve an index.html and a style.css to our web server. For the sake of clarity, I'm going to put the whole thing in its own playbook. You can also just extend the webservers.yml from the last part.

- name: Play without variables
  hosts: webservers
  tasks:
    - name: copy index.html
      ansible.builtin.copy: 
        src: files/index.hmlt
        dest: /var/www/html/index.html
      become: true
      
   - name: copy style.css
     ansible.builtin.copy:
       src: files/style.css
       dest: /var/www/html/style.css
     become: true

The further we build our playbook, the more we will need to use the "/var/www/html" path. It would be great if we could just put this in a variable. So let's do that:

- name: Play with variable
  hosts: webservers
  vars:
    my_docroot: /var/www/html 
  tasks:
    - name: copy index.html
      ansible.builtin.copy: 
        src: files/index.hmlt
        dest: "{{ my_docroot }}/index.html"
      become: true
      
   - name: copy style.css
     ansible.builtin.copy:
       src: files/style.css
       dest: "{{ my_docroot }}/style.css"
     become: true

This is the simplest definition of a variable. We have simply defined the variable "my_docroot" in the playbook and can now access it throughout the whole "Playing with Variables" piece. To use variables we use the following format:

"{{ variable_name }}"

It is important to note that we must enclose the entire string in quotes ("). Variables can also be defined at task level. This would look like this:

- name: Play mit Variablen auf Taskebene
  hosts: webservers
  tasks:
    - name: copy index.html
      ansible.builtin.copy: 
        src: files/index.html
        dest: "{{ my_docroot }}/index.html"
      become: true
      vars:
        my_docroot: /var/www/html
      
   - name: copy style.css
     ansible.builtin.copy:
       src: files/style.css
       dest: "{{ my_docroot }}/style.css"
     become: true
     vars:     
       my_docroot: /var/www/html

However, this only makes sense in very special cases, when only one specific task actually requires that variable.

In the examples above, we use a variable of type "string", which is a simple string of characters. However, there are other types of variables that we will discuss in more detail later in this guide.

Variable types

# Strings 
my_string: Hello World!

# Numbers
number_of_files: 8

# Float - we always use this when floating point numbers are involved
my_float: 2.5

# Lists - Lists containing one or more entries
files_to_copy:
  - /path/to/file1.txt
  - /path/to/file2.txt

# Dictionary - List with structured data
files_to_copy:
  - name: first file
    path: /path/to/file1.txt
    copy_to: /new/file/path1.txt
  - name: second file
    path: /path/to/file2.txt
    copy_to: /new/file/path2.txt

# Boolean - True ore False
enable_service: true
overwrite_config: false
    

Host and Group Variables

The variable defined in the first example now applies to all hosts with the same value. But what do we do if we want to define different values for each host? Let's return to our example scenario. Let's assume that the content of index.html of our two web servers should be different for each host, so that the first one outputs "I am webserver1" and the second one outputs "I am webserver2".

To do this, we use host variables (host_vars). To use them, we create a new directory in our example setup:

cd ~/ansible-guide
mkdir -p host_vars/ansible-guide-1
mkdir -p host_vars/ansible-guide-2

In each of the created directories we add a file "main.yml".

my_welcome_text: I am webserver 1

my_welcome_text: I am webserver 2

When we start our playbook, Ansible will automatically read all the files under "host_vars" and assign the variable values to the appropriate hosts. It is important that the names of the directories match the names of the hosts in our inventory.

To test this, we need to make a small adjustment to our web server playbook. Using the "copy" module, we can define the desired contents of the target file directly, instead of using a source file. It will then look like this:

- name: webserver setup
  hosts: webservers
  tasks:
    - name: Apache2 Setup
      ansible.builtin.apt:
        name: apache2
        state: present
        update_cache: true
      become: true

    - name: start and enable apache2
      ansible.builtin.systemd:
        name: apache2
        state: started
        enabled: true
      become: true

    - name: copy index.html
      ansible.builtin.copy:
        dest: /var/www/html/index.html
        content: "{{ my_welcome_text }}"
      become: true

    - name: copy apache2.conf
      ansible.builtin.copy:
        src: files/apache2.conf
        dest: /etc/apache2/apache2.conf
      become: true

Notice the change in the "copy index.html" task. Instead of defining a source file for the copy module, we enter the desired content of the target file directly, using our variable "my_welcome_text".

Then let's run the playbook:

cd ~/ansible-guide
ansible-playbook -i inventory.txt webservers.yml

PLAY [webserver setup] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [Apache2 Setup] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [start and enable apache2] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [copy index.html] ****************************************************************************
changed: [ansible-guide-1]
changed: [ansible-guide-2]

PLAY RECAP ****************************************************************************
ansible-guide-1          : ok=4    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
ansible-guide-2          : ok=4    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

The "copy index.html" task now has the status "modified" on both hosts, and has thus adopted the new content for index.html. We can now check again with curl or the browser to see if we have achieved the desired effect:

curl http://192.168.0.11
<h1>I am webserver1!</h1>

curl http://192.168.0.12
<h1>I am webserver2!</h1>

BAM! Looks good! So we successfully used host-specific variables.

The whole thing works with groups as well. For this we use group_vars. We also create a new playbook for this and use the useful debug module to test the variables.

In part 4 of this guide, we created an inventory with two different groups, "webservers" and "db". So we will create a playbook that uses exactly those two.

- name: group_vars showcase
  hosts:
    - webservers
    - db
  tasks:
    - name: Debug Ausgabe
      debug:
        msg: "{{ test_text }}"

The debug module is very useful when we are creating playbooks and want to test them in between. For example, we can use it to display the values of variables. In our case, we define a parameter for the module:

msg: Any string that will be output during the play.

Now we just need to define the variable "test_text". Differently for each group. We create another directory on the same level as "host_vars":

mkdir ~/ansible-guide/group_vars
mkdir ~/ansible-guide/group_vars/webservers
mkdir ~/ansible-guide/group_vars/db

In both directories we add a "main.yml":

test_text: I am a host in the group 'webservers'!

test_text: I am a host in the group 'db'

So we have done the same as with the host_vars, only this time at group level. Now let's run the new playbook:

cd ~/ansible-guide
ansible-playbook -i inventory.txt groupvars-test.yml

ASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]
ok: [ansible-guide-3]

TASK [Debug Ausgabe] ****************************************************************************
ok: [ansible-guide-1] => {
    "msg": "I am a host in the group 'webservers'!"
}
ok: [ansible-guide-2] => {
    "msg": "I am a host in the group 'webservers'!"
}
ok: [ansible-guide-3] => {
    "msg": "I am a host in the group 'db'!"
}
PLAY RECAP ****************************************************************************
ansible-guide-1                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
ansible-guide-2                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
ansible-guide-3                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

As we can see above, each of the three hosts now pulls the group-specific variable "test_text" and outputs it accordingly.

Summary

In this chapter you have learned what variables are and how we can define them in different places. In the next chapter I will introduce you to facts. These are very similar to variables, but there are some differences!

See you then!

Mow

Playbooks

We can use playbooks to define reusable Ansible code. A playbook consists of one or more plays. For example, we could use a playbook called "webserver.yml" to manage our web servers.

Let's try to learn the structure of a playbook using the following example:

- name: webserver install 
  hosts: webservers
  tasks: 
    - name: install apache2
      ansible.builtin.apt:
        name: apache2
        state: present
        update_cache: yes
      become: true

    - name: enable and start apache2 systemd service
      ansible.builtin.systemd:
        name: apache2
        enabled: true
        state: started

Let's investigate this line by line!

Line 1 - name

A descriptive name for the play can be assigned in the ‘name’ field in line 1. This parameter is optional, but I recommend naming each play as meaningfully as possible.

Line 2 - hosts

In line 2, we define the target systems for this play with the ‘hosts’ field. We have several options here:

Group(s)
We can define one or more groups from our inventory as a target:

- name: Play for hosts in one group
  hosts: Group1
  tasks:
    - name: Example Task 1
      ansible.builtin.apt:
        name: apache2
        state: present

- name: Play for two groups
  hosts: 
    - Group1
    - Group2
  tasks:
    - name: Example Task 1
      ansible.builtin.apt:
        name: apache2
        state: present

Hosts

Alternatively, we can also specify the hosts from the inventory directly as the target:

- name: Play for one host
  hosts: webserver1
  tasks:
    - name: Example Task 1
      ansible.builtin.apt:
        name: apache2
        state: present

- name: Play for two hosts
  hosts: 
    - webserver1
    - webserver2
  tasks:
    - name: Example Task 1
      ansible.builtin.apt:
        name: apache2
        state: present

There are a few other options in this section that we can use to influence the target list. For example, we can exclude individual hosts or groups from the target definition. More on this in a later article.

Line 3 - Begin of task definitions

This is where the list of individual tasks for this play begins. Lets see how a task is build in Ansible.

Lines 4 to 9 - Task definition

This brings us to the structure of a task. Note the indentation of each element. We distinguish between parameters that belong to the task and parameters that belong to the module.

The 'name' field (line 4) is optional, as with Play, but highly recommended, as it will also appear later in the output. After all, we want to know what is happening. Line 5 is the name of the module we want to use. In this case we want to use the 'apt' module to install a package. Everything that appears one indent further down is a module-level parameter, i.e. it refers to the module, not the task itself. This is where many people get confused.

Task parameters are parameters that affect the task itself, i.e. they can be defined for each task. Module parameters, on the other hand, are different for each module. For example, the Copy module needs information about the source and destination paths, while the 'apt' module needs the name of the package to be installed.

In our example, we use the 'apt' module to install Apache2 with the following parameters

• name: name of the package to install
• state: target state:
  • present = installed
  • absent = uninstalled
  • latest = always keep on latest version
• update_cache: forces to package cache to be updated beforehand

Line 9 contains the definition of another task level parameter (note the indentation). With 'become: true' we basically specify that superuser privileges are required to run this task. We will need this parameter very often, so I will devote a separate part of this series to it.

A note on module parameters

It is important to note that there are some module parameters that are optional and some that must be specified. However, the Ansible documentation is very helpful here. For our example, we can find the information on these pages:

Documentation for apt module

ansible.builtin.apt module – Manages apt-packages — Ansible Community Documentation

Documentation for systemd module

ansible.builtin.systemd module — Ansible Community Documentation

Example

Let us now apply what we have learned to our example scenario. Let's assume that our first two hosts are web servers and the third is a database host.

We will therefore adapt our inventory.txt accordingly:

~/ansible-guide/inventory.txt

[webservers]
ansible-guide-1 ansible_ssh_user=ansible ansible_host=192.168.0.11
ansible-guide-2 ansible_ssh_user=ansible ansible_host=192.168.0.12

[db]
ansible-guide-3 ansible_ssh_user=ansible ansible_host=192.168.0.13

I would now like to divide the setup into two playbooks. Depending on your own preferences and use case, we could also define two plays within one playbook.

Playbook 1: ~/ansible-guide/webservers.yml

- name: webserver setup
  hosts: webservers
  tasks:
    - name: Apache2 Setup
      ansible.builtin.apt:
        name: apache2
        state: present
        update_cache: true
      become: true

    - name: start and enable apache2
      ansible.builtin.systemd:
        name: apache2
        state: started
        enabled: true
      become: true

Now we can run the playbooks:

cd ~/ansible-guide
ansible-playbook -i inventory.txt webservers.yml

PLAY [webserver setup] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [Apache2 Setup] ****************************************************************************
changed: [ansible-guide-1]
changed: [ansible-guide-2]

TASK [start and enable apache2] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]


PLAY RECAP ****************************************************************************
ansible-guide-1                  : ok=3    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 
ansible-guide-2                  : ok=3    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 

It is interesting to note that the task 'start and enable apache2' returns the status 'ok' and not 'changed' as expected. This is because enabling and starting the service is already defined in the installation package. So there is nothing for Ansible to do at this point.

Now we can quickly test that our installation has worked by entering one of the IP addresses in a browser. We should now see the default Apache web server page.

Playbook 2: ~/ansible-guide/database.yml

- name: database setup
  hosts: db
  tasks:
    - name: MySQL Setup
      ansible.builtin.apt:
        name: mysql-server
        state: present
        update_cache: true
      become: true

    - name: start and enable MySQL
      ansible.builtin.systemd:
        name: mysql
        state: started
        enabled: true
      become: true

We now do the same with the database server playbook:

cd ~/ansible-guide
ansible-playbook -i inventory.txt database.yml

PLAY [database setup] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-3]

TASK [MySQL Setup] ****************************************************************************
changed: [ansible-guide-3]

TASK [start and enable MySQL] ****************************************************************************
ok: [ansible-guide-3]

PLAY RECAP ****************************************************************************
ansible-guide-3                 : ok=3    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

Deploy customized index.html

We have now done a standard installation of Apache2 and MySQL using Ansible. In the next step, I will show you how we can deploy our own index.html file, for example.

To do this, we will first create the file locally on the Ansible controller:

cd ~/ansible-guide
mkdir files
echo "<h1>My own index.html!</h1>" > files/index.html 

This results in the following file content:

<h1>My own index.html!</h1>

Now we add a task to our webservers.yml playbook:

- name: webserver setup
  hosts: webservers
  tasks:
    - name: Apache2 Setup
      ansible.builtin.apt:
        name: apache2
        state: present
        update_cache: true
      become: true

    - name: start and enable apache2
      ansible.builtin.systemd:
        name: apache2
        state: started
        enabled: true
      become: true

    - name: copy index.html
      ansible.builtin.copy:
        src: files/index.html
        dest: /var/www/html/index.html
      become: true

We are using the Ansible 'copy' module here. This can be used to copy files from the Ansible controller to the target systems. We give the module 2 parameters:

src: Source file path on the Ansible controller
dest: destination path on the remote hosts

We also tell Ansible again with 'become: true' that root permissions are required for this process.

We now run the updated playbook:

ansible-playbook -i inventory.txt webservers.yml

LAY [webserver setup] ****************************************************************************

TASK [Gathering Facts] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [Apache2 Setup] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [start and enable apache2] ****************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [copy index.html] ****************************************************************************
changed: [ansible-guide-1]
changed: [ansible-guide-2]

PLAY RECAP ****************************************************************************
ansible-guide-1                  : ok=4    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
ansible-guide-2                  : ok=4    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

Let's check that with curl:

apt install -y curl
curl http://192.168.0.11

<h1>My own index.html!</h1>

Handlers

We have now installed our web server and a database. We have also uploaded our own content to our web server. Finally , I would like to show you how we can also manage the Apache configuration file using Ansible. We want to notify the
web server when changes are made to it (and only then!). For this
handlers.

So we store the Apache configuration on the
Ansible controller. To do this, I simply copied the contents of /etc/apache2 from one of the test hosts
I simply copied the contents of /etc/apache2/apache2.conf from one of the test hosts and trimmed the
comment lines a little to make the whole thing a little more
clearer.

We put it back in our files subdirectory:

~/ansible-guide/files/apache2.conf

DefaultRuntimeDir ${APACHE_RUN_DIR}
PidFile ${APACHE_PID_FILE}

Timeout 300
KeepAlive On
MaxKeepAliveRequests 100
KeepAliveTimeout 5
User ${APACHE_RUN_USER}
Group ${APACHE_RUN_GROUP}

HostnameLookups Off

ErrorLog ${APACHE_LOG_DIR}/error.log
LogLevel warn

IncludeOptional mods-enabled/*.load
IncludeOptional mods-enabled/*.conf

Include ports.conf

<Directory />
	Options FollowSymLinks
	AllowOverride None
	Require all denied
</Directory>

<Directory /usr/share>
	AllowOverride None
	Require all granted
</Directory>

<Directory /var/www/>
	Options Indexes FollowSymLinks
	AllowOverride None
	Require all granted
</Directory>

AccessFileName .htaccess

<FilesMatch "^\.ht">
	Require all denied
</FilesMatch>

LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined
LogFormat "%h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" combined
LogFormat "%h %l %u %t \"%r\" %>s %O" common
LogFormat "%{Referer}i -> %U" referer
LogFormat "%{User-agent}i" agent

IncludeOptional conf-enabled/*.conf
IncludeOptional sites-enabled/*.conf

We extend our playbook with another task:

~/ansible-guide/webservers.yml

- name: webserver setup
  hosts: webservers
  tasks:
    - name: Apache2 Setup
      ansible.builtin.apt:
        name: apache2
        state: present
        update_cache: true
      become: true

    - name: start and enable apache2
      ansible.builtin.systemd:
        name: apache2
        state: started
        enabled: true
      become: true

    - name: copy index.html
      ansible.builtin.copy:
        src: files/index.html
        dest: /var/www/html/index.html
      become: true

    - name: copy apache2.conf
      ansible.builtin.copy:
        src: files/apache2.conf
        dest: /etc/apache2/apache2.conf
      become: true

If we were to run the whole thing again now, Ansible would copy both apache2.conf and index.html to the target systems. However, we also want to implement the automatic restart of the Apache service when changes are made. So we will add a handler and call it directly in the new task. I have added comments to the most important lines:

- name: webserver setup
  hosts: webservers
  handlers:                     
    - name: restart-apache      
      ansible.builtin.systemd:
        name: apache2
        state: restarted
      become: true
  tasks:
    - name: Apache2 Setup
      ansible.builtin.apt:
        name: apache2
        state: present
        update_cache: true
      become: true

    - name: start and enable apache2
      ansible.builtin.systemd:
        name: apache2
        state: started
        enabled: true
      become: true

    - name: copy index.html
      ansible.builtin.copy:
        src: files/index.html
        dest: /var/www/html/index.html
      become: true

    - name: copy apache2.conf
      ansible.builtin.copy:
        src: files/apache2.conf
        dest: /etc/apache2/apache2.conf
      notify: restart-apache                 
      become: true

We have now created another list on the same level as "Tasks". This contains our handler definitions. A handler has exactly the same structure as a task, but is not automatically executed when the playbook is called. This only happens if at least two things are specified:

• A task has the name of our handler - here "restart-apache" - defined in the "notify" parameter.
• At least one task that fulfills point 1 returns the status "changed". Only then will the handlers be executed.

Now we run the playbook again:

ansible-playbook -i inventory.txt webserver.yml

PLAY [webserver setup] ***********************************************************************************

TASK [Gathering Facts] ***********************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [Apache2 Setup] ***********************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [start and enable apache2] ***********************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [copy index.html] ***********************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]

TASK [copy apache2.conf] ***********************************************************************************
changed: [ansible-guide-1]
changed: [ansible-guide-2]

RUNNING HANDLER [restart-apache] ***********************************************************************************
changed: [ansible-guide-1]
changed: [ansible-guide-2]

PLAY RECAP ***********************************************************************************
ansible-guide-1                  : ok=6    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 
ansible-guide-2                  : ok=6    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 

The apache2.conf is now also managed by Ansible and the service will be restarted if necessary! Try this out a few more times by changing some parameters in the configuration and running the playbook.

Important note about handlers

As you can see in the output above, handlers are always executed at the end of the play and not immediately after the calling task. This ensures that, for example, the Apache restart is only executed once, even if multiple tasks make changes and call the handler.

If you want to explicitly restart at this point, you must define the restart as a task.

That's it for now!

In the next part I will show you how to put values into variables and where you can define them. I will also introduce you to some other useful modules!

From my own experience, I can strongly recommend that you just try it all out for yourself and try to apply what you have learned to your own use cases. It's the best way to learn :)

As always, I welcome feedback and suggestions for improvement. Feel free to use the comment function here or send an email to: dermow@posteo.de.

Have fun trying it out!

Mow

My example setup

To illustrate this part with practical examples, I have set up a small test scenario. This will remain basically the same for the rest of the guide, but will be expanded to include additional hosts.

If you feel like it, feel free to create a similar scenario and just try out the examples.

Let's start with this:

My laptop running Ubuntu Desktop 20.04 LTS and Ansible version 2.9.6 as the Ansible controller.

Three VMs running Ubuntu Server 20.04 LTS as targets:
    ansible-guide-1 (192.168.0.11)
    ansible-guide-2 (192.168.0.12)
    ansible-guide-3 (192.168.0.13)

The target user for all three hosts is 'ansible'. This user has full sudo privileges, i.e. is not a root user itself, but can execute commands with root privileges using the 'sudo' command, short for 'super user do'. Ansible also uses this mechanism. But more on that in a moment.

Setting up SSH public key authentication

In theory, Ansible can do password authentication, but this is not really useful and is also very time consuming for a certain number of target hosts. The easiest and most secure option is to use SSH keys. We create a key pair consisting of a private and a public key, and store the public part (public key) on the target systems.

We store the private key securely on our client.

Assuming that SSH key authentication has not yet been set up, but is done using a password, the following steps need to be taken:

Create a key pair on the local client

ssh-keygen -t rsa -b 4096

the output will look similar to this:

Generating a public/private rsa key pair.
Specify the file to store the key in (/home/mow/.ssh/id_rsa): /home/mow/.ssh/id_rsa
Enter the passphrase (empty for no passphrase):
Enter the same passphrase again:
Your identification is stored in /home/mow/.ssh/id_rsa
Your public key is stored in /home/mow/.ssh/id_rsa.pub
The key fingerprint is
SHA256:uIRqKu6ySijEPaHeNrkNJrs/PmzTH6T+0+WB9F+GKek mow@ubuntu1
The random image of the key is
+---[RSA 4096]----+
| |
| |
| . |
|. o .. . . |
| + o. o.S o . o |
|+ ..o.o. . * o o |
|o++B..... + + o |
|=o=**. ... E . |
|X*=++ooo. |
-—[SHA256]--—+

What have we done? We have created a new SSH key pair. This is of the RSA type (-b rsa) and 4096 bytes long (-b 4096).

Important: For keys used in a production environment, I strongly recommend using a passphrase, as a potential attacker cannot do anything with the private key alone. However, this is not absolutely necessary for this guide.

Now that we are the proud owners of a freshly printed SSH key pair, we want to store the public part of it, i.e. the public key, on the target systems. A useful tool for this is 'ssh-copy-id'.

We run the following command on our Ansible controller

ssh-copy-id -i ~/.ssh/id_rsa ansible@ansible-guide-1

We will then be prompted for the password of the target user. The public key is then stored on the target system. Of course, we repeat this process for the rest of the systems.

If everything has worked, we should be able to connect to the target systems without a password:

ssh ansible@ansible-guide-1
ssh ansible@ansible-guide-2
ssh ansible@ansible-guide-3

And now we're ready to start using Ansible!

Creating a project directory and inventory

Let's start with a project directory and an inventory. Although we could start with the default inventory (/etc/ansible/hosts) and any directory, I always recommend using a separate directory for each Ansible project.

So first we create the project directory:

Create a directory in your home

mkdir ~/ansible-guide

Then create a file in ~/ansible-guide/inventory.txt with the following content

[guide]
ansible-guide-1 ansible_ssh_user=ansible ansible_host=192.168.0.11
ansible-guide-2 ansible_ssh_user=ansible ansible_host=192.168.0.12
ansible-guide-3 ansible_ssh_user=ansible ansible_host=192.168.0.13

In this case we have created an inventory with a 'guide' group. This contains our 3 test hosts. With 'ansible_ssh_user=ansible' we specify the user to use for the SSH connection.

If the hostnames cannot be resolved to IPs via DNS, we use 'ansible_host=***' to specify the target IPs of the hosts.

This can all be done a bit more easily, but should be enough for now. After all, we still want to go into detail about inventories!

AdHoc commands

A term I unfortunately forgot to mention in the first article. So I'll make up for it here:

AdHoc commands can be used to perform specific tasks with Ansible at the command line level. They are very easy to use and are especially useful when you need to do something quickly on multiple hosts at once.

Although I always recommend using reusable playbooks for smaller tasks, the AdHoc commands are very useful for initial Ansible testing.

So let's see if we have our SSH connection configured correctly. Ansible has a ping module for this:

# Syntax
# ansible <hosts> -i <inventory> -m <modul>
cd ~/ansible-guide

ansible guide -i inventory.txt -m ping

If all went well, the output should look something like this

ansible-guide-1 | SUCCESS => {
ansible_facts": {
'discovered_interpreter_python": '/usr/bin/python'
},
'changed': false,
'ping': 'pong'
}
ansible-guide-2 | SUCCESS => {
'ansible_facts': {
'discovered_interpreter_python': '/usr/bin/python'
},
'changed': false,
'ping': 'pong'
}
ansible-guide-3 | SUCCESS => {
'ansible_facts': {
'discovered_interpreter_python': '/usr/bin/python'
},
'changed': false,
'ping': 'pong'
}

Perfect, we can now manage our three systems with Ansible!

With another ad hoc command, we could now display information about the operating system, for example:

# Syntax ansible <hosts> -i <inventory> -m <modul> -a <parameter>

ansible guide -i inventory.txt -m command -a "cat /etc/os-release"

So we run Ansible again with our 'guide' group, this time using the 'command' module and giving it the parameter 'cat /etc/os-release'.

The output should look something like this:

ansible-guide-1 | CHANGED | rc=0 >>
NAME="Ubuntu"
VERSION="20.04.1 LTS (Focal Fossa)"
ID=ubuntu
ID_LIKE=debian
PRETTY_NAME="Ubuntu 20.04.1 LTS"
VERSION_ID="20.04"
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
VERSION_CODENAME=focal
UBUNTU_CODENAME=focal

ansible-guide-2 | CHANGED | rc=0 >>
NAME="Ubuntu"
VERSION="20.04.1 LTS (Focal Fossa)"
ID=ubuntu
ID_LIKE=debian
PRETTY_NAME="Ubuntu 20.04.1 LTS"
VERSION_ID="20.04"
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
VERSION_CODENAME=focal
UBUNTU_CODENAME=focal

ansible-guide-3 | CHANGED | rc=0 >>
NAME="Ubuntu"
VERSION="20.04.1 LTS (Focal Fossa)"
ID=ubuntu
ID_LIKE=debian
PRETTY_NAME="Ubuntu 20.04.1 LTS"
VERSION_ID="20.04"
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
VERSION_CODENAME=focal
UBUNTU_CODENAME=focal

Our first playbook!

Now it's time to create our first playbook. Let's say we want to install the 'htop' package on all three systems. I will only say a few words about the contents here, as we will go into more detail about playbooks in the next articles.

Our simple playbook looks like this

# /home/mow/ansible-guide/playbook-htop.yml
- hosts: guide
  tasks:                     
    - name: install htop 
      become: true 
      ansible.builtin.apt: 
        name: htop 
        state: present

To run the whole thing, we need another command:

ansible-playbook -i inventory.txt playbook-htop.yml

And this is what the output looks like:

PLAY [guide] **************************************************************************************************************************************************************************************************

TASK [Gathering Facts] ********************************************************************************************************************************************************************************************
ok: [ansible-guide-1]
ok: [ansible-guide-2]
ok: [ansible-guide-3]

TASK [install htop] ***********************************************************************************************************************************************************************************************
changed: [ansible-guide-1]
changed: [ansible-guide-2]
changed: [ansible-guide-3]
]
PLAY RECAP ********************************************************************************************************************************************************************************************************
ansible-guide-1                  : ok=2    changed=1    unreachable=0 failed=0    skipped=0    rescued=0    ignored=0
ansible-guide-2                  : ok=2    changed=1    unreachable=0 failed=0    skipped=0    rescued=0    ignored=0 
ansible-guide-3                  : ok=2    changed=1    unreachable=0  failed=0    skipped=0    rescued=0    ignored=0

Task states

To conclude this section, I would like to briefly discuss some of the states a task can take. You may have noticed that some of our tasks return 'ok' and others return 'changed'.

A task will always return 'ok' if Ansible did not need to make any changes to create the target state. Of course, the opposite is true for the 'changed' state.

But wait a minute! What bullshit is this guy talking? In the example, we did a 'cat /etc/os-relase', so we are just printing the contents of a file. So why does the task say 'modified'?

This is because the 'command' module does nothing more than blatantly execute a shell command. Since Ansible has no way of 'knowing' what this does in turn (it could be a script or something else), it automatically assumes a change.

Hence, an important tip that you will hear from me many times:

Use the command (or shell) module ONLY IF YOU REALLY HAVE TO! Whenever possible, we should try to use modules where Ansible can track changes. This way we can always track the state of our environment, even with more complex playbooks.

There are other states besides ok and modified, but we will look at these in more detail in due course.

Thats it for now!

Mow