Everyday modules and handlers

The modules you will use every week

FQCN (fully qualified collection name) means collection.name.module, such as ansible.builtin.copy. Short names like copy usually still work, but FQCNs avoid confusion when two collections have a module with the same short name, and linting tools expect them.

- name: Create the app directory
  ansible.builtin.file:
    path: /opt/notes
    state: directory
    owner: notes
    mode: "0750"

- name: Allow only key logins
  ansible.builtin.lineinfile:
    path: /etc/ssh/sshd_config.d/01-hardening.conf
    regexp: '^PasswordAuthentication'
    line: PasswordAuthentication no
    create: true
    mode: "0600"

- name: Create user ravi in wheel
  ansible.builtin.user:
    name: ravi
    groups: wheel
    append: true
    state: present

Handlers: restart only when needed

After changing a config file you usually restart the service. But you do not want to restart it on every run, only when the file actually changed. A handler is a task in a separate handlers section. A normal task can notify it; the handler runs once, at the end of the play, and only if at least one notifying task reported changed.

- name: Configure Apache
  hosts: webservers
  become: true
  tasks:
    - name: Set the server admin email
      ansible.builtin.lineinfile:
        path: /etc/httpd/conf/httpd.conf
        regexp: '^ServerAdmin'
        line: ServerAdmin webmaster@example.com
      notify: Restart Apache

    - name: Apache is running
      ansible.builtin.service:
        name: httpd
        state: started
        enabled: true

  handlers:
    - name: Restart Apache
      ansible.builtin.service:
        name: httpd
        state: restarted

• If several tasks notify the same handler, it still runs only once.
• Handlers run at the end of the play, in the order they are written in handlers, not the order notified.
• If a later task fails on a host, pending handlers do not run there (unless you use --force-handlers or force_handlers: true).
• ansible.builtin.meta: flush_handlers runs pending handlers right away, in the middle of the play.

Collections you will need

ansible-core ships only ansible.builtin. Modules such as ansible.posix.firewalld, ansible.posix.selinux or community.general.timezone come from collections. Install them with ansible-galaxy collection install ansible.posix (from Ansible Galaxy or your company's automation hub), or use an execution environment that already contains them. The next module covers collections in depth.

Common mistakes

• mode: 644 without quotes or a leading 0. YAML reads 644 as the decimal number 644, which is not the permissions you meant. Write mode: "0644".
• Restarting a service as a normal task every time. Use a handler.
• A notify name with a typo: the play fails with "The requested handler ... was not found".
• lineinfile without regexp, so a changed value adds a second line instead of replacing the old one.