Ansible Modules Overview

An Ansible module is a discrete, reusable unit of work — a small program that Ansible transfers to a managed node, executes to accomplish a single task, and then removes. Modules are the actual workers in Ansible's architecture: while playbooks orchestrate and inventories describe targets, it is modules that install packages, copy files, restart services, create users, and interact with cloud APIs. Ansible ships with over 5,000 built-in modules, and understanding how they are organised — and how to look up any module instantly — is one of the most practical skills in this course.

How Modules Work

Every module follows the same lifecycle during a playbook run. Ansible copies the module as a Python script to a temporary directory on the managed node, executes it with the arguments you provided, receives a JSON result, and deletes the temporary file. The managed node does the actual work; the control node receives the outcome. This is why managed nodes need Python — they are the runtime environment for every module that runs against them.

Each module returns a structured JSON response that always includes a changed key — the boolean that drives idempotency. If changed is false, the system was already in the desired state and nothing was done. If changed is true, the module made a modification. This single key is what allows Ansible to be safely re-run without side effects.

Module Categories

Ansible's modules are organised into functional categories. Knowing these categories makes it much faster to find the right module for a task — instead of searching through 5,000 names, you navigate to the relevant category first.

Essential Modules to Know

Out of Ansible's 5,000+ modules, a core set of about 15 covers the vast majority of real-world automation tasks. These are the modules you will encounter repeatedly throughout this course and in production environments.

Collections and Module Namespacing

Modern Ansible organises modules into collections — packages of related modules, plugins, and roles grouped under a namespace. A fully qualified module name follows the pattern namespace.collection.module_name. For example, ansible.builtin.package means: the ansible namespace, the builtin collection, the package module.

This namespacing was introduced in Ansible 2.10 to prevent naming conflicts as the ecosystem grew. You can still use short module names like package in playbooks for backward compatibility, but the fully qualified name is the recommended standard — it makes it immediately clear which collection a module comes from.

Finding Module Documentation

You do not need to memorise module parameters — knowing how to look them up instantly is far more valuable. There are two primary methods: the built-in ansible-doc command for offline terminal reference, and the official Ansible documentation website for browsable, searchable reference with examples.

Method 1 — ansible-doc in the terminal

# Show full documentation for any module — parameters, return values, examples
ansible-doc ansible.builtin.copy

# List all available modules (pipe to grep to search)
ansible-doc -l

# Search for modules related to a keyword
ansible-doc -l | grep user

# Show a short synopsis of a module without full docs
ansible-doc -s ansible.builtin.package

> ANSIBLE.BUILTIN.COPY (/usr/lib/python3/dist-packages/ansible/modules/copy.py)

  The `copy' module copies a file from the local or remote machine
  to a location on the remote machine.

OPTIONS (= is mandatory):

- backup
        Create a backup file including the timestamp information
        [Default: False]
        type: bool

= dest
        Remote absolute path where the file should be copied to.
        type: path

- mode
        The permissions of the destination file or directory.
        [Default: (null)]
        type: raw
...
EXAMPLES:
- name: Copy file with owner and permissions
  ansible.builtin.copy:
    src: /srv/myfiles/foo.conf
    dest: /etc/foo.conf
    owner: foo
    group: foo
    mode: '0644'

Method 2 — Official documentation website