Essential Modules

A handful of modules cover most of what configuring a server actually requires, and every one of them is idempotent against live state: install a package, run a service, place a file, set ownership, create a user, edit one line in a config. Learning this toolbox against the Larkspur stack is most of what you need before roles and templates enter the picture.

The mapping is concrete — apt for nginx, service for gunicorn and PostgreSQL, copy and template for config, lineinfile for a single tuning setting. Each module names a category of work, and knowing which one owns which job is the difference between a clean play and a pile of shell commands pretending to be one.

package and apt

The apt module installs, removes, and pins packages on the Ubuntu 22.04 nodes: name=nginx state=present, with update_cache=yes to refresh the index first. The package module is the OS-agnostic wrapper that dispatches to apt or dnf by fact, useful when one role targets mixed distros.

On a known-Ubuntu fleet, apt is the explicit choice — you gain nothing by hiding behind the generic wrapper when every host runs the same package manager. Reach for package only when a single role genuinely has to span distributions.

service and systemd

The service module starts, stops, and enables units idempotently: name=gunicorn state=started enabled=yes reports changed only when it actually had to act. state=restarted is the exception — it bounces the service on every run and always reports changed, which is why a restart belongs in a handler fired by a real change, not in a routine task. The systemd module is the systemd-specific variant for when you need daemon_reload after dropping a new unit file — something service alone will not do.

Set both state and enabled on every long-running service. state=started means running now; enabled=yes means surviving a reboot. Setting one without the other gives you gunicorn that is enabled but not running, or running but gone after the next restart.

copy and template

The copy module places a static file with declared owner, group, and mode. The template module renders a Jinja2 file first — the nginx larkspur.conf, the app's app.env — then places it the same way. Both report changed only when the destination content or attributes actually differ, which is the idempotency contract from the last topic applied to files.

The task below installs and configures the web tier in one pass: apt for the package, template for the rendered config, service to run it. Every module is idempotent, so a second run reports all ok unless a fact behind the template changed.

- hosts: web
  become: true
  tasks:
    - name: Install nginx
      ansible.builtin.apt:
        name: nginx
        state: present
        update_cache: true

    - name: Render the site config
      ansible.builtin.template:
        src: larkspur.conf.j2
        dest: /etc/nginx/sites-available/larkspur.conf
        owner: root
        group: root
        mode: "0644"

    - name: Ensure nginx is running and enabled
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

Nothing in those tasks describes how to install a package or render a file — they declare the destination and let each module reconcile against whatever the host currently looks like. That is the toolbox doing its job.

file

The file module manages a path's existence and attributes without touching content: create a directory (/opt/larkspur, state=directory), set mode and owner on an existing path, make a symlink, or remove a path with state=absent. It is the module for "this directory must exist with these permissions."

Because it carries no content, file pairs naturally with copy and template: file ensures the directory and ownership are right, then template drops the rendered config into it. Each owns one concern and stays idempotent.

user and group

The user module creates the service account the app runs as — name=larkspur system=yes shell=/usr/sbin/nologin — sets its groups, and manages SSH keys via authorized_key. It is idempotent, so it is safe in every run and converges a drifted account back to the declared state rather than erroring because the user already exists.

A service account created this way is reproducible: rebuild web2.larkspur.io from the same play and the larkspur user comes back identical, no login shell, same groups. That is the difference between a managed account and one someone useradd-ed by hand during an incident.

lineinfile and blockinfile

For surgical edits to a file Ansible does not own wholesale, lineinfile ensures one line matches a regex — a single sysctl entry or a pg_hba.conf line — and blockinfile manages a delimited block. Both are the fallback for files you cannot template in full, and both are easy to overuse where template would be cleaner.

Reach for full-file management first. When Ansible controls the file end to end, template or copy rewrites it to a declared state in one pass; reserve lineinfile for a single setting inside a vendor-managed config you genuinely manage only part of. Building a whole file line by line across many lineinfile tasks produces a brittle, ordering-dependent mess.