Ansible Modules: Complete Guide to Built-in & Custom Modules

By Luca Berton · Published 2024-01-01 · Category: installation

Complete guide to Ansible modules. Understand built-in modules, collection modules, how to find, use, and create custom modules for automation.

Ansible modules are the foundation of Ansible's automation capabilities. They are small programs that perform specific tasks, enabling you to automate everything from software installation to cloud provisioning. This article explains what Ansible modules are, their types, and how to use them in playbooks.

What Are Ansible Modules?

Ansible modules are standalone units of code executed by Ansible to perform specific tasks on managed nodes. These tasks can range from system configuration and file manipulation to cloud infrastructure provisioning.

Modules are also referred to as "task plugins" or "library plugins" and are invoked in Ansible playbooks as tasks.

Key Features of Ansible Modules:

Idempotence: Modules are designed to achieve the same result regardless of how many times they are run.
Agentless Execution: Modules execute over SSH or WinRM without requiring agents on the target systems.
Extensibility: You can create custom modules to extend functionality.

Types of Ansible Modules

Ansible includes a wide variety of modules categorized by their functionality:

1. Core Modules

Maintained by the Ansible team and included in all installations.
Examples: file, user, service, package.

2. Cloud Modules

Manage resources in cloud platforms like AWS, Azure, and Google Cloud.
Examples: amazon.aws.ec2, azure.azcollection.azure_rm_vm.

3. Networking Modules

Automate network device configurations.
Examples: ios_config, junos_config, nxos_command.

4. Database Modules

Manage databases like MySQL, PostgreSQL, and MongoDB.
Examples: mysql_user, postgresql_db.

5. Custom Modules

User-created modules to meet specific requirements.

Anatomy of an Ansible Module Task

Here’s an example task using the apt module to install Nginx:

- name: Install Nginx
  apt:
    name: nginx
    state: present

Task Components:

name: A description of the task.
apt: The module used for the task.
name: The package to be installed.
state: Ensures the package is installed.

Commonly Used Ansible Modules

File Management
copy: Copy files to target machines.
template: Deploy Jinja2 templates.
file: Manage file and directory properties.

Service Management
service: Start, stop, and manage services.
systemd: Interact with systemd services.

Package Management
yum: Manage packages on RHEL-based systems.
apt: Manage packages on Debian-based systems.

Cloud and Virtualization
ec2: Provision AWS EC2 instances.
vmware_guest: Manage VMware virtual machines.

User Management
user: Create, update, or delete user accounts.
group: Manage user groups.

Writing Custom Ansible Modules

Custom modules can be written in Python, PowerShell, or any scripting language. A simple Python module follows this structure:

#!/usr/bin/python

from ansible.module_utils.basic import AnsibleModule

def main():
    module = AnsibleModule(
        argument_spec=dict(
            name=dict(type='str', required=True)
        )
    )
    response = {"message": f"Hello {module.params['name']}!"}
    module.exit_json(changed=False, **response)

if __name__ == '__main__':
    main()

Using Modules in Playbooks

Modules are called in tasks within a playbook. Example playbook to ensure a service is running:

- hosts: webservers
  tasks:
    - name: Ensure Nginx is running
      service:
        name: nginx
        state: started

Conclusion

Ansible modules are the essential building blocks of Ansible automation. Whether you're managing servers, deploying applications, or provisioning cloud resources, modules enable you to perform tasks efficiently and consistently.

Explore More About Ansible Modules in the Official Documentation

Module Categories

Category	Examples	Use Case
System	`user`, `group`, `service`, `cron`	OS configuration
Files	`copy`, `template`, `file`, `lineinfile`	File management
Packages	`apt`, `yum`, `pip`, `snap`	Software installation
Cloud	`ec2_instance`, `azure_rm_virtualmachine`	Cloud resources
Network	`ios_config`, `nxos_command`	Network devices
Database	`mysql_db`, `postgresql_user`	Database management
Windows	`win_copy`, `win_service`, `win_user`	Windows automation

Using Modules

# In playbooks
- name: Install nginx
  ansible.builtin.apt:
    name: nginx
    state: present
  become: true

# Ad-hoc commands
# ansible all -m ping
# ansible all -m shell -a "uptime"
# ansible all -m copy -a "src=file.txt dest=/tmp/file.txt"

FQCN (Fully Qualified Collection Name)

# Recommended: use FQCN
- ansible.builtin.copy:
    src: config.yml
    dest: /etc/app/config.yml

# Short name (works but deprecated for non-builtin)
- copy:
    src: config.yml
    dest: /etc/app/config.yml

# Collection modules
- community.general.ufw:
    rule: allow
    port: 22

- amazon.aws.ec2_instance:
    name: web-server
    instance_type: t3.micro

Module Return Values

- name: Create user
  ansible.builtin.user:
    name: deploy
  register: user_result

- debug:
    msg: |
      Changed: {{ user_result.changed }}
      UID: {{ user_result.uid }}
      Home: {{ user_result.home }}

Find and Explore Modules

# List all available modules
ansible-doc -l

# Search modules
ansible-doc -l | grep docker

# Module documentation
ansible-doc ansible.builtin.copy

# Show module parameters (short)
ansible-doc -s ansible.builtin.copy

Key Built-in Modules

Module	Purpose
`copy`	Copy files to remote
`template`	Render Jinja2 templates
`file`	Manage files/dirs/links
`lineinfile`	Edit lines in files
`apt` / `yum`	Package management
`service`	Manage services
`user` / `group`	User management
`command` / `shell`	Run commands
`uri`	HTTP requests
`debug`	Print messages
`set_fact`	Set variables
`assert`	Validate conditions

Install Collection Modules

ansible-galaxy collection install community.general
ansible-galaxy collection install amazon.aws
ansible-galaxy collection install community.docker

Write a Custom Module

#!/usr/bin/python
# library/hello.py
from ansible.module_utils.basic import AnsibleModule

def main():
    module = AnsibleModule(
        argument_spec=dict(
            name=dict(type='str', required=True),
        )
    )
    module.exit_json(changed=False, msg=f"Hello, {module.params['name']}!")

if __name__ == '__main__':
    main()

- hello:
    name: World
  register: result
- debug: var=result.msg  # "Hello, World!"

FAQ

Modules vs Plugins?

Modules are a type of plugin that execute tasks on remote hosts. Other plugins (callback, lookup, filter) extend Ansible's core functionality.

How do modules execute?

Ansible copies the module to the remote host, executes it with Python, captures JSON output, then removes the module. Exception: raw module runs without Python.

What's the difference between command and shell?

command runs without a shell (no pipes, redirects). shell runs through /bin/sh (supports |, >, &&). Prefer command for security; use shell when you need shell features.

What Are Modules?

Modules are discrete units of code that Ansible executes on managed nodes. Each module handles a specific task:

# Each task uses one module
- ansible.builtin.apt:        # Package management
    name: nginx
- ansible.builtin.service:     # Service management
    name: nginx
    state: started
- ansible.builtin.template:    # File templating
    src: config.j2
    dest: /etc/app.conf

Find Modules

# List all available modules
ansible-doc -l

# Search for modules
ansible-doc -l | grep docker

# View module documentation
ansible-doc ansible.builtin.copy

# List modules in a collection
ansible-doc -l community.general

Common Module Categories

Files

- ansible.builtin.copy:       # Copy files
- ansible.builtin.template:   # Jinja2 templates
- ansible.builtin.file:       # File properties
- ansible.builtin.lineinfile: # Edit lines
- ansible.builtin.get_url:    # Download files
- ansible.builtin.unarchive:  # Extract archives

Packages

- ansible.builtin.apt:        # Debian/Ubuntu
- ansible.builtin.yum:        # RHEL/CentOS
- ansible.builtin.dnf:        # Fedora
- ansible.builtin.pip:        # Python packages
- ansible.builtin.package:    # OS-agnostic

System

- ansible.builtin.service:    # Manage services
- ansible.builtin.systemd:    # systemd specific
- ansible.builtin.user:       # User accounts
- ansible.builtin.group:      # Groups
- ansible.builtin.cron:       # Cron jobs
- ansible.builtin.hostname:   # Set hostname

Commands

- ansible.builtin.command:    # Run commands (no shell)
- ansible.builtin.shell:      # Run through shell
- ansible.builtin.raw:        # Raw SSH command
- ansible.builtin.script:     # Run local script remotely
- ansible.builtin.expect:     # Interactive commands

Networking & Cloud

- amazon.aws.ec2_instance:    # AWS EC2
- azure.azcollection.*:       # Azure resources
- community.docker.*:         # Docker containers
- ansible.netcommon.*:        # Network devices

Module Return Values

- copy:
    src: file.txt
    dest: /tmp/file.txt
  register: result

# result contains:
# .changed — whether the task made changes
# .failed — whether it failed
# .dest — destination path
# .checksum — file checksum
# .size — file size

Module Parameters

# Required vs optional
- apt:
    name: nginx          # Required
    state: present       # Optional (default: present)
    update_cache: true   # Optional

# Free-form (shorthand)
- command: /opt/script.sh
# Equivalent to:
- command:
    cmd: /opt/script.sh

Collections vs Built-in

# Built-in (always available)
- ansible.builtin.copy:

# Collection (must install first)
- community.docker.docker_container:
- amazon.aws.ec2_instance:

# Install collections
# ansible-galaxy collection install community.docker

FAQ

How many modules are there?

Thousands — ansible.builtin has ~70 core modules. Collections add thousands more for cloud, networking, databases, etc.

Can I use modules without a playbook?

Yes — ad-hoc commands: ansible all -m ping or ansible web1 -m apt -a "name=nginx" -b

What language are modules written in?

Mostly Python, but modules can be any executable (Bash, Go, Ruby, etc.).

Category: installation

Browse all Ansible tutorials · AnsiblePilot Home

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton

Ansible Modules: Complete Guide to Built-in & Custom Modules

What Are Ansible Modules?

Key Features of Ansible Modules:

Types of Ansible Modules

1. Core Modules

2. Cloud Modules

3. Networking Modules

4. Database Modules

5. Custom Modules

Anatomy of an Ansible Module Task

Task Components:

Commonly Used Ansible Modules

Writing Custom Ansible Modules

Using Modules in Playbooks

Conclusion

Module Categories

Using Modules

FQCN (Fully Qualified Collection Name)

Module Return Values

Find and Explore Modules

Key Built-in Modules

Install Collection Modules

Write a Custom Module

FAQ

Modules vs Plugins?

How do modules execute?

What's the difference between command and shell?

What Are Modules?

Find Modules

Common Module Categories

Files

Packages

System

Commands

Networking & Cloud

Module Return Values

Module Parameters

Collections vs Built-in

FAQ

How many modules are there?

Can I use modules without a playbook?

What language are modules written in?

Related Articles