Ansible for repeatable fixes and checks

The idea

When the same fix has to be applied to several machines, or applied again after you rebuilt one, typing commands does not scale and cannot be reviewed. Ansible describes the desired state in a text file and brings each machine to it. It connects over SSH, needs no agent on the managed hosts (only Python), and is built so that running it twice changes nothing the second time. That property is idempotence, and it is why you can run a playbook as a check.

On RHEL the control tools come from the ansible-core package in AppStream. Check what you have with ansible --version. The command set below is the same across versions.

The parts

Part	What it is
Inventory	The list of managed hosts and groups ([lab]), a file in INI or YAML form
Module	A unit of work with parameters: copy, lineinfile, dnf, service, user, file, template
Task	One module call with a name
Play	Tasks applied to a group of hosts, with options such as become and vars
Playbook	A YAML file with one or more plays
Handler	A task that runs at the end of the play, only if a task notified it and reported changed
Fact	A variable Ansible gathers about the host, such as the distribution or addresses

Prefer the full module names (ansible.builtin.copy). They avoid ambiguity and let ansible-doc find the page. Only command, shell and raw are not idempotent by themselves; if you must use command, add creates: or removes: so it skips when the work is already done.

Configuration and access

Ansible reads settings from ansible.cfg (current directory, then ~/.ansible.cfg, then /etc/ansible/ansible.cfg). A minimal project directory has an ansible.cfg naming the inventory, the remote user and privilege escalation:

[defaults]
inventory = ./inventory
remote_user = alex

[privilege_escalation]
become = true

Key-based SSH to the managed hosts and sudo for the remote user make it work without prompts. If it asks for a password or says Permission denied, you are debugging SSH, not Ansible: try ssh alex@node2.lab.example first.

Try it

Real output from ansible-core, on a local connection. Start with documentation, which is available offline.

ansible-doc -l | wc -l
ansible-doc -s ansible.builtin.lineinfile | sed -n 1,4p

ansible-doc -l counts the installed modules (71 in this test environment; a RHEL host with extra collections shows more, and which ones depend on the packages you installed). -s shows a snippet of every parameter. The full page without -s ends with working EXAMPLES, which is what you copy during an exam.

Ad hoc commands

An ad hoc command runs one module on a group, with no playbook:

ansible lab -i inventory -m ansible.builtin.copy -a "dest=/tmp/ans/x.txt content=hello"

node1 | CHANGED => {
    "changed": true,
    "checksum": "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d",
    "dest": "/tmp/ans/x.txt",
    "mode": "0644",
    ...

Run the identical command again:

node1 | SUCCESS => {
    "changed": false,
    "checksum": "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d",
    "dest": "/tmp/ans/x.txt",
    ...

CHANGED the first time, SUCCESS with "changed": false the second: the file already matched, so nothing happened. This is the idempotent behaviour you rely on.

Useful ad hoc commands while troubleshooting: ansible all -m ansible.builtin.ping (SSH and Python work), ansible lab -m ansible.builtin.setup -a 'filter=ansible_distribution*' (facts), ansible lab -b -m ansible.builtin.command -a 'systemctl is-active rsyslog' (run a read-only check everywhere; -b means become).

A playbook with a handler

---
- name: Forward logs to the central host
  hosts: lab
  vars:
    loghost: loghost.lab.example
  tasks:
    - name: Install the forwarding rule
      ansible.builtin.copy:
        dest: /tmp/ans/rs.conf
        content: |
          *.* action(type="omfwd" target="{{ loghost }}" port="514" protocol="tcp")
        mode: "0644"
      notify: Restart rsyslog
  handlers:
    - name: Restart rsyslog
      ansible.builtin.debug:
        msg: "systemctl restart rsyslog would run here"

ansible-playbook -i inventory play.yml

PLAY [Forward logs to the central host] ****************************************

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

TASK [Install the forwarding rule] *********************************************
changed: [node1]

RUNNING HANDLER [Restart rsyslog] **********************************************
ok: [node1] => {
    "msg": "systemctl restart rsyslog would run here"
}

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

(The handler uses debug here only so the test does not touch a service; in your playbook use ansible.builtin.service with state: restarted.) The second run:

TASK [Install the forwarding rule] *********************************************
ok: [node1]

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

No changed, so no notification, so no handler. The service is not restarted needlessly. Always read the PLAY RECAP: changed=0 on the second run proves idempotence; failed or unreachable is non-zero when something broke.

Look before you change

--check runs without changing anything, and --diff shows what would change in text files:

ansible-playbook -i inventory fix.yml --check --diff

TASK [Root login off] **********************************************************
--- before: /tmp/ans/sshd_test.conf (content)
+++ after: /tmp/ans/sshd_test.conf (content)
@@ -1,2 +1,2 @@
-#PermitRootLogin yes
+PermitRootLogin no
 Port 22

changed: [node1]

ansible-playbook -i inventory fix.yml --syntax-check

playbook: fix.yml

--syntax-check only parses the YAML and the structure; it does not contact hosts and cannot see a wrong parameter or a missing privilege. --check can, but some modules (command, shell) cannot predict their result and are skipped.

The mistakes you will meet

Symptom	Likely cause
YAML syntax: mapping values are not allowed here or could not find expected ':'	Indentation or a missing colon; YAML allows spaces, never tabs
The requested handler 'x' was not found / handler never runs	notify: text and handler name: differ (case matters)
Permission denied writing under /etc	The play lacks become: true (or -b)
couldn't resolve module/action 'ansible.posix.firewalld'	The collection is not installed: ansible-doc -l | grep firewalld shows it
UNREACHABLE! ... Permission denied (publickey)	SSH keys, user name or ansible_user
changed every run	A command/shell task without creates:, or a template that writes a timestamp
Failed to connect ... python	Managed host has no Python interpreter at the discovered path

Going further

Roles from Red Hat. The rhel-system-roles package supplies tested roles for common jobs (time synchronisation, SELinux, firewall, logging, storage, network). Reading how they set a variable is a good source of working examples, and they are the supported way to automate these settings in production. Beyond the exam: keep playbooks in version control, use ansible-vault for secrets, and test with a second host before the real one.