Ansible Modules And Plugins

Last updated: July 1, 2025

My Journey from Confusion to Clarity

When I first started with Ansible, I was utterly confused about the difference between modules and plugins. I remember spending hours trying to figure out why I couldn't use a "lookup plugin" the same way I used a "copy module." The documentation mentioned both terms interchangeably in some contexts, and as a beginner, I felt lost in a sea of technical jargon.

The breakthrough came during a particularly challenging automation project where I needed to read configuration data from external files, transform JSON data into different formats, and perform conditional logic based on file existence. I was trying to solve everything with modules until a senior colleague introduced me to the world of plugins – specifically lookup, filter, and test plugins.

That moment changed everything. I realized that Ansible's true power lies not just in its modules (the "what" you want to do) but also in its plugins (the "how" you want to extend and manipulate that functionality). Understanding this distinction transformed me from someone who could copy-paste playbooks to someone who could architect sophisticated automation solutions.

In this post, I'll share what I've learned about Ansible modules and plugins, using practical Linux and Windows examples to demonstrate how they work together to create powerful automation workflows.

Understanding Ansible Modules vs Plugins

Let me start by clarifying the fundamental difference that confused me for so long:

Modules: The "Doers"

Modules are units of code that perform specific tasks on target systems. They are the primary building blocks of Ansible automation that actually execute actions like:

• Installing packages

• Creating files and directories

• Managing services

• Configuring network settings

• Managing users and permissions

Plugins: The "Enhancers"

Plugins extend Ansible's core functionality and control how automation works. They run on the control node and provide capabilities like:

• Looking up data from external sources (lookup plugins)

• Transforming and filtering data (filter plugins)

• Testing conditions and values (test plugins)

• Connecting to different systems (connection plugins)

• Handling authentication (become plugins)

Think of it this way: Modules are like tools in a toolbox (hammer, screwdriver, wrench), while plugins are like the workshop extensions that help you use those tools more effectively (measuring tape, lighting, workbench features).

Ansible Modules Deep Dive

Core Module Categories

Ansible provides thousands of modules organized into logical categories:

System Modules

These handle basic system operations:

# Linux package management
- name: Install packages on RHEL/CentOS
  ansible.builtin.yum:
    name:
      - httpd
      - mysql-server
      - git
    state: present

- name: Install packages on Ubuntu/Debian
  ansible.builtin.apt:
    name:
      - apache2
      - mysql-server
      - git
    state: present
    update_cache: yes

# Windows package management
- name: Install software on Windows
  chocolatey.chocolatey.win_chocolatey:
    name:
      - git
      - notepadplusplus
      - 7zip
    state: present

File Management Modules

For handling files and directories:

# Cross-platform file operations
- name: Create application directory (Linux)
  ansible.builtin.file:
    path: /opt/myapp
    state: directory
    owner: nginx
    group: nginx
    mode: '0755'
  when: ansible_os_family != 'Windows'

- name: Create application directory (Windows)
  ansible.windows.win_file:
    path: C:\MyApp
    state: directory
  when: ansible_os_family == 'Windows'

- name: Deploy configuration template (Linux)
  ansible.builtin.template:
    src: app.conf.j2
    dest: /opt/myapp/app.conf
    backup: yes
  when: ansible_os_family != 'Windows'

- name: Deploy configuration template (Windows)
  ansible.windows.win_template:
    src: app.conf.j2
    dest: C:\MyApp\app.conf
  when: ansible_os_family == 'Windows'

Service Management Modules

For controlling system services:

# Linux service management
- name: Manage web server service (Linux)
  ansible.builtin.systemd:
    name: "{{ web_service_name }}"
    state: started
    enabled: yes
    daemon_reload: yes
  when: ansible_os_family != 'Windows'

# Windows service management  
- name: Manage IIS service (Windows)
  ansible.windows.win_service:
    name: W3SVC
    state: started
    start_mode: auto
  when: ansible_os_family == 'Windows'

- name: Install Windows feature
  ansible.windows.win_feature:
    name: IIS-WebServerRole
    state: present
  when: ansible_os_family == 'Windows'

Network Modules

For network configuration and management:

# Linux firewall configuration
- name: Configure firewall (Linux)
  ansible.posix.firewalld:
    service: "{{ item }}"
    permanent: true
    state: enabled
    immediate: true
  loop:
    - http
    - https
    - ssh
  when: ansible_os_family == 'RedHat'

# Windows firewall configuration
- name: Configure Windows firewall
  ansible.windows.win_firewall_rule:
    name: "Allow {{ item.name }}"
    localport: "{{ item.port }}"
    action: allow
    direction: in
    protocol: tcp
    state: present
  loop:
    - { name: "HTTP", port: "80" }
    - { name: "HTTPS", port: "443" }
    - { name: "RDP", port: "3389" }
  when: ansible_os_family == 'Windows'

Custom Module Development

Sometimes you need functionality that doesn't exist in built-in modules. Here's a simple custom module example:

#!/usr/bin/python
# custom_modules/system_info.py

from ansible.module_utils.basic import AnsibleModule
import platform
import psutil

def get_system_info():
    """Gather comprehensive system information"""
    return {
        'hostname': platform.node(),
        'os': platform.system(),
        'os_version': platform.release(),
        'architecture': platform.machine(),
        'cpu_count': psutil.cpu_count(),
        'memory_gb': round(psutil.virtual_memory().total / (1024**3), 2),
        'disk_usage': {
            'total': round(psutil.disk_usage('/').total / (1024**3), 2),
            'used': round(psutil.disk_usage('/').used / (1024**3), 2),
            'free': round(psutil.disk_usage('/').free / (1024**3), 2)
        }
    }

def main():
    module = AnsibleModule(
        argument_spec=dict(
            detailed=dict(type='bool', default=False)
        ),
        supports_check_mode=True
    )
    
    try:
        system_info = get_system_info()
        
        module.exit_json(
            changed=False,
            system_info=system_info,
            msg="System information gathered successfully"
        )
    except Exception as e:
        module.fail_json(msg=f"Failed to gather system info: {str(e)}")

if __name__ == '__main__':
    main()

Using the custom module:

---
- name: Gather system information using custom module
  hosts: all
  tasks:
    - name: Get detailed system information
      system_info:
        detailed: true
      register: sys_info

    - name: Display system information
      ansible.builtin.debug:
        msg: |
          System: {{ sys_info.system_info.hostname }}
          OS: {{ sys_info.system_info.os }} {{ sys_info.system_info.os_version }}
          CPU Cores: {{ sys_info.system_info.cpu_count }}
          Memory: {{ sys_info.system_info.memory_gb }}GB
          Disk: {{ sys_info.system_info.disk_usage.used }}GB / {{ sys_info.system_info.disk_usage.total }}GB

Ansible Plugins Deep Dive

Plugins are the secret sauce that makes Ansible incredibly flexible and powerful. Let's explore the most commonly used types:

Lookup Plugins

Lookup plugins retrieve data from external sources during playbook execution. They run on the control node and are perfect for reading configuration files, querying APIs, or accessing databases.

File Lookup Plugin

---
- name: Deploy SSH keys using lookup plugins
  hosts: all
  tasks:
    # Read SSH public key from local file
    - name: Deploy SSH public key (Linux)
      ansible.posix.authorized_key:
        user: "{{ ansible_user }}"
        state: present
        key: "{{ lookup('file', '~/.ssh/id_rsa.pub') }}"
      when: ansible_os_family != 'Windows'

    # Read application configuration from JSON file
    - name: Load application configuration
      ansible.builtin.set_fact:
        app_config: "{{ lookup('file', 'configs/app_config.json') | from_json }}"

    - name: Display loaded configuration
      ansible.builtin.debug:
        var: app_config

Environment Lookup Plugin

---
- name: Use environment variables in automation
  hosts: all
  vars:
    # Lookup environment variables with defaults
    db_password: "{{ lookup('env', 'DB_PASSWORD') | default('defaultpass') }}"
    api_key: "{{ lookup('env', 'API_KEY') }}"
    deployment_env: "{{ lookup('env', 'ENVIRONMENT') | default('development') }}"
  tasks:
    - name: Configure application with environment variables
      ansible.builtin.template:
        src: app.conf.j2
        dest: "{{ '/etc/myapp/app.conf' if ansible_os_family != 'Windows' else 'C:\\MyApp\\app.conf' }}"
      vars:
        database_password: "{{ db_password }}"
        api_token: "{{ api_key }}"
        environment: "{{ deployment_env }}"

URL Lookup Plugin

---
- name: Fetch data from APIs using lookup plugins
  hosts: localhost
  tasks:
    # Fetch server list from API
    - name: Get server inventory from API
      ansible.builtin.set_fact:
        server_list: "{{ lookup('url', 'https://api.example.com/servers') | from_json }}"

    # Download and verify checksums
    - name: Download application package
      ansible.builtin.get_url:
        url: "{{ app_download_url }}"
        dest: "/tmp/{{ app_package_name }}"
        checksum: "sha256:{{ lookup('url', app_checksum_url) }}"

Inventory Hostname Lookup

---
- name: Dynamic inventory operations with lookup plugins
  hosts: localhost
  tasks:
    # Get all hosts in a specific group
    - name: Get all web servers
      ansible.builtin.set_fact:
        web_servers: "{{ lookup('inventory_hostnames', 'webservers') }}"

    - name: Display web servers
      ansible.builtin.debug:
        msg: "Web servers: {{ web_servers }}"

    # Generate configuration for load balancer
    - name: Create load balancer configuration
      ansible.builtin.template:
        src: haproxy.cfg.j2
        dest: /etc/haproxy/haproxy.cfg
      vars:
        backend_servers: "{{ lookup('inventory_hostnames', 'webservers') }}"

Filter Plugins

Filter plugins transform and manipulate data. They're incredibly useful for data processing, formatting, and conversion tasks.

Data Transformation Filters

---
- name: Data transformation with filter plugins
  hosts: all
  vars:
    user_list:
      - { name: "john", role: "admin", active: true }
      - { name: "jane", role: "user", active: true }
      - { name: "bob", role: "user", active: false }
    
    raw_data: |
      name,age,department
      Alice,25,Engineering
      Bob,30,Marketing
      Charlie,35,Engineering
  
  tasks:
    # List manipulation filters
    - name: Filter active users only
      ansible.builtin.debug:
        msg: "Active users: {{ user_list | selectattr('active') | map(attribute='name') | list }}"

    - name: Get admin users
      ansible.builtin.debug:
        msg: "Admin users: {{ user_list | selectattr('role', 'equalto', 'admin') | map(attribute='name') | list }}"

    # String manipulation filters
    - name: Transform CSV data
      ansible.builtin.set_fact:
        parsed_data: "{{ raw_data | split('\n') | map('split', ',') | list }}"

    - name: Create user passwords with hash filter
      ansible.builtin.user:
        name: "{{ item.name }}"
        password: "{{ ('password123' + item.name) | password_hash('sha512') }}"
        state: present
      loop: "{{ user_list | selectattr('active') | list }}"
      when: ansible_os_family != 'Windows'

JSON/YAML Processing Filters

---
- name: JSON and YAML processing with filters
  hosts: localhost
  vars:
    config_json: |
      {
        "database": {
          "host": "localhost",
          "port": 5432,
          "name": "myapp"
        },
        "cache": {
          "type": "redis",
          "host": "cache.example.com"
        }
      }
  
  tasks:
    # Convert JSON to YAML
    - name: Convert JSON configuration to YAML
      ansible.builtin.copy:
        content: "{{ config_json | from_json | to_nice_yaml }}"
        dest: "/tmp/config.yml"

    # Extract specific values from JSON
    - name: Extract database configuration
      ansible.builtin.set_fact:
        db_config: "{{ config_json | from_json | json_query('database') }}"

    - name: Display database host
      ansible.builtin.debug:
        msg: "Database host: {{ db_config.host }}"

Network and URL Filters

---
- name: Network and URL manipulation with filters
  hosts: all
  vars:
    server_urls:
      - "https://web1.example.com:8080/app"
      - "https://web2.example.com:8080/app"
      - "https://api.example.com:3000/v1"
  
  tasks:
    # Extract hostnames from URLs
    - name: Extract hostnames from URLs
      ansible.builtin.debug:
        msg: "Hostnames: {{ server_urls | map('urlsplit', 'hostname') | list }}"

    # Generate IP address ranges
    - name: Generate subnet IP addresses
      ansible.builtin.debug:
        msg: "Subnet IPs: {{ '192.168.1.0/24' | ansible.utils.ipaddr('host') | list }}"

    # URL manipulation
    - name: Create backup URLs
      ansible.builtin.set_fact:
        backup_urls: "{{ server_urls | map('regex_replace', 'app$', 'backup') | list }}"

Test Plugins

Test plugins provide boolean tests for conditional logic in playbooks. They're essential for making intelligent decisions in your automation.

File and Path Tests

---
- name: Conditional logic with test plugins
  hosts: all
  tasks:
    # Test if files exist
    - name: Check if application is already installed
      ansible.builtin.stat:
        path: "{{ '/opt/myapp/bin/myapp' if ansible_os_family != 'Windows' else 'C:\\MyApp\\myapp.exe' }}"
      register: app_binary

    - name: Install application if not present
      ansible.builtin.package:
        name: myapp
        state: present
      when: not app_binary.stat.exists

    # Test file properties
    - name: Ensure configuration file has correct permissions
      ansible.builtin.file:
        path: "{{ config_file_path }}"
        mode: '0600'
        owner: root
        group: root
      when: 
        - ansible_os_family != 'Windows'
        - config_file_path is defined
        - config_file_path | length > 0

Version and Comparison Tests

---
- name: Version comparison with test plugins
  hosts: all
  tasks:
    # Test version comparisons
    - name: Check if Python version is sufficient
      ansible.builtin.fail:
        msg: "Python version {{ ansible_python.version.major }}.{{ ansible_python.version.minor }} is too old"
      when: ansible_python.version.major is version('3.8', '<')

    # Test if services failed
    - name: Start web server
      ansible.builtin.systemd:
        name: "{{ web_service_name }}"
        state: started
      register: start_result
      when: ansible_os_family != 'Windows'

    - name: Handle service start failure
      ansible.builtin.debug:
        msg: "Service failed to start: {{ start_result.msg }}"
      when: 
        - start_result is defined
        - start_result is failed

    # Test data types and values
    - name: Validate configuration parameters
      ansible.builtin.assert:
        that:
          - max_connections is defined
          - max_connections is number
          - max_connections is version('100', '>=')
          - database_url is defined
          - database_url is match('^postgres://.*')
        fail_msg: "Invalid configuration parameters"

Collection and String Tests

---
- name: Collection and string testing with test plugins
  hosts: all
  vars:
    required_packages:
      - git
      - curl
      - wget
    installed_packages:
      - git
      - vim
      - curl
  
  tasks:
    # Test collections and subsets
    - name: Check if all required packages are available
      ansible.builtin.debug:
        msg: "All required packages are installed"
      when: required_packages is subset(installed_packages)

    - name: Find missing packages
      ansible.builtin.set_fact:
        missing_packages: "{{ required_packages | difference(installed_packages) }}"

    - name: Install missing packages
      ansible.builtin.package:
        name: "{{ missing_packages }}"
        state: present
      when: missing_packages | length > 0

    # String pattern tests
    - name: Validate email addresses
      ansible.builtin.assert:
        that:
          - admin_email is defined
          - admin_email is match('.*@.*\\..*')
        fail_msg: "Invalid admin email address"
      vars:
        admin_email: "[email protected]"

Connection Plugins

Connection plugins define how Ansible connects to target systems. They're crucial for cross-platform automation.

SSH Connection for Linux

# ansible.cfg
[defaults]
host_key_checking = False
remote_user = ubuntu
private_key_file = ~/.ssh/id_rsa

[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s
pipelining = True

---
- name: Linux automation via SSH
  hosts: linux_servers
  connection: ssh
  become: yes
  become_method: sudo
  tasks:
    - name: Update package cache
      ansible.builtin.apt:
        update_cache: yes
      when: ansible_os_family == 'Debian'

    - name: Install security updates
      ansible.builtin.package:
        name: "*"
        state: latest
      when: ansible_os_family == 'RedHat'

WinRM Connection for Windows

# inventory/group_vars/windows.yml
ansible_connection: winrm
ansible_winrm_transport: ntlm
ansible_winrm_server_cert_validation: ignore
ansible_winrm_port: 5986
ansible_user: Administrator
ansible_password: "{{ vault_windows_password }}"

---
- name: Windows automation via WinRM
  hosts: windows_servers
  connection: winrm
  tasks:
    - name: Install Windows updates
      ansible.windows.win_updates:
        category_names:
          - SecurityUpdates
          - CriticalUpdates
        state: installed
        reboot: yes

    - name: Configure PowerShell execution policy
      ansible.windows.win_shell: |
        Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine -Force

Real-World Cross-Platform Example

Let's combine modules and plugins in a comprehensive cross-platform deployment:

---
- name: Cross-platform web application deployment
  hosts: all
  vars:
    app_name: "mywebapp"
    app_version: "{{ lookup('env', 'APP_VERSION') | default('1.0.0') }}"
    app_config_url: "https://config.example.com/{{ app_name }}/{{ deployment_env }}.json"
    deployment_env: "{{ lookup('env', 'DEPLOY_ENV') | default('development') }}"
    
  tasks:
    # Pre-deployment validation using test plugins
    - name: Validate deployment prerequisites
      ansible.builtin.assert:
        that:
          - app_version is version('1.0.0', '>=')
          - deployment_env in ['development', 'staging', 'production']
          - ansible_python.version.major is version('3.6', '>=')
        fail_msg: "Deployment prerequisites not met"

    # Fetch configuration using lookup plugins
    - name: Fetch application configuration
      ansible.builtin.set_fact:
        app_config: "{{ lookup('url', app_config_url) | from_json }}"
      delegate_to: localhost
      run_once: true

    # Platform-specific package installation using modules
    - name: Install dependencies (Linux)
      ansible.builtin.package:
        name: "{{ app_config.dependencies.linux }}"
        state: present
      when: ansible_os_family != 'Windows'
      become: yes

    - name: Install dependencies (Windows)
      chocolatey.chocolatey.win_chocolatey:
        name: "{{ app_config.dependencies.windows }}"
        state: present
      when: ansible_os_family == 'Windows'

    # Create application directory using modules
    - name: Create application directory (Linux)
      ansible.builtin.file:
        path: "{{ app_config.paths.linux.app_dir }}"
        state: directory
        owner: "{{ app_config.user.linux }}"
        group: "{{ app_config.user.linux }}"
        mode: '0755'
      when: ansible_os_family != 'Windows'
      become: yes

    - name: Create application directory (Windows)
      ansible.windows.win_file:
        path: "{{ app_config.paths.windows.app_dir }}"
        state: directory
      when: ansible_os_family == 'Windows'

    # Deploy configuration using filter plugins for data transformation
    - name: Deploy application configuration
      ansible.builtin.template:
        src: app.conf.j2
        dest: "{{ app_config_path }}"
        backup: yes
      vars:
        app_config_path: "{{ app_config.paths.linux.config if ansible_os_family != 'Windows' else app_config.paths.windows.config }}"
        database_password: "{{ lookup('env', 'DB_PASSWORD') | default('defaultpass') }}"
        # Use filter plugins to transform database URL
        database_url: "{{ app_config.database.base_url | replace('HOSTNAME', app_config.database.host) | replace('PORT', app_config.database.port | string) }}"
      notify: 
        - restart application service

    # Service management using modules
    - name: Start application service (Linux)
      ansible.builtin.systemd:
        name: "{{ app_name }}"
        state: started
        enabled: yes
        daemon_reload: yes
      when: ansible_os_family != 'Windows'
      become: yes

    - name: Start application service (Windows)
      ansible.windows.win_service:
        name: "{{ app_name }}"
        state: started
        start_mode: auto
      when: ansible_os_family == 'Windows'

    # Health check using modules and test plugins
    - name: Wait for application to be ready
      ansible.builtin.uri:
        url: "{{ health_check_url }}"
        method: GET
        status_code: 200
      vars:
        health_check_url: "http://{{ ansible_default_ipv4.address if ansible_os_family != 'Windows' else ansible_ip_addresses[0] }}:{{ app_config.port }}/health"
      retries: 30
      delay: 10
      register: health_check
      until: health_check is succeeded

    # Generate deployment report using filter plugins
    - name: Generate deployment report
      ansible.builtin.copy:
        content: |
          Deployment Report
          =================
          Application: {{ app_name }}
          Version: {{ app_version }}
          Environment: {{ deployment_env }}
          Target: {{ inventory_hostname }}
          OS: {{ ansible_os_family }}
          Deployed at: {{ ansible_date_time.iso8601 }}
          
          Configuration:
          {{ app_config | to_nice_yaml }}
          
          Health Check: {{ health_check.status }} - {{ health_check.msg | default('OK') }}
        dest: "{{ report_path }}"
      vars:
        report_path: "{{ '/tmp/deployment-report.txt' if ansible_os_family != 'Windows' else 'C:\\temp\\deployment-report.txt' }}"
      delegate_to: localhost

  handlers:
    - name: restart application service
      ansible.builtin.systemd:
        name: "{{ app_name }}"
        state: restarted
      when: ansible_os_family != 'Windows'
      become: yes

    - name: restart application service
      ansible.windows.win_service:
        name: "{{ app_name }}"
        state: restarted
      when: ansible_os_family == 'Windows'

Advanced Plugin Usage Patterns

Custom Filter Plugin

Sometimes you need data transformations that don't exist in built-in filters:

# filter_plugins/custom_filters.py

def extract_domain(url):
    """Extract domain from URL"""
    from urllib.parse import urlparse
    return urlparse(url).netloc

def generate_password(length=12):
    """Generate a random password"""
    import string
    import random
    chars = string.ascii_letters + string.digits + "!@#$%^&*"
    return ''.join(random.choice(chars) for _ in range(length))

def bytes_to_human(bytes_value):
    """Convert bytes to human readable format"""
    for unit in ['B', 'KB', 'MB', 'GB', 'TB']:
        if bytes_value < 1024.0:
            return f"{bytes_value:.1f}{unit}"
        bytes_value /= 1024.0
    return f"{bytes_value:.1f}PB"

class FilterModule(object):
    """Custom Ansible filters"""
    
    def filters(self):
        return {
            'extract_domain': extract_domain,
            'generate_password': generate_password,
            'bytes_to_human': bytes_to_human
        }

Using custom filters:

---
- name: Using custom filter plugins
  hosts: localhost
  vars:
    api_endpoints:
      - "https://api1.example.com/v1/users"
      - "https://api2.example.com/v1/data"
      - "https://backup.example.com/api"
    
    disk_usage_bytes: 1073741824  # 1GB in bytes
  
  tasks:
    - name: Extract domains from API endpoints
      ansible.builtin.debug:
        msg: "API domains: {{ api_endpoints | map('extract_domain') | list }}"

    - name: Generate secure passwords for users
      ansible.builtin.debug:
        msg: "Generated password: {{ 'user123' | generate_password(16) }}"

    - name: Display disk usage in human readable format
      ansible.builtin.debug:
        msg: "Disk usage: {{ disk_usage_bytes | bytes_to_human }}"

Custom Lookup Plugin

Create a lookup plugin to fetch data from external APIs:

# lookup_plugins/api_lookup.py

from ansible.plugins.lookup import LookupBase
from ansible.errors import AnsibleError
import requests
import json

class LookupModule(LookupBase):
    """Lookup plugin to fetch data from REST APIs"""
    
    def run(self, terms, variables=None, **kwargs):
        ret = []
        
        for term in terms:
            try:
                # Parse the API URL and optional headers
                if isinstance(term, dict):
                    url = term.get('url')
                    headers = term.get('headers', {})
                    params = term.get('params', {})
                else:
                    url = term
                    headers = {}
                    params = {}
                
                # Make the API request
                response = requests.get(url, headers=headers, params=params)
                response.raise_for_status()
                
                # Parse JSON response
                data = response.json()
                ret.append(data)
                
            except requests.RequestException as e:
                raise AnsibleError(f"API request failed: {str(e)}")
            except json.JSONDecodeError as e:
                raise AnsibleError(f"Failed to parse JSON response: {str(e)}")
        
        return ret

Using custom lookup plugin:

---
- name: Using custom lookup plugin for API data
  hosts: localhost
  tasks:
    - name: Fetch user data from API
      ansible.builtin.set_fact:
        user_data: "{{ lookup('api_lookup', 'https://jsonplaceholder.typicode.com/users') }}"

    - name: Fetch specific user with parameters
      ansible.builtin.set_fact:
        specific_user: "{{ lookup('api_lookup', {'url': 'https://api.example.com/users', 'params': {'id': '123'}, 'headers': {'Authorization': 'Bearer ' + api_token}}) }}"
      vars:
        api_token: "{{ lookup('env', 'API_TOKEN') }}"

    - name: Process API data
      ansible.builtin.debug:
        msg: "Found {{ user_data | length }} users"

Performance and Best Practices

Module Performance Tips

1. Use appropriate modules: Choose the most specific module for your task

2. Batch operations: Use loops efficiently

3. Minimize network calls: Use modules that support bulk operations

---
- name: Performance optimization examples
  hosts: all
  tasks:
    # GOOD: Batch package installation
    - name: Install multiple packages efficiently
      ansible.builtin.package:
        name: "{{ packages }}"
        state: present
      vars:
        packages:
          - git
          - curl
          - wget
          - vim

    # AVOID: Individual package installation
    # - name: Install package one by one (slow)
    #   ansible.builtin.package:
    #     name: "{{ item }}"
    #     state: present
    #   loop:
    #     - git
    #     - curl
    #     - wget
    #     - vim

    # GOOD: Use copy module for multiple files
    - name: Deploy configuration files efficiently
      ansible.builtin.copy:
        src: "{{ item.src }}"
        dest: "{{ item.dest }}"
        mode: "{{ item.mode }}"
      loop:
        - { src: "app.conf", dest: "/etc/app/app.conf", mode: "0644" }
        - { src: "database.conf", dest: "/etc/app/db.conf", mode: "0600" }
        - { src: "logging.conf", dest: "/etc/app/log.conf", mode: "0644" }

Plugin Performance Tips

1. Cache lookup results: Avoid repeated expensive lookups

2. Use appropriate plugin types: Choose the right plugin for the job

3. Optimize filter chains: Order filters efficiently

---
- name: Plugin performance optimization
  hosts: all
  tasks:
    # GOOD: Cache expensive lookup results
    - name: Cache API data once
      ansible.builtin.set_fact:
        api_data: "{{ lookup('url', 'https://api.example.com/data') | from_json }}"
      run_once: true
      delegate_to: localhost

    - name: Use cached data in multiple tasks
      ansible.builtin.debug:
        msg: "Processing data for {{ item.name }}"
      loop: "{{ api_data.servers }}"

    # GOOD: Efficient filter chaining
    - name: Process data efficiently
      ansible.builtin.set_fact:
        active_servers: "{{ server_list | selectattr('status', 'equalto', 'active') | map(attribute='hostname') | sort | list }}"
      vars:
        server_list:
          - { hostname: "web1", status: "active" }
          - { hostname: "web2", status: "inactive" }
          - { hostname: "web3", status: "active" }

Troubleshooting and Debugging

Module Debugging

---
- name: Module debugging techniques
  hosts: all
  tasks:
    # Enable debug mode for modules
    - name: Test package installation with debug
      ansible.builtin.package:
        name: nonexistent-package
        state: present
      register: install_result
      ignore_errors: yes

    - name: Display module execution details
      ansible.builtin.debug:
        var: install_result
        verbosity: 2

    # Use check mode to test without changes
    - name: Test file creation in check mode
      ansible.builtin.file:
        path: /tmp/test-file
        state: touch
      check_mode: yes
      register: check_result

    - name: Show what would have changed
      ansible.builtin.debug:
        msg: "File would be {{ 'created' if check_result.changed else 'unchanged' }}"

Plugin Debugging

---
- name: Plugin debugging techniques
  hosts: localhost
  tasks:
    # Debug lookup plugin issues
    - name: Test lookup with error handling
      block:
        - name: Attempt file lookup
          ansible.builtin.set_fact:
            file_content: "{{ lookup('file', '/nonexistent/file.txt') }}"
      rescue:
        - name: Handle lookup failure
          ansible.builtin.debug:
            msg: "File lookup failed, using default content"
          
        - name: Set default content
          ansible.builtin.set_fact:
            file_content: "default content"

    # Debug filter plugin issues
    - name: Test filter with validation
      ansible.builtin.set_fact:
        processed_data: "{{ raw_data | from_json if raw_data is string else raw_data }}"
      vars:
        raw_data: '{"key": "value"}'

    # Validate filter results
    - name: Validate processed data
      ansible.builtin.assert:
        that:
          - processed_data is defined
          - processed_data is mapping
        fail_msg: "Data processing failed"

Common Pitfalls and Solutions

1. Module vs Plugin Confusion

Problem: Using the wrong component type for the task

# WRONG: Trying to use a lookup plugin as a module
- name: This won't work
  lookup:
    plugin: file
    path: /etc/hosts

# CORRECT: Using lookup plugin properly
- name: Read file content
  ansible.builtin.debug:
    msg: "{{ lookup('file', '/etc/hosts') }}"

2. Platform-Specific Module Issues

Problem: Using Linux-specific modules on Windows

# WRONG: Using systemd module on Windows
- name: Start service
  ansible.builtin.systemd:
    name: myservice
    state: started

# CORRECT: Platform-aware service management
- name: Start service (Linux)
  ansible.builtin.systemd:
    name: myservice
    state: started
  when: ansible_os_family != 'Windows'

- name: Start service (Windows)
  ansible.windows.win_service:
    name: myservice
    state: started
  when: ansible_os_family == 'Windows'

3. Plugin Data Type Issues

Problem: Incorrect data type handling in filters

# WRONG: Assuming data types
- name: Process data incorrectly
  ansible.builtin.debug:
    msg: "{{ user_count | int + 1 }}"  # Fails if user_count is not numeric

# CORRECT: Validate and convert data types
- name: Process data safely
  ansible.builtin.debug:
    msg: "{{ (user_count | int) + 1 if user_count is number else 'Invalid data' }}"

Conclusion

My journey from confusion to clarity with Ansible modules and plugins taught me that understanding the distinction between "what to do" (modules) and "how to enhance it" (plugins) is fundamental to mastering Ansible automation.

Key takeaways from this exploration:

1. Modules are your workers - They perform the actual tasks on target systems

2. Plugins are your enhancers - They extend and customize how Ansible operates

3. Combination is power - The real magic happens when you combine modules and plugins effectively

4. Platform awareness matters - Always consider cross-platform compatibility

5. Performance and maintainability - Choose the right tool for the job and optimize accordingly

Whether you're managing a few servers or orchestrating complex multi-platform infrastructure, mastering modules and plugins will transform your automation from basic scripts to sophisticated, maintainable solutions.

The beauty of Ansible lies not just in its simplicity, but in the depth of functionality that modules and plugins provide. Start with the basics, experiment with different combinations, and gradually build your expertise. Your future self (and your team) will thank you for investing time in understanding these fundamental concepts.

---

Have questions about Ansible modules and plugins or want to share your own automation experiences? Feel free to reach out through the comments below. Let's build better automation together!