tfmv - Terraform の rename に moved block を添える小さな CLI

Terraform code では、命名の負債が静かにたまります。初期は速さを優先し、resource name に -、_、environment suffix、略語、team ごとの convention が混ざる。あとで整理したくなったとき、単に .tf file の block name を変えるだけでは足りません。Terraform state にも、old address と new address の関係を伝える必要があります。

Terraform の moved block は、その移行関係を表すための仕組みです。しかし一度の rename が複数の resource、data source、module、そして多くの references に広がると、手で moved block を書く作業は退屈で、抜け漏れも起きやすくなります。今日紹介する suzuki-shunsuke/tfmv は、この小さく具体的な問題に向けた CLI です。Terraform blocks を rename し、対応する moved blocks を生成します。

公開時点の GitHub page では、およそ 159 stars、6 forks。主な言語は Go、license は MIT です。Project は 2024-12-20 に作成され、直近の push は 2026-06-06。現在 GitHub latest release はありません。

プロジェクト概要

項目	内容
Repository	suzuki-shunsuke/tfmv
位置づけ	Terraform resource、data source、module rename と moved block generation
Stars	約 159
Forks	6
主な言語	Go
License	MIT
Latest release	なし

Terraform rename の機械的な部分を担う

Terraform rename には二つの作業があります。一つ目は source code 上の rename です。たとえば github_repository.example-1 を github_repository.example_1 に変更し、それを参照している block も更新する。二つ目は state migration の説明です。Terraform に対して、その object は新規作成でも削除でもなく、old address から new address に移動したのだと伝える必要があります。

手作業では、次のような失敗が起きます。

1. block name は変えたが、reference が一部残る。
2. reference は変えたが、moved block を忘れる。
3. moved block を書いたが、old address や new address を打ち間違える。

tfmv の価値はここにあります。Naming transformation rule を Terraform block に適用し、同時に moved.tf を生成します。大きな IaC platform ではありません。実際の整理 task にそのまま入れられる小さな tool です。

最小例は hyphen から underscore への置換

README の基本例はわかりやすいです。

tfmv -r "-/_"

-r / --replace は simple replacement を意味します。たとえば次の resource があるとします。

resource "github_repository" "example-1" {
  name = "example-1"
}

tfmv は block name を example_1 に移し、references も更新します。同時に、次のような moved block を生成します。

moved {
  from = github_repository.example-1
  to   = github_repository.example_1
}

この設計は naming convention の統一に向いています。たとえば Terraform block name では hyphen をやめて underscore に寄せる、あるいは一部の environment suffix をまとめて外す、といった作業です。terraform init を実行する必要はなく、default では current directory の *.tf files を探します。

resource だけでなく data source と module も対象

tfmv は resource だけを扱う tool ではありません。README では、Terraform resources、data sources、modules を rename し、references を更新できると説明されています。この範囲は重要です。実際の module では、次のような関係がよくあります。

• resource name が data から参照される。
• module name が depends_on に出てくる。
• output が data source や resource を参照する。
• 複数 block の naming rule を同時に変える必要がある。

単純な text replacement だけでは、普通の string を誤って変えたり、Terraform address の意味を取り落としたりしやすいです。tfmv は普通の sed ではなく、Terraform block address を意識した renamer と見るほうが近いです。

三つの rename rule を使える

tfmv では、rename method を一つ指定します。

• --replace / -r: simple string replacement。- から _ への移行など。
• --regexp: regular expression による rename。suffix removal や pattern matching に向く。
• --jsonnet / -j: Jsonnet で柔軟な naming logic を書く。

Simple rule は command line に直接書けます。

tfmv --regexp '-prod$/'

これは -prod suffix を外すような用途に使えます。もっと複雑な場合は Jsonnet を書けます。tfmv は各 input object の情報を Jsonnet に渡します。file path、block type、resource type、current name などです。Jsonnet は new name を返します。空文字や同じ名前を返した object は rename されません。

この段階分けは実用的です。多くの整理 task は -r で足ります。少し複雑なら regexp、本当に policy 的な logic が必要なときだけ Jsonnet に進めばよい。

Scope control で大きな repository の risk を下げる

Terraform name を batch change するときは、scope control が重要です。tfmv は --include と --exclude を持ち、regular expression で対象を絞れます。

tfmv -r "-/_" --include "^aws_"
tfmv -r "-/_" --exclude "^aws_"

Specific .tf file を argument として渡すこともできます。

tfmv -r "-/_" main.tf

Recursive search が必要なら -R を使います。

tfmv -Rr "-/_"

Recursive mode では .git、.terraform、node_modules が ignore されます。Terraform project の現実的な構造に合った default です。State directory、dependency directory、tool cache に入り込むのを避けられます。

--dry-run と moved file の置き場所

tfmv を使うなら、最初は --dry-run を走らせるのがよいです。

tfmv -r "-/_" --dry-run main.tf

README によれば、dry run は log を出しますが blocks は rename しません。Infrastructure code ではこの step を残す価値があります。Terraform refactor の risk は syntax より address migration の意図にあります。まず log を見る。次に diff を見る。最後に terraform plan を走らせる。この順番が安全です。

Default では、tfmv は moved blocks を moved.tf に書きます。File name を変えたい場合は -m を使います。

tfmv -r "-/_" -m moved_blocks.tf

-m same を使えば、rename した同じ file に moved blocks を出せます。これは team preference 次第です。Migration blocks を一か所にまとめて後で掃除したい team もあれば、original module の近くに置きたい team もあります。

どんな workflow に置くか

tfmv は、日常的に無意識で走らせる tool というより、明示的な Terraform refactor に置くのがよさそうです。

1. Naming migration だけを扱う branch を作る。
2. tfmv --dry-run で影響範囲を見る。
3. Directory、file、include/exclude で scope を絞る。
4. tfmv を実行し、source changes と moved blocks を生成する。
5. Diff を review し、references が更新されているか確認する。
6. Target workspace で terraform plan を実行する。
7. Merge 後に一度 apply を観察し、team policy に従って古い moved blocks を整理する。

tfmv は mechanical mistake を減らしますが、plan と review の代替ではありません。Terraform state migration は production infrastructure change の一部です。Tool は repetitive code を減らすためのもので、verification を飛ばすためのものではありません。

terraform state mv との関係

tfmv が生成するのは Terraform configuration 内の moved blocks であり、直接 terraform state mv を実行するわけではありません。この違いは重要です。

terraform state mv は one-off な state operation で、手作業の migration に向く場面があります。一方、moved block は migration intent を configuration に書き、code と一緒に review、commit、run できるようにします。Team collaboration では後者の透明性が高いです。PR で old address、new address、source changes を見られ、CI や plan workflow にも migration relationship が現れます。

tfmv が面白いのは、単に名前を変えるだけでなく、「rename」を Terraform が理解でき、team が audit できる migration として表現しやすくする点です。

注意しておきたい boundary

tfmv の problem domain は明確です。その分、使う側も boundary を持つべきです。

• どの Terraform rename を実施すべきかは判断してくれない。
• Provider behavior、plan review、environment verification の代替ではない。
• Batch rule を間違えると、望まない大量 rename が生成される可能性がある。
• 現在 GitHub latest release がないため、採用時は install method と repository change cadence を見る必要がある。

したがって、安全な使い方は small scope、dry run、diff review、plan verification です。大きな infrastructure repository で global replacement を一度走らせ、そのまま merge するのは避けたいです。

試すのに向いている場面

tfmv は次のような場面に合います。

• Terraform repository の block naming convention を統一している。
• Hyphen、suffix、historical naming pattern をまとめて移行したい。
• Module 内に references が多く、手作業では抜け漏れが怖い。
• One-off state operation ではなく moved block を使いたい。
• Naming migration を PR diff として review したい。

一つの resource だけなら、手で moved block を書くほうが速いかもしれません。しかし対象が数十個に増えたり、明確な naming rule がある場合、tfmv は mechanical work をかなり減らしてくれます。

まとめ

suzuki-shunsuke/tfmv は、小さな niche developer tool らしい tool です。Scope は狭いですが、問題は現実的です。Terraform rename は毎日発生する作業ではありません。しかし発生したとき、address、references、moved blocks を手で合わせるのはかなり間違いやすい。

Scope control、dry run、regexp、Jsonnet、moved file location といった細部が揃っている点がよいです。Terraform refactor を risk-free にする tool ではありませんが、もっとも反復的で抜けやすい部分を自動化してくれます。中規模以上の Terraform repository を保守しているなら、toolbox に入れておく価値があります。