問題点新しいマシンやCI/CDランナーで、スムーズな開始を期待してterraform initを実行したとします。しかし、プロセスが停止してしまいます。main.tfは完璧に見えますが、TerraformがプライベートGitリポジトリからモジュールを取得できません。恐ろしいexit status 128に続いてPermission denied (publickey)というメッセージが表示されます。
Error: Failed to download module
Could not download module "network" source code from "git@github.com:org/terraform-modules.git":
error downloading 'ssh://git@github.com/org/terraform-modules.git':
exit status 128: Cloning into '.terraform/modules/network'...
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.
これは通常、ローカルのGitクライアントとプロバイダー（GitHub、GitLab、またはBitbucket）間のSSHハンドシェイクが失敗したために発生します。標準のgit cloneコマンドでキーが機能していても、Terraformの環境がそれらを認識していない可能性があります。
根本原因Terraformは実際にはSSHロジックを処理しません。システムにインストールされているgitバイナリにダウンロードタスクを渡すだけです。ローカルのGit環境が有効な秘密鍵を見つけられないか、リモートサーバーと通信するための認証情報が不足している場合、ダウンロードは失敗します。その後、Terraformはその失敗を報告します。
最も頻繁な原因には以下のものがあります：
- 秘密鍵をロードしていないアクティブでないSSHエージェント。-
~/.ssh/id_rsaまたは~/.ssh/id_ed25519ファイルの不適切なファイル権限。- SSH公開鍵がGitプロバイダーの設定に登録されていない。- モジュールのsource文字列におけるわずかな構文エラー。## ステップバイステップの修正方法### 1. SSH接続を手動で確認するまず、Terraformを介さずに確認します。Gitがプロバイダーに到達できるかを確認する必要があります。ターミナルで次のコマンドを実行してください：
ssh -T git@github.com
接続に成功すると、Hi username! You've successfully authenticated...と返されます。ここで権限エラーが発生する場合、Terraformではなく、SSHの設定がボトルネックになっています。
2. SSHエージェントにキーをロードする多くの場合、キーは存在しますが、現在のセッションで「アクティブ」になっていません。これは、新しいターミナルタブや自動化された環境でよく見られます。エージェントを起動し、手動でキーを追加する必要があります。
# バックグラウンドでエージェントを起動する
eval "$(ssh-agent -s)"
# 秘密鍵を追加する（最新のキーにはid_ed25519を使用）
ssh-add ~/.ssh/id_ed25519
3. 秘密鍵の権限を修正するSSHはセキュリティに厳格です。システムの他のユーザーが秘密鍵にアクセスできる場合、SSHクライアントはそれを完全に無視します。.sshディレクトリには700の権限、秘密鍵には600の権限が必要です。
これらを正しく設定することは必須です。8進数の値に自信がない場合は、ToolCraftのUnix Permissions Calculatorで視覚的に確認できます。以下のコマンドを適用してキーを保護してください：
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
4. 明示的なTerraformモジュール構文を使用するTerraformは、短縮されたGit URLによって混乱することがあります。安全のために、明示的なgit::ssh://プレフィックスを使用してください。これにより、Terraformに使用するプロトコルを正確に伝えます。また、Terraformでは、リポジトリパスとそのリポジトリ内のサブディレクトリを区切るためにダブルスラッシュ（//）を使用することを忘れないでください。
module "vpc" {
# 形式: git::ssh://git@provider/org/repo.git//path/to/module?ref=tag
source = "git::ssh://git@github.com/acme/infrastructure-modules.git//modules/network?ref=v2.4.0"
}
5. SSH設定ファイルで複数のキーを管理する仕事用と個人用のGitHubアカウントで別々のキーを使い分けている場合、Gitが誤ったキーを提示している可能性があります。~/.ssh/configを編集することで、正しいキーを強制的に使用させることができます：
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_work
IdentitiesOnly yes
CI/CDでの問題を解決するGitHub Actionsのような自動化ランナーには、デフォルトで対話型のSSHエージェントがありません。秘密鍵をシークレットとして注入する必要があります。GitHub Actionsの場合、このタスクにはwebfactory/ssh-agentアクションが業界標準となっています。
- name: Setup SSH Keys
uses: webfactory/ssh-agent@v0.5.4
with:
ssh-private-key: ${{ secrets.MY_TERRAFORM_DEPLOY_KEY }}
このアクションはSSH_AUTH_SOCK環境変数を設定します。Terraformがgit cloneを実行すると、ロードされたキーを自動的に見つけ、正常に認証されます。
検証とクリーンアップ権限やエージェントを修正した後、再試行する前に失敗した試行の残骸をクリアしてください。Terraformは、クリーンな初期化を妨げる可能性のある不完全なディレクトリを残すことがあります。
# ローカルのモジュールキャッシュを削除する
rm -rf .terraform/modules
# 再度initを実行する
terraform init
成功すると、128の終了コードなしに、一連の緑色のDownloading...メッセージが表示されます。