「死の赤文字」エラー
リポジトリをクローンし、環境変数を設定して、terraform initを実行したとします。初期化が成功する代わりに、Error: Unsupported Terraform Core versionという無愛想なメッセージが表示されます。これは、ローカルのTerraformバイナリが、その特定のインフラストラクチャ構成に対応していないことを意味します。
これは、チームでの開発中や古いプロジェクトを再開する際によく発生する悩みです。障害のように感じられますが、実際には異なるマシン間でのインフラ状態の一貫性を保つための重要な安全機能です。
根本原因：バージョン制約
Terraformは、terraform {}設定ブロック内のrequired_version設定に依存しています。これにより、どのバージョンのCLIがコードを操作できるかが明示的に定義されます。これは、異なるバージョンがステートファイルに書き込むことでメタデータが破損したり、古いバージョンが完全にロックアウトされたりする「ステートファイルの飛び越し」を防ぎます。
versions.tfまたはmain.tfファイルを確認してください。おそらく、次のような制約が見つかるはずです。
terraform {
required_version = ">= 1.6.0"
}
ローカルマシンでバージョン1.3.0を実行している場合、1.3.0は「1.6.0以上」という要件を満たさないため、Terraformは即座に実行を停止します。
方法1：設定の更新
個人で作業している場合やプロジェクトのリーダーで、新しいバージョンに移行することを決めた場合は、制約を変更できます。terraformブロックを見つけ、required_version文字列をローカル環境に合わせて調整します。
定義方法にはいくつかのオプションがあります。
# オプションA：厳密な固定（全員に特定のバージョンを強制）
terraform {
required_version = "1.3.0"
}
# オプションB：ペシミスティック演算子（1.3.1や1.3.2は許可するが、1.4.0は許可しない）
terraform {
required_version = "~> 1.3.0"
}
# オプションC：最小バージョン（最も柔軟なアプローチ）
terraform {
required_version = ">= 1.3.0"
}
ファイルを保存したら、再度terraform initを実行して修正を確認します。
方法2：プロのアプローチ（バージョンマネージャー）
プロフェッショナルなDevOps環境では、ローカルマシンに合わせてコードを曲げるべきではありません。代わりに、マシンをプロジェクトのニーズに適応させるべきです。プロジェクトにバージョン1.6.0が必要なら、1.6.0をインストールする必要があります。
tfenv（macOS/Linux）やtfutils/tfenv-windowsなどのツールは非常に便利です。これらを使用すると、バイナリを手動で入れ替えることなく、複数のバージョンを使い分けることができます。
tfenvを使用したバージョンの切り替え：
- 必要なバージョンをインストール：
tfenv install 1.6.0 - そのバージョンを有効化：
tfenv use 1.6.0 - 変更を確認：
terraform version
asdfユーザーの場合、プロセスは同様に迅速です：
asdf install terraform 1.6.0
asdf local terraform 1.6.0
意外な落とし穴：ステートファイル
コードの制約が完璧に見えるのにエラーが発生することがあります。これは通常、ステートファイルがすでに新しいバージョンによって変更されているために起こります。Terraformは、最後に使用されたバージョンをステートのメタデータに直接埋め込みます。チームメイトが1.7.0を使用して変更を適用した場合、あなたが1.3.0でプランを実行しようとすると、データの破損を防ぐためにTerraformがブロックします。
この場合、通常はローカルのTerraform CLIをステートファイルに記録されているバージョン以上にアップグレードする必要があります。
検証とテスト
まず、現在有効なバージョンを確認して修正を確かめます：
terraform version
次に、ドライランを実行して制約が満たされていることを確認します：
terraform plan
「Plan: 5 to add, 0 to change, 0 to destroy」のようなサマリーが表示されれば、ハードルを無事にクリアしたことになります。
再発防止のベストプラクティス
このエラーの再発を防ぐには、リポジトリのルートディレクトリに.terraform-versionファイルを追加します。ほとんどのバージョンマネージャーはこのファイルを検出し、ディレクトリにcdした瞬間に環境を自動的に切り替えます。
複雑な設定を扱う場合、データをクリーンに保つことが不可欠です。私は、変数ファイルや外部メタデータを再確認するために、YAML ↔ JSON コンバーターをよく使用します。これは、Terraformが処理を開始する前にデータ構造が有効であることを確認する簡単な方法です。
最後に、CI/CDパイプラインでlatestタグを使用するのは避けましょう。GitHub Actionsなどのランナーのバージョンは、required_versionに合わせて明示的に固定（ピン留め）してください。これにより、Terraformの新しいメジャーバージョンがリリースされた瞬間にビルドが壊れるのを防ぐことができます。