問題の概要
デプロイの準備は万端なのに、ansible-galaxy で足止めを食らってしまうことがあります。このエラーは通常、Ansible を動かしている Python 環境が Galaxy サーバーの SSL 証明書を検証できないときに発生します。セキュリティは最優先事項ですが、ローカルの証明書チェーンにリンクが欠けていると、ハンドシェイクが失敗してしまいます。
ターミナルには通常、以下のようなエラーが表示されます。
ERROR! Unknown error when attempting to call Galaxy: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1123)>
要約：とりあえず今すぐ解決したい場合のワークアラウンド
安全なローカルのサンドボックス環境で作業しており、すぐにチェックをバイパスする必要がある場合は、--ignore-certs フラグを使用します。これはクイックフィックスであり、本番環境向けの恒久的な解決策ではありません。
ansible-galaxy collection install community.general --ignore-certs
フラグを毎回入力せずにセッション全体に適用するには、以下の環境変数をエクスポートします。
export ANSIBLE_GALAXY_IGNORE_CERTS=True
なぜこのエラーが発生するのか？
Ansible はコンテンツの取得に Python の urllib または requests ライブラリを使用しています。Python 3.6 以降、これらのライブラリは証明書チェーンの検証が非常に厳格になりました。主な原因として、以下の3つのいずれかが考えられます。
- OS の証明書が古い: ローカルの
ca-certificatesパッケージが数ヶ月間更新されておらず、galaxy.ansible.comが使用している新しい CA（認証局）を認識できていない。 - 企業によるインターセプト: 多くの企業では、Zscaler や Blue Coat などのプロキシを介して「ディープ・パケット・インスペクション」を行っています。これらのサービスは、実際の Galaxy 証明書を、お使いのマシンがまだ信頼していない自己署名の企業用証明書に置き換えます。
- macOS の隔離環境: 公式の macOS 用
.pkgインストーラーでインストールされた Python バージョンは、システムのキーチェーンを完全に無視することがよくあります。
ステップバイステップの解決策
1. Linux の証明書ストアを更新する
Linux ディストリビューションでは、信頼されたルート認証局を定期的に更新する必要があります。サーバーや WSL インスタンスでまず最初に試すべき方法です。
Ubuntu/Debian:
sudo apt-get update
sudo apt-get install --reinstall ca-certificates
sudo update-ca-certificates
CentOS/RHEL 8 & 9:
sudo dnf upgrade ca-certificates
sudo update-ca-trust
2. macOS の Python 証明書スクリプトを実行する
Python がシステムのルート証明書に自動的にリンクしないため、macOS ユーザーはこの問題によく遭遇します。アプリケーションフォルダ内を確認してください。Python には、この問題を解決するための特定のコマンドスクリプトが付属しています。
# まずバージョンを確認してください。この例では 3.12 を使用しています
/Applications/Python\ 3.12/Install\ Certificates.command
あるいは、OS よりも頻繁に更新される certifi バンドルを Python に強制的に使用させることもできます。
pip install --upgrade certifi
3. 企業の CA バンドルを注入する
企業のファイアウォールの内側にいる場合は、会社のルート証明書がどこにあるかを Ansible に正確に伝える必要があります。IT チームに company-root-ca.pem ファイルを依頼してください。ファイルを入手したら、環境変数をそのパスに指定します。
export REQUESTS_CA_BUNDLE=/etc/pki/tls/certs/corporate-proxy-ca.pem
export SSL_CERT_FILE=/etc/pki/tls/certs/corporate-proxy-ca.pem
ansible-galaxy collection install community.aws
4. ansible.cfg で設定を恒久化する
変数をエクスポートするのに疲れましたか？設定をプロジェクトに直接組み込むことができます。ansible.cfg ファイルを開き、以下のセクションを追加してください。
[galaxy]
ignore_certs = True
警告: ignore_certs = True を使用するのは、既知の安全な内部ネットワークにいる場合のみにしてください。公共の Wi-Fi などで検証を無効にすると、中間者攻撃（MITM）の格好の標的になります。
接続の確認
詳細ログを表示してインストールを実行し、修正が機能したか確認します。-vvv フラグを使用すると、呼び出されている URL や、接続がどこで停滞しているかを正確に確認できます。
ansible-galaxy collection install community.general -vvv
また、この Python のワンライナーを実行して、生の接続をテストすることもできます。200 が返ってくれば、SSL パスは正常です。
python3 -c "import urllib.request; print(urllib.request.urlopen('https://galaxy.ansible.com').getcode())"
まとめ
CERTIFICATE_VERIFY_FAILED エラーはバグではなく、セキュリティ機能です。--ignore-certs は 10 秒で済むクイックフィックスとして機能しますが、プロフェッショナルなアプローチは ca-certificates を更新するか、企業の CA をマッピングすることです。証明書ストアを最新の状態に保つことで、自動化の機能性とセキュリティの両方を維持できます。