Fix lỗi Ansible "ERROR! couldn't resolve module/action" — Module Not Found

Mô tả lỗi

Bạn chạy một Ansible playbook và nhận được thông báo:

ERROR! couldn't resolve module/action 'community.general.ufw'. This often indicates a misspelling, missing collection, or incorrect module path.

The error appears to be in '/home/user/playbooks/firewall.yml': line 12, column 7, but may
be elsewhere in the file depending on the exact syntax problem.

Hoặc phiên bản ngắn gọn hơn:

ERROR! couldn't resolve module/action 'docker_container'

Dù thế nào, playbook cũng dừng lại hoàn toàn. Không có gì chạy được.

Nguyên nhân

Từ Ansible 2.10 trở đi, nhiều module đã được tách ra khỏi gói core và chuyển vào các collection riêng biệt. Nếu bạn nâng cấp từ 2.9 hoặc lấy playbook từ một hướng dẫn cũ, module bạn đang gọi có thể nằm trong một collection chưa được cài đặt.

Ba nguyên nhân phổ biến nhất gây ra lỗi này:

• Collection chứa module chưa được cài đặt (ví dụ: community.general, community.docker, amazon.aws)
• Bạn đang dùng tên module ngắn như docker_container thay vì tên đầy đủ — FQCN — như community.docker.docker_container
• Ansible đang chạy từ một môi trường Python khác với nơi bạn đã cài collection

Cách 1: Cài collection bị thiếu

Đây là cách giải quyết cho khoảng 80% trường hợp. Đầu tiên, tìm xem module thuộc collection nào — kiểm tra Ansible Collections Index hoặc tìm kiếm cục bộ:

ansible-doc -l | grep docker_container

Sau đó cài đặt:

# Cài một collection đơn lẻ
ansible-galaxy collection install community.general

# community.docker bao gồm docker_container, docker_image, v.v.
ansible-galaxy collection install community.docker

# Các module AWS
ansible-galaxy collection install amazon.aws

# Cài nhiều collection cùng lúc
ansible-galaxy collection install community.general community.docker ansible.posix

Các module thường dùng và collection tương ứng:

• ufw, timezone, htpasswd, git_config → community.general
• docker_container, docker_image, docker_network → community.docker
• ec2, s3_bucket, rds_instance → amazon.aws
• postgresql_db, postgresql_user → community.postgresql
• mysql_db, mysql_user → community.mysql
• k8s, helm → kubernetes.core

Cách 2: Dùng tên đầy đủ FQCN

Tên module ngắn vẫn có thể thất bại trên Ansible 2.10+ dù đã cài collection. Cách an toàn nhất là chuyển sang FQCN ở mọi nơi:

# Trước (tên ngắn — không đáng tin cậy trên Ansible 2.10+)
- name: Quản lý tường lửa UFW
  ufw:
    rule: allow
    port: 22

# Sau (FQCN — luôn hoạt động)
- name: Quản lý tường lửa UFW
  community.general.ufw:
    rule: allow
    port: 22

Tương tự với Docker:

# Trước
- name: Khởi động container nginx
  docker_container:
    name: nginx
    image: nginx:latest
    state: started

# Sau
- name: Khởi động container nginx
  community.docker.docker_container:
    name: nginx
    image: nginx:latest
    state: started

Cách 3: Dùng requirements.yml để cài đặt nhất quán

Làm việc nhóm? Đừng trông chờ mọi người nhớ cài đúng collection. Hãy khai báo các dependency trong file requirements.yml và commit vào repo:

# requirements.yml
collections:
  - name: community.general
    version: ">=8.0.0"
  - name: community.docker
    version: ">=3.0.0"
  - name: amazon.aws
    version: ">=7.0.0"

Cài tất cả chỉ với một lệnh:

ansible-galaxy collection install -r requirements.yml

Thêm bước này vào đầu pipeline CI/CD, trước khi chạy bất kỳ playbook nào.

Cách 4: Sai môi trường Python/Ansible

Vẫn bị lỗi sau khi đã cài collection? Ansible có thể đang dùng một môi trường Python khác — nơi collection chưa được cài.

# Xem file thực thi ansible đang dùng là file nào
which ansible

# Liệt kê các collection đã cài và đường dẫn
ansible-galaxy collection list

# Dùng virtualenv? Kích hoạt trước, rồi cài lại
source /path/to/venv/bin/activate
ansible-galaxy collection install community.general

Mặc định, collection được cài vào một trong các vị trí sau:

• ~/.ansible/collections/ — theo từng user
• /usr/share/ansible/collections/ — toàn hệ thống
• ./collections/ — theo project (khi cấu hình trong ansible.cfg)

Cần cài toàn hệ thống? Thêm sudo:

sudo ansible-galaxy collection install community.general

Cách 5: Kiểm tra lỗi chính tả tên module

Cài collection cũng không giải quyết được nếu tên module bị gõ sai. Hãy kiểm tra lại tên chính xác:

# Tìm kiếm module theo từ khóa
ansible-doc -l | grep -i postgres

# Xem tài liệu đầy đủ của một module cụ thể
ansible-doc community.postgresql.postgresql_db

Kiểm tra kết quả

Trước khi chạy playbook thật, hãy kiểm tra cú pháp trước:

ansible-playbook playbook.yml --syntax-check

Đầu ra bình thường trông như thế này:

playbook: playbook.yml

Không có lỗi. Sau đó chạy thử để phát hiện thêm vấn đề:

ansible-playbook playbook.yml --check

Xác nhận collection đã được cài đúng:

ansible-galaxy collection list | grep community.general
# community.general    9.1.0

Phòng tránh

• Dùng FQCN trong mọi playbook — rõ ràng và không bị phá vỡ khi nâng cấp Ansible
• Luôn có file requirements.yml trong mỗi project Ansible và commit vào version control
• Ghim phiên bản collection trong requirements.yml — cách đơn giản nhất để tránh lỗi âm thầm khi nâng cấp
• Trong CI/CD, chạy ansible-galaxy collection install -r requirements.yml trước khi thực thi bất kỳ playbook nào
• Nâng cấp qua ranh giới 2.9 → 2.10? Hãy rà soát playbook để tìm các module đã chuyển sang collection