Ansible Vaultの「vault password file not found」エラーを修正する

エラーの内容

vault暗号化された変数を使ってプレイブックを実行すると、突然こんなエラーが出ます：

ERROR! The vault password file /path/to/.vault_pass was not found or is not readable

このエラーは、新しいマシンにリポジトリをクローンした後、CI/CDを設定したとき、あるいは間違ったディレクトリからプレイブックを実行したときによく発生します。昨日は問題なく動いていたのに、今日はダメ。デバッグの手順を紹介します。

デバッグの手順

1. Ansibleがvaultパスワードファイルをどこで探しているか確認する

パスは3つの異なる場所から来ている可能性があります。この順番で確認してください：

カレントディレクトリまたはホームディレクトリにあるansible.cfg
ANSIBLE_VAULT_PASSWORD_FILE環境変数
--vault-password-file CLIフラグ

# ansible.cfgを確認
grep -r vault_password_file ansible.cfg ~/.ansible.cfg /etc/ansible/ansible.cfg 2>/dev/null

# 環境変数を確認
echo $ANSIBLE_VAULT_PASSWORD_FILE

2. そのパスにファイルが実際に存在するか確認する

ls -la /path/to/.vault_pass

No such file or directoryと表示された場合、ファイルが本当に存在しません — このマシンで作成されていないか、削除されたか、パスが間違っています。

ファイルは存在するのにエラーが続く場合は、パーミッションの問題です：

stat /path/to/.vault_pass
# "Access"の行を確認 — ansibleを実行するユーザーが読み取れる必要があります

3. 相対パスの問題かどうか確認する

よくある落とし穴があります。ansible.cfgにvault_password_file = .vault_passのような相対パスが設定されている場合、Ansibleは設定ファイルの場所ではなく、カレントワーキングディレクトリを基準にパスを解決します。別のディレクトリからプレイブックを実行すると、動かなくなります。

# 失敗 — 親ディレクトリから実行している場合
cd /home/user
ansible-playbook myproject/site.yml

# 成功 — .vault_passが存在するプロジェクトルートから実行
cd /home/user/myproject
ansible-playbook site.yml

解決策

解決策1: 不足しているvaultパスワードファイルを作成する

新しいマシンや新たにクローンしたリポジトリでは、ファイルが存在しないことがほとんどです。再作成する必要があります。vaultパスワードファイルはプレーンテキストで、1行にパスワードだけを記載します。

# ファイルを作成
echo 'your_vault_password_here' > ~/.vault_pass

# 権限を制限 — オーナーだけが読み取れるようにする
chmod 600 ~/.vault_pass

パスワードは、vaultの暗号化に使用したものと一致している必要があります。忘れてしまった場合、データは復元できません。これはvaultが意図どおりに機能している証拠です。

解決策2: パーミッションを修正する

ファイルは存在するが、Ansibleがまだ読み取れない場合：

# 所有権とパーミッションを修正
chown $USER ~/.vault_pass
chmod 600 ~/.vault_pass

# 確認
ls -la ~/.vault_pass
# 表示例: -rw------- 1 youruser yourgroup ...

解決策3: ansible.cfgに絶対パスを使用する

絶対パスに切り替えることで、「どのディレクトリにいるか」という問題を完全に解消できます：

[defaults]
vault_password_file = /home/youruser/.vault_pass

チルダも使えます — Ansibleは正しく展開します：

[defaults]
vault_password_file = ~/.vault_pass

解決策4: コマンドラインで指定する

設定を変更せずに今すぐ実行したい場合は、フラグを使います：

ansible-playbook site.yml --vault-password-file ~/.vault_pass

# またはパスワードを対話的に入力
ansible-playbook site.yml --ask-vault-pass

解決策5: 環境変数を使用する（CI/CD向け）

自動パイプラインにはパスワードファイルをチェックインすべきではありません。vaultパスワードをCIシークレットとして保存し、実行時に一時ファイルに書き込んで、完了後に削除します：

# GitHub Actionsの例
- name: Run playbook
  env:
    VAULT_PASS: ${{ secrets.ANSIBLE_VAULT_PASSWORD }}
  run: |
    echo "$VAULT_PASS" > /tmp/.vault_pass
    chmod 600 /tmp/.vault_pass
    ansible-playbook site.yml --vault-password-file /tmp/.vault_pass
    rm -f /tmp/.vault_pass

解決策6: vaultパスワードスクリプトを使用する

複数のvault ID、AWS Secrets ManagerやHashiCorp Vaultからの取得など、より複雑な構成では、プレーンファイルの代わりに実行可能なスクリプトを使えます。Ansibleはそれを実行し、標準出力からパスワードを読み取ります：

#!/bin/bash
# get-vault-pass.sh
echo "$VAULT_PASSWORD"

chmod +x get-vault-pass.sh

# ansible.cfg
[defaults]
vault_password_file = ./get-vault-pass.sh

確認方法

プレイブック全体を実行する前に、簡単な復号テストで修正が機能しているか確認します：

# 暗号化ファイルを直接表示してみる
ansible-vault view group_vars/all/vault.yml

# またはファイルに書き込まずに標準出力に復号する
ansible-vault decrypt --output - group_vars/all/vault.yml

画面に復号された内容が表示されれば完了です。ERROR! Decryption failedが表示される場合は、ファイルは見つかって読み取れているものの、パスワードが間違っています。

Tips

.vault_passや類似のパターンをすぐに.gitignoreに追加してください。vaultパスワードファイルは絶対にコミットしないこと。
ファイルにはchmod 600を維持してください。Ansibleのバージョンによっては、全員が読み取れるパスワードファイルの使用を拒否するものもあり、それ以前にセキュリティ上の問題です。
強力なランダムvaultパスワードが必要ですか？ToolCraftのパスワードジェネレーターはブラウザ上で完全に動作し、サーバーには何も送信されず、暗号学的にランダムな出力を生成します。vaultシークレットに十分な品質です。
プロジェクトのREADMEには、vault IDとパスワードファイルの対応関係を記載してください。パスワード自体ではなく、マッピングだけで構いません。将来のチームメンバー（6ヶ月後の自分自身も含め）が感謝するでしょう。

まとめ

vault password file not foundエラーのほとんどは、3つの根本原因に起因します：このマシンにまだファイルが存在しない、ansible.cfgのパスが相対パスで間違ったディレクトリにいる、またはパーミッションが正しくない、のいずれかです。

恒久的な修正はシンプルです：ansible.cfgに絶対パス（または~/.vault_pass）を使用し、ファイルをchmod 600に保ち、vaultパスワードをパスワードマネージャーなどの安全な場所に保管してください。チームプロジェクトでは、標準の場所を一つ決め — ~/.vault_passで十分です — 次にプロジェクトをセットアップする人が何を作成すればよいかわかるようREADMEに記載しましょう。