🧰

terragrunt を並列実行しすぎると terragrunt-cache や plugin_cache_dir が壊れる問題

に公開
Terraform
IaC
cache
Terragrunt
tech

TL;DR

  • 結論、多くの場合は .terraformrc の plugin_cache_dir を使ってるのが原因
  • terragrunt においては .terraformrc の plugin_cache_dir は不要で、TG_PROVIDER_CACHE で Terragrunt Cache server を使うのがよい

手順

前提:

  • 環境は Mac とする
  • project root 配下で実行する

事象

  • 今以下のようなエラーで terragrunt がフリーズして困っているものとする
  • もうダメなので大人しく ctrl-C で中断する
Error: Failed to load plugin schemas

Error while loading schemas for plugin components: Failed to obtain
provider schema: Could not load the schema for provider
registry.terraform.io/hashicorp/aws: failed to instantiate provider
"registry.terraform.io/hashicorp/aws" to obtain schema: timeout while
waiting for plugin to start..

まず壊れた cache を削除

# Terragrunt Cache server の cache を削除
# 確認
$ ll ~/Library/Caches/terragrunt/providers
Permissions Size User Date Modified    Name
drwxr-xr-x@    - hi  2025-11-30 09:08  registry.terraform.io/

# 削除
$ rm -rf ~/Library/Caches/terragrunt/providers*

# live/ 配下の terragrunt-cache も削除
$ find . -type d -name ".terragrunt-cache" -prune -exec rm -rf {} \;

# クリアな時点のファイルサイズを把握しておく (私の環境の一例)
$ du -sh .
824K    .

正しく設定できてるか見直す

TG_PROVIDER_CACHE の有効化を確認

$ echo $TG_PROVIDER_CACHE
1

なければ以下を ~/.zshrc などに追加してから再ログイン

~/.zshrc
export TG_PROVIDER_CACHE=1

再初期化

$ terragrunt run --all -- init

# それでも壊れるなら並列数を減らす。
# デフォルト並列数は∞。 `terraform --parallelism` (デフォルト 10) とは別。
$ terragrunt run --all --parallelism 2 -- init

# init 後のファイルサイズを見て、cache が聞いてることを確認する (私の環境の一例)
$ du -sh .
5.7M    .

その他

.terraformrc の plugin_cache_dir は不要なのか？

TG_PROVIDER_CACHE を設定していれば、なんと不要らしい
例えば validate コマンドの実行ログを見てみると・・・

$ terragrunt run --all -- validate
09:15:08.909 INFO   Terragrunt Cache server is listening on 127.0.0.1:52126
09:15:08.911 INFO   Start Terragrunt Cache server
09:15:08.912 INFO   Using runner pool for stack .
09:15:08.933 INFO   The runner-pool runner at . will be processed in the following order for command validate:
- Unit ./live/aws/production/_global/dns
- Unit ./live/aws/production/ap-northeast-1/foundation/network
- Unit ./live/aws/production/ap-northeast-1/platform/parameters
- Unit ./live/aws/production/ap-northeast-1/platform/auth-app-cognito
- Unit ./live/aws/production/ap-northeast-1/services/app-frontend

09:15:12.670 STDOUT [live/aws/production/_global/dns] terraform: Success! The configuration is valid.
09:15:12.671 STDOUT [live/aws/production/_global/dns] terraform:
09:15:12.752 STDOUT [live/aws/production/ap-northeast-1/platform/parameters] terraform: Success! The configuration is valid.
09:15:12.752 STDOUT [live/aws/production/ap-northeast-1/platform/parameters] terraform:
09:15:12.929 STDOUT [live/aws/production/ap-northeast-1/foundation/network] terraform: Success! The configuration is valid.
09:15:12.930 STDOUT [live/aws/production/ap-northeast-1/foundation/network] terraform:
09:15:16.393 STDOUT [live/aws/production/ap-northeast-1/services/app-frontend] terraform: Success! The configuration is valid.
09:15:16.394 STDOUT [live/aws/production/ap-northeast-1/services/app-frontend] terraform:
09:15:16.404 STDOUT [live/aws/production/ap-northeast-1/platform/auth-app-cognito] terraform: Success! The configuration is valid.
09:15:16.404 STDOUT [live/aws/production/ap-northeast-1/platform/auth-app-cognito] terraform:

❯❯ Run Summary  5 units  7s
   ────────────────────────────
   Succeeded    5

09:15:16.415 INFO   Shutting down Terragrunt Cache server...
09:15:16.417 INFO   Terragrunt Cache server stopped

何やら怪しげなサーバーが起動してる

09:15:08.909 INFO Terragrunt Cache server is listening on 127.0.0.1:52126
09:15:08.911 INFO Start Terragrunt Cache server
09:15:16.415 INFO Shutting down Terragrunt Cache server...
09:15:16.417 INFO Terragrunt Cache server stopped

実際できあがった .terragrunt-cache 配下の provider の実体を探してみると・・・

$ ll live/aws/production/_global/dns/.terragrunt-cache/X93XzFwrkeh0BjWR7QgsIyVhd2A/HD16a5RKre9YrifuG0FFjgoDOA4/.terraform/providers/registry.terraform.io/hashicorp/aws/6.21.0/
Permissions Size User Date Modified    Name
lrwxr-xr-x@    - hi  2025-11-30 09:14  darwin_arm64 -> /Users/hi/Library/Caches/terragrunt/providers/registry.terraform.io/hashicorp/aws/6.21.0/darwin_arm64/

$ ll /Users/hi/Library/Caches/terragrunt/providers/registry.terraform.io/hashicorp/aws/6.21.0/darwin_arm64/
Permissions Size User Date Modified    Name
.rw-rw-r--@  17k hi   2025-11-30 09:09 LICENSE.txt
.rwxr-xr-x@ 750M hi   2025-11-30 09:09 terraform-provider-aws_v6.21.0_x5*

公式 の記述である以下とも一致するので、これが Terragrunt Cache server の cache の実体なのだろう

By default, cached providers are stored in terragrunt/providers folder, which is located in the user cache directory:

  • $HOME/.terragrunt-cache/terragrunt/providers on Unix systems
  • $HOME/Library/Caches/terragrunt/providers on Darwin
  • %LocalAppData%\terragrunt\providers on Windows

TG_PROVIDER_CACHE を有効化してないとどうなるのか？

# 私の環境の一例
$ du -sh .
3.7G    .
  • AWS の場合 1 provider 750 MB くらいあるので、cache が効いてない場合は明らかに違いがわかる
  • 750 MB * provider 数なので、実験用の小規模でも上記くらいになって、あっという間にディスクドカ食い気絶部の仲間入り
  • なぜこれが default off なのかは謎

で、本当に壊れなくなったの？

悪魔の証明です

参考

Discussion