https://developer.hashicorp.com/terraform/plugin/framework/resources/write-only-arguments

以下、Terraform Plugin Framework における「Write-only Arguments（書き込み専用引数）」のドキュメントを日本語に和訳し、Markdown形式にてまとめました。

Write-only Arguments（書き込み専用引数）

概要

書き込み専用引数（write-only arguments）とは、利用者が設定できるが、Terraform のプランや状態（state）アーティファクトに 永続化されない管理対象リソース属性です。これにより、プロバイダーはリソースの作成や更新時に入力値を受け入れることはできるものの、その値を Terraform の状態ファイルに保存しないという振る舞いが可能になります。 (HashiCorp Developer)

使用すべき場面

書き込み専用引数を使うべき典型的なシナリオには次のようなものがあります：

パスワード／API キー／トークンなど 秘匿すべき値で、Terraform の状態に保存したくないもの。 (HashiCorp Developer)
一時的またはエフェメラルな値で、操作後に追跡や比較する必要がないもの。
プロバイダー側で入力を受け取る必要はあるが、その後のリソース状態からはその入力を露出したくない／保持したくないもの。

動作の仕組み

スキーマ定義

プロバイダーのリソーススキーマにおいて、ある属性を WriteOnly: true（または同等）としてマークします。これにより、フレームワークはその属性を書き込み専用として扱い、プラン／状態ファイルへの保存をスキップします。 (HashiCorp Developer) 例（Go の疑似コード）：

"secret_password": schema.StringAttribute{
    Required:  true,
    WriteOnly: true,
},

プラン／状態での振る舞い

設定ファイルで書き込み専用属性が指定された場合、その値は Create／Update 時にプロバイダーへ渡されます。
ただし、その値は Terraform のプランや状態アーティファクトに記録されません。
次回実行時には、その属性の前回値が状態ファイルに存在しないため、Terraform はその属性に基づいた差分検知ができません。
このため、書き込み専用フィールドに変更があったことを反映させたい場合、一般に バージョン用／変更検知用の補助引数（例：*_version や *_change_signal）を併設します。例：password_wo + password_wo_version といったパターンが知られています。 (HashiCorp Developer)

互換性に関する考慮

古い Terraform CLI バージョンでは書き込み専用属性を十分にサポートしていない可能性があります。そのため、プロバイダーが Required + WriteOnly の属性を定義した場合、利用者は少なくとも Terraform v1.11 以上を使用する必要があります。 (HashiCorp Discuss) 古いクライアントで実行すると、書き込み専用属性が通常のオプション属性として扱われるか、エラーになる可能性があります。 (HashiCorp Discuss)

ベストプラクティスおよびガイダンス

属性名やドキュメントにおいて「書き込み専用」であることを明示しましょう（たとえば _wo サフィックスや *_wo_version といった命名を使うなど）。
書き込み専用属性単体では変更検知が難しいため、補助のバージョン／変更検知用引数を提供することを推奨します。
秘密値や状態に残したくない敏感情報は、可能な限り Terraform 状態に保存しない設計を検討してください。
プロバイダーの互換性に注意し、ターゲットの Terraform CLI バージョンを明記／検証してください。

使用例

resource "azurerm_mssql_server" "db" {
  name                                = "example-db"
  resource_group_name                 = azurerm_resource_group.db.name
  location                            = azurerm_resource_group.db.location
  version                             = "12.0"

  administrator_login                 = "mssqladmin"
  administrator_login_password_wo     = var.db_password.value
  administrator_login_password_wo_version = var.db_password.version
}

この例では：

administrator_login_password_wo が 書き込み専用属性です。
administrator_login_password_wo_version が、実際のパスワード値が状態ファイルに保存されない代わりに、変更を検知するための補助引数です。この構成により、パスワード実値は Terraform の状態に残りませんが、バージョン（もしくは信号）が変わった際に更新をトリガーできます。

使用すべきでない／向かないケース

属性の値を次回以降の実行で読み取ったり、比較／追跡したりする必要がある場合。
属性値を状態に保持する必要がある下流処理がある場合。
非常に古い Terraform CLI バージョン（書き込み専用属性の機能が未サポート）との互換性を重視する場合。

kenzo0107/terraform-provider-framework-write-only-arguments.md