Vấn đềBạn đã dành ba mươi phút để viết một truy vấn JMESPath hoàn hảo nhằm phân tích phản hồi JSON dài 500 dòng từ một API đám mây. Bạn chạy playbook của mình, nhưng thay vì nhận được dữ liệu mong đợi, tác vụ thất bại ngay lập tức với một lỗi phụ thuộc gây khó chịu:
The task includes an option with an undefined variable. The error was: 'json_query' filter requires 'jmespath' to be installed on the Ansible controller
Lỗi này thường xảy ra ngay sau khi thiết lập một máy điều khiển (control node) mới hoặc chuyển sang một CI/CD runner mới. Mặc dù thông báo lỗi nêu rõ nội dung còn thiếu, giải pháp sẽ tùy thuộc vào cách bạn quản lý môi trường Python của mình.
Tại sao lỗi này xảy raAnsible giữ cho bản cài đặt cốt lõi gọn nhẹ bằng cách không đi kèm mọi thư viện có thể. Bộ lọc json_query thực chất là một trình bao bọc (wrapper) cho JMESPath, một ngôn ngữ truy vấn mạnh mẽ cho JSON. Vì Ansible là một ứng dụng Python, nó cần thư viện này được cài đặt trong cùng một môi trường Python hiện đang chạy mã nguồn Ansible core của bạn.
Quan trọng là thư viện này phải nằm trên Máy điều khiển Ansible (Ansible Controller)—máy mà bạn thực thi lệnh ansible-playbook. Bạn không cần cài đặt nó trên các máy chủ được quản lý từ xa. Nếu bạn sử dụng một công cụ như GitHub Actions, phần phụ thuộc này phải là một phần trong môi trường của runner đó.
Hướng dẫn sửa lỗi từng bước### Cách 1: Cài đặt qua Pip (Tiêu chuẩn)Nếu bạn đã cài đặt Ansible bằng pip, đây thường là cách khắc phục nhanh nhất. Đầu tiên, hãy kiểm tra phiên bản Python mà bản cài đặt Ansible của bạn đang sử dụng:
ansible --version | grep "python version"
Sau khi có phiên bản, hãy cài đặt thư viện. Đối với thiết lập Python 3 tiêu chuẩn, hãy sử dụng:
pip3 install jmespath
Nếu bạn đang quản lý nhiều phiên bản Python, bạn có thể cần sử dụng python3 -m pip install jmespath để đảm bảo nó được cài đặt vào đúng thư mục site-packages.
Cách 2: Làm việc với Môi trường ảo (Virtual Environments)Các quy trình làm việc chuyên nghiệp thường sử dụng môi trường ảo (venv) để ngăn chặn xung đột gói. Việc cài đặt toàn cục sẽ không có tác dụng nếu Ansible đang chạy bên trong một môi trường cô lập. Hãy kích hoạt môi trường của dự án trước:
source /opt/ansible-venv/bin/activate
pip install jmespath
Nếu bạn không chắc chắn tệp thực thi Ansible nằm ở đâu, hãy chạy lệnh which ansible. Nếu đường dẫn trỏ đến một thư mục bên trong thư mục dự án của bạn, gần như chắc chắn bạn đang sử dụng môi trường ảo.
Cách 3: Trình quản lý gói hệ thốngQuản trị viên Linux thường thích sử dụng apt hoặc dnf để giữ cho các phần phụ thuộc ổn định trên toàn bộ hệ điều hành.
Dành cho Ubuntu hoặc Debian:
sudo apt update
sudo apt install python3-jmespath
Dành cho RHEL, CentOS, hoặc Fedora:
sudo dnf install python3-jmespath
Xác minh: Kiểm tra nhanhĐừng đợi playbook chạy mất 10 phút mới biết cách sửa lỗi có hiệu quả hay không. Sử dụng lệnh ad-hoc một dòng này để kiểm tra bộ lọc trên máy cục bộ của bạn:
ansible localhost -m debug -a "msg={{ {'status': 'active'} | json_query('status') }}"
Kết quả mong đợi:
localhost | SUCCESS => {
"msg": "active"
}
Nếu bạn thấy "msg": "active", phần phụ thuộc đã được ánh xạ chính xác. Nếu lỗi vẫn còn, hãy kiểm tra xem bạn có vô tình cài đặt jmespath cho Python 2.7 trong khi Ansible đang chạy trên phiên bản 3.10+ hay không.
Mẹo chuyên nghiệp để lọc JSONViệc gỡ lỗi các truy vấn phức tạp bên trong playbook rất chậm. Nếu truy vấn của bạn trả về dữ liệu sai, Ansible thường đưa ra lỗi "undefined variable" (biến không xác định) chung chung, che giấu vấn đề cú pháp thực sự.
Trước khi áp dụng logic vào một tác vụ, tôi sử dụng JSON Formatter & Validator tại ToolCraft để trực quan hóa cấu trúc. Tôi đã lãng phí hàng giờ cho các bộ lọc chỉ để nhận ra rằng API trả về một danh sách lồng nhau thay vì một đối tượng phẳng. Sử dụng công cụ cục bộ hoặc trên trình duyệt nhanh hơn nhiều so với việc chạy playbook hai mươi lần chỉ để tìm một dấu chấm còn thiếu trong truy vấn. Nếu bạn đang chuyển đổi các tệp cấu hình cũ, YAML to JSON Converter có thể giúp bạn thấy chính xác các biến của mình sẽ trông như thế nào đối với bộ máy JMESPath.