Ansible Troubleshooting — Deprecated Module Usage (Rule 105)

Introduction

Ansible-lint rule 105 (deprecated-module) flags modules that are no longer actively maintained and scheduled for removal. Using deprecated modules means you're building on code that won't receive security patches, bug fixes, or compatibility updates — and will eventually break when the module is removed.

The Error

- name: Configure VLAN
  ansible.netcommon.net_vlan:  # ← Deprecated
    vlan_id: 20

$ ansible-lint playbook.yml
deprecated-module: Using deprecated module 'ansible.netcommon.net_vlan'.

Common Deprecated Modules and Replacements

How to Find Replacements

Check Module Documentation

# Ansible docs show deprecation notice and replacement
ansible-doc ansible.netcommon.net_vlan
# DEPRECATED - use platform-specific modules instead

Check the Ansible Module Index

The Ansible module index lists all modules with their status (deprecated, removed, or active).

Use ansible-lint --fix

For some rules, ansible-lint can auto-fix:

ansible-lint --fix playbook.yml

This works for FQCN migration and some module renames.

Fix Examples

Example 1: Network Module

# ❌ Deprecated
- name: Configure VLAN
  ansible.netcommon.net_vlan:
    vlan_id: 20

# ✅ Platform-specific replacement
- name: Configure VLAN
  cisco.ios.ios_vlans:
    config:
      - vlan_id: 20
        name: management
        state: active

Example 2: include → include_tasks

# ❌ Deprecated
- include: tasks/setup.yml

# ✅ Replacement
- ansible.builtin.include_tasks: tasks/setup.yml

Example 3: Docker Module Migration

# ❌ Old location
- community.general.docker_container:
    name: myapp
    image: myapp:latest

# ✅ New collection
- community.docker.docker_container:
    name: myapp
    image: myapp:latest

Install the new collection:

ansible-galaxy collection install community.docker

Bulk Find Deprecated Modules

Scan All Playbooks

# Find all deprecated module usage across your project
ansible-lint -t deprecated-module roles/ playbooks/

# Or grep for known deprecated modules
grep -rn "net_vlan\|net_interface\|net_l3_interface" roles/

Check Collection Versions

# List installed collections with versions
ansible-galaxy collection list

# Update all collections
ansible-galaxy collection install -r requirements.yml --force

Migration Checklist

1. Run ansible-lint to identify all deprecated modules
2. Check docs for each deprecated module's replacement
3. Install new collections if replacements are in different collections
4. Update playbooks with new module names and parameters
5. Test — parameter names may differ between old and new modules
6. Update requirements.yml with new collection dependencies
7. Pin collection versions for reproducible builds

Suppressing the Rule (Temporary)

If you need time to migrate:

# Per-task skip
- name: Legacy VLAN config (migrating soon)
  ansible.netcommon.net_vlan:  # noqa: deprecated-module
    vlan_id: 20

# In .ansible-lint (project-wide)
warn_list:
  - deprecated-module  # TODO: migrate by Q2 2026

Related Articles

• Ansible-Lint Guide
• literal-compare Rule (601)
• syntax-check Rule (911)
• Ansible Galaxy Guide
• Ansible Best Practices Guide

Conclusion

Replace deprecated modules immediately — they receive no security patches and will be removed in future Ansible releases. Check ansible-doc <module> for replacement guidance, install new collections with ansible-galaxy, and run ansible-lint regularly to catch deprecations early. Use warn_list in .ansible-lint only as a temporary measure while migrating.