Terraform × Instana 実践編：file() か jsonencode() か？Widgets構成でハマった話

はじめに

本記事は、以前投稿した以下の記事の続編です：

TerraformでInstanaのカスタムダッシュボードを作ってみた（with jsonencode / jsondecode）

前回は、Instana Provider を使って Terraform でカスタムダッシュボードを作る方法と、必要な設定やAPIの仕様について触れました。

今回は「widgetsの構成方法」をテーマに、Terraformが毎回差分を出してくる問題や、結局どう書くのが安定なのか？を深掘りしていきます。

---

背景：file() だけでいけるんじゃ？説

Instanaの公式ドキュメントでは、以下のように widgets = file("widgets.json") の記述例が示されています：

resource "instana_custom_dashboard" "example" {
  title = "Example Dashboard"

  access_rule { 
    access_type = "READ_WRITE"
    relation_type = "USER"
    related_id = "user-id-1"
  }

  widgets = file("${path.module}/widgets.json")
}

この記述、ぱっと見て「文字列で渡せばOK」と思って試したくなりますよね？

実験結果：Instana側では成功、Terraformでは diff の嵐

widgets = file("widgets.json")

この形式で実際に試したところ…

• ◯ InstanaにはPOSTされ、ダッシュボード作成は成功！

• ❌ ただし Terraform の plan/apply に毎回diffが出る

.widgets: planned value ... does not match config value ...

その理由は、file()で読み込んだ内容が整形（インデントや改行）されていて、構造としての比較ではなく文字列としてdiffが出る ためです。

原因考察：Terraformはfile()の内容を文字列として扱う

Terraformでは widgets のようなJSONオブジェクトは構造化した形式として比較されるべきですが、
file() 関数で読み込んだ場合、Terraformはその中身をただの文字列として扱ってしまいます。

つまり、中身がまったく同じ構造でも、インデントや改行の違いだけで「変更あり」とみなされてしまうのです。

locals {
  widgets = jsondecode(file("${path.module}/widgets.json"))
}

resource "instana_custom_dashboard" "example" {
  ...
  widgets = jsonencode(local.widgets)
}

こうすることで、Terraformが内部で構造を基に比較し、不要なdiffが発生しなくなります。

---

おまけ：related_id にメールアドレス入れると怒られる

Error: USER is unknown
Body: {"errors":["Related ID dai@hiraoka (USER) is unknown."]}

これは access_rule にメールアドレスを渡していたためです。
Instanaの仕様では、USERの related_id に必要なのは UUID形式のユーザーID。

ユーザー一覧は API から取得できます：

curl -s -H "Authorization: apiToken $INSTANA_API_TOKEN" \
  "$INSTANA_ENDPOINT/api/settings/users" | jq .

---

widgets.json の例

[
  {
    "id": "widget-1",
    "title": "Tokyo Sample Widget",
    "x": 0,
    "y": 0,
    "width": 6,
    "height": 3,
    "type": "apdex",
    "config": {
      "apdexConfigId": "Tokyo-some-config-id",
      "entityType": "website",
      "entityId": "Tokyo-some-entity-id"
    }
  }
]

結論まとめ

ケース	結果・考察
widgets = file(...)	通るが plan/apply に差分が出るため非推奨
widgets = jsonencode(...)	安定して構造的に一致。おすすめ
related_id = "メール"	Instana 側で拒否される NG
related_id = "UUID"	OK

実際にPRを出しました！

今回の件は、Instana Providerのドキュメントに対して以下の改善PRを提出し、修正提案として取り込んでもらえるよう働きかけています：

Fix: Recommend using jsondecode(file(...)) for widgets to avoid false diffs #34

もし同じようにハマった方がいれば、PRやIssueにイイねしてもらえると、反映の後押しになるかもしれません！

ここまで読んでくださってありがとうございました！