Bí ẩn: Đã cài đặt nhưng lại bị thiếu
Bạn đã làm mọi thứ đúng theo hướng dẫn. Bạn đã tạo một file requirements.yml, liệt kê các dependency của mình và kích hoạt quá trình cài đặt. Đầu ra terminal có thể hiển thị một loạt văn bản màu xanh lá cây hài lòng xác nhận rằng các role đã được tải xuống thành công. Nhưng ngay khi bạn chạy playbook, Ansible lại ném vào mặt bạn một thông báo lỗi màu đỏ đầy khó chịu:
ERROR! the role 'geerlingguy.nginx' was not found in /etc/ansible/roles:/root/.ansible/roles:/usr/share/ansible/roles
Cảm giác như Ansible đang hoàn toàn phớt lờ nỗ lực của bạn. Vấn đề thường không phải là do cài đặt thất bại. Thay vào đó, nó hầu như luôn là một sự đứt gãy trong giao tiếp: ansible-galaxy đã đặt role vào một thư mục, nhưng ansible-playbook lại đang tìm kiếm ở một nơi hoàn toàn khác.
Cách gỡ lỗi đường dẫn tìm kiếm
Bắt đầu bằng cách kiểm tra "Search Path" (Đường dẫn tìm kiếm) được liệt kê trong thông báo lỗi đó. Trong ví dụ trên, Ansible đã kiểm tra chính xác ba vị trí hệ thống. Nếu role của bạn không nằm trong một trong ba vị trí đó, playbook sẽ thất bại mọi lúc.
Các role thường nằm trong ~/.ansible/roles nếu bạn cài đặt chúng với tư cách người dùng tiêu chuẩn. Tuy nhiên, nếu bạn chuyển sang sudo để chạy playbook, Ansible sẽ chuyển hướng tìm kiếm sang thư mục chính của người dùng root. Sự sai lệch này chịu trách nhiệm cho khoảng 80% lỗi 'role not found' trong môi trường phát triển cục bộ. Ngược lại, nếu bạn cài đặt các role cục bộ vào dự án của mình nhưng không cập nhật cấu hình, Ansible sẽ không biết để tìm kiếm ở đó.
Kiểm tra kỹ những gì Ansible thực sự nhìn thấy
Chạy lệnh này để xem các role nào đang hoạt động và chúng nằm ở đâu trên đĩa của bạn:
ansible-galaxy role list
geerlingguy.nginx có xuất hiện trong danh sách không? Nếu nó bị thiếu hoặc đường dẫn có vẻ sai, bạn đã xác định được nguyên nhân gốc rễ.
Giải pháp từng bước
Cách 1: Ép buộc các Role vào thư mục dự án
Giữ các dependency bên trong thư mục dự án của bạn. Đây là cách đáng tin cậy nhất để quản lý một môi trường cộng tác. Thay vì dựa vào các đường dẫn hệ thống toàn cục, hãy yêu cầu Galaxy đưa mọi thứ vào thư mục roles/ cục bộ.
ansible-galaxy install -r requirements.yml -p ./roles
Flag -p (hoặc --roles-path) là người bạn tốt nhất của bạn ở đây. Nó đảm bảo các role nằm chính xác ở nơi mà hầu hết các playbook mong đợi: trong một thư mục con ngay cạnh các file YAML của bạn.
Cách 2: Tinh chỉnh file ansible.cfg của bạn
Có thể bạn thích một thư mục chia sẻ cho nhiều dự án. Nếu vậy, bạn phải cho Ansible biết thư mục đó nằm ở đâu. Tạo hoặc chỉnh sửa file ansible.cfg trong thư mục gốc của dự án và thêm các dòng sau:
[defaults]
roles_path = ./roles:~/.ansible/roles:/usr/share/ansible/roles
Cấu hình này tạo ra một danh sách ưu tiên. Ansible sẽ kiểm tra thư mục cục bộ của dự án trước, sau đó là thư mục cá nhân của người dùng và cuối cùng là đường dẫn toàn hệ thống. Đây thường là "mắt xích còn thiếu" giúp giải quyết dứt điểm lỗi này.
Cách 3: Cẩn thận với việc sai lệch tên gọi
Lỗi cú pháp trong requirements.yml cũng có thể gây ra rắc rối này. Nếu bạn chỉ định một tên tùy chỉnh cho một role, bạn phải sử dụng chính xác tên đó trong playbook của mình, không phải tên nguồn ban đầu.
Ví dụ về một thiết lập gây nhầm lẫn:
# requirements.yml
- src: geerlingguy.nginx
name: my_custom_nginx
Trong trường hợp này, việc gọi roles: [geerlingguy.nginx] sẽ bị lỗi. Thay vào đó, bạn sẽ cần sử dụng roles: [my_custom_nginx].
Xác minh bản sửa lỗi
Sau khi áp dụng bản sửa lỗi, hãy xác nhận rằng các đường dẫn đã khớp nhau. Chạy lại lệnh liệt kê:
ansible-galaxy list
Giờ đây, bạn sẽ thấy thư mục roles của dự án trong kết quả đầu ra. Để kiểm tra kỹ lần cuối, hãy chạy playbook của bạn với flag syntax để đảm bảo tất cả các dependency đã được giải quyết:
ansible-playbook site.yml --syntax-check
Nếu bạn thấy kết quả thoát thành công, bạn đã sẵn sàng để triển khai.
Mẹo chuyên nghiệp và thực hành tốt nhất
Để luôn chủ động trước các vấn đề này, hãy luôn commit file ansible.cfg vào kho lưu trữ Git của bạn. Điều này đảm bảo mọi nhà phát triển trong nhóm của bạn đều tự động sử dụng cùng một đường dẫn tìm kiếm, ngăn chặn tranh cãi kinh điển "nó chạy tốt trên máy của tôi".
Khi làm việc với các hệ thống bị hạn chế hoặc không có mạng (air-gapped), bạn có thể phải di chuyển các role thủ công dưới dạng file nén tarball. Các file có thể dễ dàng bị hỏng trong quá trình truyền tải này. Tôi khuyên bạn nên sử dụng một Trình tạo mã băm để kiểm tra mã kiểm tra SHA-256 của gói role trước khi bạn giải nén nó. Đó là một bước thực hiện trong 30 giây giúp ngăn chặn hàng giờ gỡ lỗi cho một bản cài đặt bị hỏng.
Bài học rút ra
- **Đường dẫn rất lắt léo:** `ansible-galaxy` và `ansible-playbook` không phải lúc nào cũng chia sẻ cùng một thư mục mặc định, đặc biệt là khi có liên quan đến `sudo`.
- **Local tốt hơn:** Lưu trữ các role trong `./roles` giúp quá trình tự động hóa của bạn linh hoạt và dễ dự đoán hơn.
- **Cấu hình là chìa khóa:** Sử dụng `ansible.cfg` để xác định rõ ràng `roles_path` của bạn và loại bỏ việc phỏng đoán.