You can think of `ansible` as a more easier and human-readable bash scripts that can run on almost any remote machine (E.g. GNU/Linux, network router/switch, Windows...).
__It can do anything__ that can be done via terminal, but more reliably and on many different hosts (for instance - with different OS).
## Terminology
- __Control node__ - machine which will run ansible
- __Inventory__ - list of remote host, can be devided to groups.
- __Fact__ - info about remote host.
- __"Gather Facts"__ - automatic procces that gathers all info about system to use in tasks.
- __Task__ - script.
- __Playbook__ - main script __file__.
- __Handler__ - operation that run when task successfully changed configuration (e.g. reload nginx service if config changed)
- __Role__ - profile which contains scripts and files for host group
### Roles structure
```sh
./roles
└── [RoleName]
├── defaults
│ └── main.yml
├── files
├── handlers
│ └── main.yml
├── meta
│ └── main.yml
├── README.md
├── tasks
│ └── main.yml
├── templates
├── tests
│ ├── inventory
│ └── test.yml
└── vars
└── main.yml
```
-`defaults` - Folder to store files with variables with default values
-`files` - Folder to store static files (e.g. `index.html`)
-`handlers` - Folder for handlers
-`meta` - Folder for role metadata (information about authors, licenses, compatibilities, and dependencies). If the current role relies on another role, that gets declared in a meta folder.
-`README.md` - Documentation (Info about role)
-`tasks` - Folder for tasks, you can create other tasks in this folder e.g. `configure_NGINX.yml`
-`templates` - Folder to store dynamic files, that Ansible will edit based on facts and variables. Uses template enigne `Jinja2` and thus files in this folder should end with `.j2` extension (e.g. `nginx.conf.j2`)
-`tests` - Folder contains test environment with `inventory.ini` and `playbook.yml` to test role. Primarily used in CI, you probably won't need it in the begining
-`vars` - Folder for files with variables
## Guide
In this example we have x2 GNU/Linux (Debian) PCs and 1 vyOS router
Task: dump config of a router and write role for PCs which will:
- Install browser if it isn't installed
- Write its version in terminal during run of Ansible
As you can see, we have `UNREACHABLE!` host - it's router and we can't access it because it doesn't have SSH user `casual`. We have 3 ways for fixing it:
+ per cli run - `ansible all -m ping -i inventory.ini --user TARGETUSER --ask-pass `
+ per host - edit `inventory.ini`:
```yaml
[PCs] # host group name
192.168.0.11 #debian11
192.168.0.5 #debian12
[routers]
192.168.0.13 ansible_user=vyos #we set SSH access user to "vyos" vyOS 1.5
```
+ per hosts group/all hosts - edit `inventory.ini`:
```yaml
[PCs] # host group name
192.168.0.11 #debian11
192.168.0.5 #debian12
[routers]
192.168.0.13 #vyOS 1.5
[routers:vars]
ansible_user=vyos #SSH user to connect
[all:vars]
ansible_user=ssh_connect_user #SSH user to connect
As you can see, we have error "Connection type ssh is not valid for this module". The thing about this, we interact via SSH with router (not normal bash shell) and should inform about this ansible - `inventory.ini`:
```yaml
...
[routers:vars]
ansible_user=vyos
ansible_network_os=vyos # router OS
ansible_connection=network_cli # we inform that it's not regular bash shell
TASK [web-browser : Check if browser is installed] ******************************************
ok: [192.168.0.11]
fatal: [192.168.0.5]: FAILED! => {"cache_update_time": 1717928756, "cache_updated": false, "changed": false, "msg": "'/usr/bin/apt-get -y -o \"Dpkg::Options::=--force-confdef\" -o \"Dpkg::Options::=--force-confold\" install 'firefox-esr=115.11.0esr-1~deb12u1'' failed: E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)\nE: Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), are you root?\n", "rc": 100, "stderr": "E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)\nE: Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), are you root?\n", "stderr_lines": ["E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)", "E: Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), are you root?"], "stdout": "", "stdout_lines": []}
PLAY RECAP **********************************************************************************
We failed, because our user doesn't have root permissions. But why `192.168.0.11` didn't failed? - Because it already have installed firefox.
So how to fix permissions? We have 3 choices:
- Make manager user with root privileges and give his creds to ansible
- Give sudo priveleges to connecting user
- Give to ansible root password to use in `su` (Note: you should use [encrypted variables](https://docs.ansible.com/ansible/latest/vault_guide/vault_using_encrypted_content.html#playbooks-vault))
Recommended to make manager user with strong password and use encrypted password (1+3). But for sake of time I will just give ansible my password. And since on debian there is no `sudo` (what is default method of privelege escalation in Ansible), I will tell ansible to use `su`.
`inventory.ini`:
```yaml
...
[PCs:vars]
ansible_become=true
ansible_become_password=rootPassword
ansible_become_method=su
```
Try again:
```sh
TASK [web-browser : Gather the package facts] **********************************
chaanged: [192.168.0.5]
```
7. Next we will write browser version in terminal during run of Ansible
`roles/web-browser/tasks/main.yml`:
```yaml
...
- name: Gather the package facts
ansible.builtin.package_facts:
manager: auto
- name: Write browser version in terminal during run of Ansible
ansible.builtin.debug:
msg: "Firefox {{ ansible_facts.packages['firefox-esr'][0].version }} is installed!"
when: "'firefox-esr' in ansible_facts.packages"
```
Let's test it:
```sh
TASK [web-browser : Write browser version in terminal during run of Ansible] ***************
ok: [192.168.0.11] => {
"msg": "Firefox 115.11.0esr-1~deb11u1 is installed!"
}
ok: [192.168.0.5] => {
"msg": "Firefox 115.11.0esr-1~deb12u1 is installed!"
<h1>Welcome to {{ ansible_facts['hostname'] }}</h1><!-- We can use other variables from facts that ansible gathered, you can check what it have with command - ansible 192.168.0.5 -m ansible.builtin.gather_facts -i inventory.ini --tree ./tmp/facts -->
</main>
<!-- We make jinja2 loop to iterate over environment variables -->
<!-- We can use other variables from facts that ansible gathered, you can check what it have with command - ansible 192.168.0.5 -m ansible.builtin.gather_facts -i inventory.ini --tree ./tmp/facts -->
</main>
<!-- We make jinja2 loop to iterate over environment variables -->
<p>variable MAIL is /var/mail/root</p>
<p>variable LANGUAGE is en_US:en</p>
<p>variable USER is casual</p>
<p>variable SSH_CLIENT is 192.168.0.56 40480 22</p>
<p>variable XDG_SESSION_TYPE is tty</p>
<p>variable SHLVL is 0</p>
<p>variable MOTD_SHOWN is pam</p>
<p>variable HOME is /root</p>
<p>variable SSH_TTY is /dev/pts/0</p>
<p>variable DBUS_SESSION_BUS_ADDRESS is unix:path=/run/user/1000/bus</p>
<p>variable LOGNAME is casual</p>
<p>variable _ is /bin/sh</p>
<p>variable XDG_SESSION_CLASS is user</p>
<p>variable TERM is xterm-256color</p>
<p>variable XDG_SESSION_ID is 49</p>
<p>variable PATH is /usr/local/bin:/usr/bin:/bin:/usr/games</p>
<p>variable XDG_RUNTIME_DIR is /run/user/1000</p>
<p>variable LANG is en_US.UTF-8</p>
<p>variable SHELL is /bin/bash</p>
<p>variable PWD is /home/casual</p>
<p>variable SSH_CONNECTION is 192.168.0.56 40480 192.168.0.5 22</p>
</body>
</html>
```
10. And last - make caddy restart if ansible makes any modification
`roles/web-browser/handlers/main.yml`:
```yaml
- name: restart caddy service
ansible.builtin.service:
name: caddy
state: restarted
```
and then we can add `notify` to tasks so they will restart caddy:
Let's edit index.html a bit and run entire playbook:
`roles/web-browser/tasks/main.yml`:
```yaml
...
- name: Create Caddyfile
ansible.builtin.copy:
src: Caddyfile
dest: /etc/caddy/Caddyfile
owner: caddy
group: caddy
mode: '0644'
notify: restart caddy service
...
- name: write index webpage using jinja2
ansible.builtin.template:
src: index.html.j2
dest: /var/www/html/index.html
owner: caddy
group: caddy
mode: '0644'
notify: restart caddy service
```
What will happen:
```sh
...
TASK [web-browser : write index webpage using jinja2] **************************
