Cách sửa lỗi Ansible: couldn't resolve module/action 'community.general.docker_container'

Tại sao lỗi này xảy ra

Ansible đã thay đổi cách xử lý các module kể từ phiên bản 2.10. Trước đây, Ansible là một công cụ "batteries-included" (tích hợp sẵn mọi thứ) nơi mọi module đều được cài đặt sẵn. Hiện nay, nó sử dụng một mô hình phi tập trung gọi là Collections. Nếu bạn gặp lỗi này, môi trường cục bộ của bạn đang thiếu gói cụ thể chứa các module Docker.

Lỗi ERROR! couldn't resolve module/action 'community.general.docker_container' thường có nghĩa là collection community.general không nằm trong đường dẫn tìm kiếm của bạn. Nó có thể chưa được cài đặt, hoặc Ansible đang tìm kiếm sai thư mục.

Các nguyên nhân phổ biến

• Thiếu Collection: Bạn chưa chạy lệnh cài đặt ansible-galaxy.
• Sai lệch đường dẫn: Collection được cài đặt trong ~/.ansible/collections, nhưng cấu hình của bạn lại trỏ đi nơi khác.
• Xung đột môi trường ảo: Bạn đã cài đặt collection trong Python của hệ thống, nhưng bạn lại đang chạy playbook bên trong một venv.
• Thay đổi Namespace: Mặc dù nhiều module Docker nằm trong community.general, một số đã được chuyển sang community.docker.

Các bước khắc phục

1. Cài đặt Collection thủ công

Cách khắc phục nhanh nhất là tải collection trực tiếp từ registry của Ansible Galaxy. Mở terminal và chạy:

ansible-galaxy collection install community.general

Vì các module Docker thường xuyên được cập nhật, bạn cũng có thể muốn cài đặt collection Docker cụ thể để tránh các vấn đề về phân giải trong tương lai:

ansible-galaxy collection install community.docker

2. Sử dụng tệp requirements.yml

Quản lý các phụ thuộc một cách thủ công sẽ tiềm ẩn rủi ro cho các dự án nhóm. Thay vào đó, hãy sử dụng tệp requirements.yml trong thư mục gốc của dự án để theo dõi các phiên bản. Điều này đảm bảo mọi người trong nhóm đều sử dụng cùng một môi trường.

Tạo requirements.yml với nội dung sau:

---
collections:
  - name: community.general
    version: 8.2.0
  - name: community.docker
    version: 3.10.0

Cài đặt tất cả cùng lúc bằng cách sử dụng cờ -r:

ansible-galaxy collection install -r requirements.yml

3. Kiểm tra đường dẫn Collection của bạn

Đôi khi các tệp đã có sẵn, nhưng Ansible lại tìm kiếm sai chỗ. Theo mặc định, Ansible tìm kiếm trong ~/.ansible/collections và /usr/share/ansible/collections. Kiểm tra cấu hình hiện tại của bạn bằng cách chạy:

ansible --version

Tìm dòng configured module search path. Nếu bạn muốn giữ các collection bên trong thư mục dự án (ví dụ: trong thư mục ./collections), hãy cập nhật tệp ansible.cfg của bạn:

[defaults]
collections_path = ./collections:~/.ansible/collections:/usr/share/ansible/collections

4. Xử lý môi trường ảo Python

Môi trường ảo (venv) thường gây ra sự nhầm lẫn về đường dẫn. Nếu bạn sử dụng venv, hãy đảm bảo bạn cài đặt các collection khi môi trường đó đang hoạt động. Một lỗi phổ biến là sử dụng tệp thực thi ansible-galaxy của hệ thống để cài đặt module cho một lần chạy ansible-playbook dựa trên venv.

Để an toàn, hãy gọi công cụ galaxy thông qua cú pháp module Python để đảm bảo nó tác động đúng vào môi trường:

python3 -m ansible galaxy collection install community.general

Xác nhận khắc phục

Kiểm tra xem Ansible đã nhận dạng được module chưa. Liệt kê tất cả các collection đã cài đặt bằng lệnh này:

ansible-galaxy collection list

Nếu community.general xuất hiện trong danh sách, hãy thử một bài kiểm tra ad-hoc nhanh. Chạy lệnh này để xem Ansible có thể lấy tài liệu của module hay không:

ansible localhost -m community.general.docker_container --help

Nếu bạn thấy một loạt văn bản hướng dẫn thay vì thông báo lỗi, bạn đã sẵn sàng.

Mẹo khắc phục sự cố nâng cao

• Sử dụng FQCN: Luôn sử dụng Tên Collection Đầy đủ (Fully Qualified Collection Name). Hãy viết community.general.docker_container thay vì chỉ docker_container. Điều này giúp ngăn chặn xung đột tên gọi.
• Kiểm tra quyền hạn: Nếu bạn đã sử dụng sudo để cài đặt Ansible, bạn có thể cần sudo để cài đặt các collection trên toàn hệ thống. Tuy nhiên, tốt hơn là nên cài đặt chúng ở cấp độ người dùng để tránh các rắc rối về quyền hạn.
• Hệ thống không có mạng (Air-Gapped): Nếu máy chủ của bạn không có internet, hãy tải xuống tệp .tar.gz từ trang web Galaxy. Cài đặt cục bộ bằng lệnh ansible-galaxy collection install ./my-collection.tar.gz.