materialize-terraform-provider

Materialize Terraform プロバイダー

MaterializeInc/materialize Terraform プロバイダーは、Materialize のリソースを宣言的に管理します。Materialize Cloud（SaaS）とセルフマネージドのデプロイの両方に対応しています。

このスキルでは、リソースごとの引数リファレンスを意図的に重複して掲載していません。プロバイダーはスキーマからすべてのリソースとデータソースの完全なドキュメントを自動生成しており、それが信頼できる情報源です。このスキルでは、そのリファレンスの場所を案内し、自動生成ドキュメントに含まれない知識、つまりプロバイダーのセットアップ、リソース間のパターン、インポートの手順、注意点のみを紹介します。

正式なリファレンスの場所

自動生成ドキュメントは、プロバイダーのリポジトリと Terraform Registry にあります。

• リポジトリ：terraform-provider-materialize の docs/
• Registry：https://registry.terraform.io/providers/MaterializeInc/materialize/latest/docs

ファイル名は機械的に決まるため、一覧がなくても任意のリソースのパスを特定できます。

必要な情報	プロバイダーリポジトリ内で参照するファイル
リソース materialize_<name>	docs/resources/<name>.md
データソース materialize_<name>	docs/data-sources/materialize_<name>.md
プロバイダーの引数	docs/index.md
移行ガイド	docs/guides/（例：materialize_source_table.md）

たとえば、materialize_source_kafka のドキュメントは docs/resources/source_kafka.md にあります。自動生成された各ページには、引数リファレンス、属性リファレンス、インポート構文、通常はサンプルもすべて含まれています。

リソースの引数を推測してはいけません。 設定を作成する前に、そのリソースの自動生成ドキュメントを確認してください。プロバイダーをローカルにインストールしている場合は、terraform providers schema -json を使うと、正確なスキーマを信頼できる情報源として確認できます。

プロバイダーの設定

Materialize Cloud（SaaS）

provider "materialize" {
  password       = var.materialize_password  # app password
  default_region = "aws/us-east-1"
}

セルフマネージド

provider "materialize" {
  host     = "materialized"
  port     = 6875
  username = "materialize"
  database = "materialize"
  password = var.mz_password
  # Use "require" (or stricter, e.g. "verify-full") against any TLS-enabled
  # deployment. "disable" is only appropriate for a local, non-TLS instance.
  sslmode  = "require"
}

OIDC/SSO 認証（セルフマネージド）

provider "materialize" {
  host     = "materialized"
  port     = 6875
  username = var.oidc_username
  password = var.oidc_id_token
  database = "materialize"
  options = {
    oidc_auth_enabled = "true"
  }
}

すべての引数に対応する環境変数があります：MZ_HOST、MZ_PORT、MZ_USER、MZ_DATABASE、MZ_PASSWORD、MZ_SSLMODE、MZ_DEFAULT_REGION。

重要： セルフマネージドモードでは、Frontegg に依存するリソース（アプリパスワード、ユーザー、SSO、SCIM）はサポートされていません。これらは Materialize Cloud に対してのみ動作します。

リソースマップ

どのようなものがあるかをカテゴリ別に示します。調べる対象を把握するために使ってください。ここには名前のみを記載しています。引数については生成されたドキュメントを参照してください。

• コンピューティング：materialize_cluster（materialize_cluster_replica は非推奨です。size を指定して materialize_cluster を使用してください）
• 名前空間：materialize_database、materialize_schema
• 接続：materialize_connection_{kafka,postgres,mysql,sqlserver,aws,ssh_tunnel,confluent_schema_registry,aws_privatelink,iceberg_catalog}
• ソース：materialize_source_{kafka,postgres,mysql,sqlserver,load_generator}
• ソーステーブル（推奨モデル。テーブルはソースとは別に定義します）：materialize_source_table_{kafka,postgres,mysql,sqlserver,webhook}
• シンク：materialize_sink_{kafka,iceberg}
• ビューとテーブル：materialize_materialized_view、materialize_view、materialize_index、materialize_table、materialize_type
• セキュリティ：materialize_role、materialize_secret、materialize_network_policy、materialize_grant_system_privilege
• オブジェクト権限付与：オブジェクトの種類ごとに 1 つのリソースがあります（materialize_cluster_grant、materialize_database_grant、materialize_schema_grant、materialize_table_grant など）。各リソースは role_name、privilege、およびオブジェクト参照を受け取ります。materialize_*_grant_default_privilege の各バリアントは、今後作成されるオブジェクトの権限を設定します。
• クラウド専用（Frontegg）：materialize_user、materialize_app_password、materialize_sso_*、materialize_scim_*、materialize_region
• システム設定：materialize_system_parameter、materialize_role_parameter
• データソース：上記の読み取り専用リスト（クラスター、ソース、ビュー、ロールなど）に加え、materialize_egress_ips、materialize_current_cluster、materialize_current_database。いずれも region によるフィルタリングに対応しています。

リソース間のパターン

これらの規約はほとんどのリソースに共通して適用され、ドキュメントを個別に読んでいると見落としやすいものです。

具体例

接続、ソース、ソーステーブルはネストされた参照ブロックを介して連携し、認証情報にはシークレットを使用します。

resource "materialize_connection_kafka" "kafka" {
  name              = "kafka_conn"
  security_protocol = "SASL_SSL"
  sasl_mechanisms   = "SCRAM-SHA-256"

  kafka_broker {
    broker = "broker1.example.com:9092"
  }

  sasl_username {
    text = "my_user"
  }

  sasl_password {
    secret {
      name = materialize_secret.kafka_password.name
    }
  }
}

resource "materialize_source_kafka" "events" {
  name         = "events_source"
  cluster_name = materialize_cluster.analytics.name

  kafka_connection {
    name = materialize_connection_kafka.kafka.name
  }
}

resource "materialize_source_table_kafka" "events_table" {
  name  = "events"
  topic = "events-topic"

  source {
    name = materialize_source_kafka.events.name
  }

  format {
    avro {
      schema_registry_connection {
        name = materialize_connection_confluent_schema_registry.sr.name
      }
    }
  }

  envelope {
    upsert = true
  }
}

規約

• 修飾名：ほとんどのリソースには読み取り専用の qualified_sql_name（database.schema.object）があります。リソース間の参照ブロックでは name、database_name、schema_name を指定します。後者 2 つのデフォルト値はそれぞれ materialize と public です。
• シークレットまたはテキスト：認証情報の引数には、上記の例のようにインラインの text または secret {} 参照ブロックを指定できます。シークレットの使用を推奨します。
• 共通の引数：ほとんどのリソースは database_name、schema_name、comment、ownership_role、region に対応しています。接続ではさらに validate にも対応しています。
• 名前で識別：materialize_cluster と materialize_schema は identify_by_name = true に対応しており、内部の Materialize ID の代わりにオブジェクト名を状態 ID として使用します。Terraform の状態を変更せずにクラスターを入れ替えるブルーグリーンデプロイに便利です。
• 書き込み専用の引数（Terraform 1.11 以降）：materialize_role.password_wo と materialize_secret.value_wo（および対応する *_wo_version）は Terraform の状態に保存されません。通常の機密値はプランの出力では非表示になりますが、状態には保存されます。

既存のリソースのインポート

terraform import materialize_cluster.my_cluster <region>:<cluster_id>
# or with identify_by_name:
terraform import materialize_cluster.my_cluster <region>:name:<cluster_name>

各生成リソースのドキュメントには、正確なインポート形式が記載されています。オブジェクト ID は mz_catalog システムテーブル（mz_clusters、mz_databases、mz_schemas、mz_sources、mz_sinks、mz_views、mz_connections、mz_secrets、mz_roles）で確認できます。

よくある注意点

• クラウドとセルフ管理：Frontegg に依存するリソース（ユーザー、SSO、SCIM、アプリパスワード）は、セルフ管理インスタンスでは動作しません。
• パブリックスキーマのないデータベース：materialize_database は public スキーマを自動作成しません。必要に応じて明示的に作成してください。
• ソーステーブルの移行：ソースリソース内のインライン table {} ブロックは非推奨となり、個別の materialize_source_table_* リソースが推奨されています。プロバイダーリポジトリの docs/guides/materialize_source_table.md を参照してください。
• Webhook ソース：materialize_source_webhook はレガシーです。新しい Webhook では Webhook 対応の materialize_table を使用してください。ただし、自動移行にはまだ対応していません。
• クラスターレプリカの非推奨：管理対象クラスターでは、size を指定した materialize_cluster を使用してください。
• ステート内のシークレット：センシティブとしてマークされた値はプランの出力には表示されませんが、ステートには保存されます。ステートに一切保存されないようにするには、Terraform 1.11 以降で書き込み専用（*_wo）引数を使用してください。

このスキルを最新の状態に保つ

リソースごとのリファレンスはここに重複して記載されていないため、古くなることはありません。プロバイダーリポジトリ内の生成ドキュメントは、同梱されているリリースに対して常に最新です。フロントマターの verified-against 値には、キュレーションされたコンテンツ（パターン、注意点、リソースマップ）を最後に検証したプロバイダーのコミットが記録されています。更新するには：

1. そのコミットから現在の main までプロバイダーリポジトリの差分を確認し、新規または非推奨のリソース、docs/guides/、CHANGELOG の項目に注目します。
2. 動作に変更があった場合は、リソースマップ、パターン、注意点をここで更新します。
3. verified-against を新しいコミット SHA に更新します。