問題の発生クラウドAPIからの500行に及ぶJSONレスポンスを解析するために、30分かけて完璧なJMESPathクエリを作成したとしましょう。しかし、プレイブックを実行すると、期待したデータが得られる代わりに、イライラさせる依存関係エラーでタスクが即座に失敗してしまいます。
タスクに未定義の変数を含むオプションが含まれています。エラー内容：'json_query' フィルタを使用するには、Ansible コントローラーに 'jmespath' がインストールされている必要があります。
このエラーは通常、新しいコントロールノードをセットアップした直後や、新しいCI/CDランナーに移行した際に発生します。不足しているものはメッセージで明確に示されていますが、解決策はPython環境をどのように管理しているかによって異なります。
発生理由Ansibleはコアのインストールを軽量に保つため、すべてのライブラリを同梱しているわけではありません。json_queryフィルタは、実際にはJSON用の強力なクエリ言語であるJMESPathのラッパーです。AnsibleはPythonアプリケーションであるため、現在Ansibleコアコードを実行しているのと同じPython環境にこのライブラリがインストールされている必要があります。
重要なのは、このライブラリがAnsibleコントローラー（ansible-playbookコマンドを実行するマシン）に存在しなければならないという点です。リモートの管理対象サーバーにインストールする必要はありません。GitHub Actionsのようなツールを使用している場合は、そのランナーの環境にこの依存関係が含まれている必要があります。
ステップバイステップの解決策### 方法1：Pipによるインストール（標準的）Ansibleをpipでインストールした場合は、通常これが最も早い解決策です。まず、Ansibleのインストールで現在使用されているPythonのバージョンを確認します。
ansible --version | grep "python version"
バージョンを確認したら、ライブラリをインストールします。標準的なPython 3のセットアップでは、以下を使用します。
pip3 install jmespath
複数のPythonバージョンを管理している場合は、正しいsite-packagesディレクトリにインストールされるよう、python3 -m pip install jmespathを使用する必要があるかもしれません。
方法2：仮想環境（venv）での作業プロフェッショナルのワークフローでは、パッケージの競合を防ぐために仮想環境（venv）を使用することがよくあります。Ansibleが隔離された環境で実行されている場合、グローバルへのインストールは効果がありません。まずプロジェクトの環境をアクティブ化してください。
source /opt/ansible-venv/bin/activate
pip install jmespath
Ansibleバイナリがどこにあるかわからない場合は、which ansibleを実行してください。パスがプロジェクトディレクトリ内のフォルダを指しているなら、ほぼ間違いなく仮想環境を使用しています。
方法3：システムパッケージマネージャLinux管理者は、OS全体で依存関係の安定性を保つために、aptやdnfを使用することを好む場合があります。
UbuntuまたはDebianの場合：
sudo apt update
sudo apt install python3-jmespath
RHEL、CentOS、またはFedoraの場合：
sudo dnf install python3-jmespath
検証：クイックチェック修正が機能したかどうかを確認するために、10分かかるプレイブックの実行を待つ必要はありません。この1行のアドホックコマンドを使用して、ローカルマシンに対してフィルタをテストします。
ansible localhost -m debug -a "msg={{ {'status': 'active'} | json_query('status') }}"
期待される出力：
localhost | SUCCESS => {
"msg": "active"
}
"msg": "active"と表示されれば、依存関係は正しくマッピングされています。エラーが解消されない場合は、AnsibleがPython 3.10+で動作しているのに、誤ってPython 2.7用にjmespathをインストールしていないか確認してください。
JSONフィルタリングのプロの技プレイブック内での複雑なクエリのデバッグは時間がかかります。クエリが間違ったデータを返す場合、Ansibleはしばしば一般的な「undefined variable（未定義の変数）」エラーをスローし、真の構文問題を隠してしまいます。
タスクにロジックを組み込む前に、私はToolCraftのJSON Formatter & Validatorを使用して構造を視覚化しています。フィルタに何時間も費やした挙げ句、APIがフラットなオブジェクトではなくネストされたリストを返していたことに気づく、といった失敗を避けるためです。プレイブックを20回実行してクエリ内のドットの欠落を探すよりも、ローカルやブラウザベースのツールを使用する方がはるかに高速です。 レガシーな設定ファイルを変換している場合は、YAML to JSON Converterを使用すると、変数がJMESPathエンジンからどのように見えるかを正確に把握できます。