はじめに
インフラのグループ福本です。
この記事では、IaCツールであるTerraformのバージョンアップを行なった際のやり方や注意点をまとめたいと思います。
なお実行環境はMacを想定しています。
Terraformのバージョンアップを検討している方の助けになれば幸いです。
バージョンアップの必要性
今回は、Terraformに追加された新機能を利用できるようにするために、アップデートを実施しました。
なお、新機能追加の他に既知のバグ修正、セキュリティの向上などのメリットがあります。
また、各プロバイダーのModuleを利用する際にTerraformやプロバイダーで一定以上のバージョンが求められるためバージョンアップが必要になることもあります。
利用ツール
バージョンアップを行うにあたり利用したツールは以下です。
- tfenv
- tfupdate
利用ツールの用途
tfenv
複数のTerraform versionのインストールや切り替え、ディレクトリごとに利用するバージョンを指定できます。
利用バージョンを指定するファイル（.terraform-version）を作成し、バージョンを設定するだけで切り替えられるため便利です。
また、ファイルで指定したバージョンがインストールされていない場合は、インストールまで行ってくれます。
インフラGでは、devやprodなど環境毎にディレクトリを分けており、それぞれのディレクトリに.terraform-versionを用意することで、環境毎に使用するバージョンを指定できるようにしています。
tfupdate
tfファイルに記述されているTerraform/Provider/Moduleのバージョンを一括更新できます。
Moduleを利用している際などはversion指定を書き換える対象が多くなるため、こちらを使うと便利です。
なお、それぞれのツールの詳細な説明は割愛しますので、githubなどをご確認ください。
GitHub - tfutils/tfenv: Terraform version manager
GitHub - minamijoyo/tfupdate: Update version constraints in your Terraform configurations
Terraformバージョン制約表記確認
バージョンアップを進めていく前に、知っておいた方が良いことがバージョン制約表記です。
Terraformはバージョン制約の表記の仕方により、利用できるバージョンが異なるため、表記方法を事前に確認してください。
Version Constraints - Configuration Language | Terraform | HashiCorp Developer
一部を抜粋して紹介します。
| 表記 | 説明 | 例 |
|---|---|---|
| ~> | 右端のバージョンコンポーネントのみを増分可 | ~>1.0.4 OK: 1.0.5, 1.0.10 NG: 1.1.0 ~> 1.4 OK: 1.5, 1.10 NG: 2.0 |
| >= | 比較が真となるバージョンを許可 | >=1.0.4 OK: 1.0.5, 1.4, 2.0 NG: 1.0.3 |
バージョンアップ前の準備
バージョンアップを始める前に、バージョンアップによる変更内容と影響を調査します。
現在のバージョン確認
まず、現在使用しているTerraformのバージョンをterraform -vで確認します。
アップデート情報の確認
Terraformの公式サイトにて現在のバージョン以降から最新バージョンまでの情報を参照し、変更箇所や注意事項を確認、対応が必要なものがあれば、コードを修正してください。
Upgrading to Terraform v1.9 | Terraform | HashiCorp Developer
バージョンアップ手順
バージョンアップの対象と更新順序
バージョンアップを行う対象は以下です。
- Terraform
- Provider
- 公式Module（なお、未利用の場合は対応必要ありません。）
また更新を実施する順序は上から順になります。
これは公式ModuleがTerraformおよびProviderで一定以上のバージョンを要求するためです。
先に公式Moduleをアップデートしようすると、TerraformやProviderのバージョンがModuleの要求するバージョン以下になることがあり、アップデート出来ないことがあります。
Terraformのバージョンアップ
ステップ1: Terraformのrequired_versionを変更
利用中のバージョン以降を許容し、バージョンアップが行えるよう状態にする為、Terraform実行ディレクトリにて以下のコマンドを実行しTerraformのrequired_versionを修正します。
# 利用中のバージョンが1.xの場合、terraformの実行ディレクトリにて以下を実施
tfupdate terraform -v "~> 1.x" -r <terraformディレクトリのパス>
xには利用中のバージョン番号を入れてください。
※ ~> 1.x.y としないこと 左記の場合 y の数字のみ変更が許容されることになります。
ステップ2: アップデートしたいバージョンを指定
tfenvにてバージョンを管理できるよう、Terraformの実行ディレクトリに
.terraform-versionファイルを作成し、アップデートしたいバージョンを指定します。
# 1.9.0を使用したい場合terraformの実行ディレクトリにて以下を実施
echo "1.9.0" > .terraform-version※ここでの記入は、1.x.yのyまで記入してもOKです。
ステップ3: terraform planを実行
terraform planを実行し、変更の有無を確認、変更がある場合は影響を確認しコード修正などを実施してください。
バージョンアップしたいバージョンが未インストールの場合は、tfenvが自動的にインストールしてくれます。
ステップ4: terraform applyを実行
terraform applyを実行し、変更を反映してください。
Providerのバージョンアップ
ステップ1: バージョンチェック
Githubにて、Providerのアップデート情報を確認し、現在のバージョン以降から最新バージョンまでの情報を参照し、変更箇所を確認、対応が必要なものがあれば、コードを修正してください。
Releases · hashicorp/terraform-provider-aws · GitHub
ステップ2: Providerのversionを修正
利用中のバージョン以降を許容し、バージョンアップが行えるよう状態にする為、Terraform実行ディレクトリにて以下のコマンドを実行しProviderのrequired_providersを修正します。
マイナーバージョンをアップデートする場合:
# 利用中のバージョンが5.xの場合、terraformの実行ディレクトリにて以下を実施
tfupdate provider aws -v "~> 5.x" -r <terraformディレクトリのパス>
メジャーバージョンをアップデートする場合：
# 利用中のバージョンが5.xの場合terraformの実行ディレクトリにて以下を実施
tfupdate provider aws -v ">= 5.x" -r <terraformディレクトリのパス>
上記のような書き方をすると、最新のマイナー/メジャーバージョンにアップデートします。
なお、アップデートしたいバージョンが決まっている場合は以下で対応できます。
状況に合わせて使い分けてください。
# アップデートしたいバージョンが5.xxの場合terraformの実行ディレクトリにて以下を実施
tfupdate provider aws -v "= 5.xx" -r <terraformディレクトリのパス>
ステップ3: lockファイルを更新
providerをアップデートする、環境やModule毎にlockファイルを更新してください。
# 環境やModuleのディレクトリにて以下を実施
terraform init -upgrade
ステップ4: terraform planを実行
terraform planを実行し、変更の有無を確認、変更が無ければ次の手順へ、変更がある場合は影響を確認し必要な対応を実施してください。
ステップ5: terraform applyを実行
terraform applyを実行し、変更を反映してください。
公式Moduleのバージョンアップ
ステップ1: 利用中の公式Module洗い出し
アップデート対象のModuleを特定するため、利用中の公式Moduleを洗い出してください。
例：VS Codeでterraformディレクトリ内を「terraform-aws-modules」で検索
ステップ2: バージョンチェック
「terraform module <サービス名>」などでWeb検索し、Terraformの公式ページにて各Moduleでアップデートするバージョンを調べてください。
参照例：aws ec2
Releases · terraform-aws-modules/terraform-aws-ec2-instance · GitHub
ステップ3: Moduleのversionを変更
AWS公式Moduleを呼び出している、tfファイルにてversionを修正もしくは追記
# albのModuleを更新する際の例
module "ec2" {
source = "terraform-aws-modules/ec2-instance/aws"
version = "~> 5.x" ←ここを修正 この場合、5.x系の最新になります
...
}
ステップ4: lockファイルを更新
アップデートするModuleが存在するディレクトリごとにlockファイルを更新してください。
# アップデートModuleが存在するディレクトリにて以下を実施
terraform init -upgrade
ステップ5: terraform planを実行
terraform planを実行し、変更の有無を確認、変更が無ければ次の手順へ、変更がある場合は影響を確認し必要な対応を実施してください。
※まとめて複数Mobuleの更新し、変更があった際に影響を及ぼしているModuleの特定に手間がかかる場合は、1~2個程度ずつ小分けにして更新することも検討してください。
※公式Moduleに大規模な変更がある場合は、最新版を呼び出せるModuleを新規作成することも検討してください。
ステップ6: terraform applyを実行
terraform applyを実行し、変更を反映してください。
以上で、アップデートは終了になります。
バージョンアップ時の注意事項
バージョンアップデートの影響により、自身が変更を行なっていないリソースでも変更があるように見えることがあるため注意してください。
DataSourceを利用している場合、元となるリソースに変更があるとDataSourceが再読み込みとなり、そのDataSourceを参照しているリソースが変更もしくは再作成されることがあります。
まとめ
以上、Terraformのバージョンアップ手順について解説しました。
新しいバージョンの利用は多くのメリットがありますが、安全に行うためには準備と確認が欠かせません。
この記事が皆さんの作業の一助となれば幸いです。安全で円滑なバージョンアップをお祈りしています！
福本 益実 Masumi Fukumoto
ITマネジメント&インフラ･セキュリティ統括部 インフラ部 インフラグループ
リードエンジニア
2024/01にパーソルキャリアへ入社。前職はSIerにてインフラエンジニアとして従事。スクラム開発への参加経験もあり、設計からインフラ構築、アプリ開発、運用までを行なった経験を活かして、インフラをモダナイゼーションしようと奮闘中。
※2024年08月現在の情報です。
