materialize-terraform-provider

用途

Materialize Terraform Provider 用于以声明式方式管理 Materialize 资源，适用于 Materialize Cloud（SaaS）和自托管部署。该技能刻意不重复每个资源的参数参考，因为提供程序会从 schema 自动生成所有资源和数据源的完整文档，那才是权威来源。本技能只承载生成文档未包含的知识：提供程序配置、跨资源模式、导入工作流和常见陷阱。

权威参考位置

生成文档位于提供程序仓库和 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 可给出精确的 schema 作为事实依据。

提供程序配置

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
  # 对任何启用 TLS 的部署使用 "require"（或更严格，如 "verify-full"）。
  # "disable" 仅适用于本地、非 TLS 实例。
  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
对象授权：每种对象类型一个资源（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
数据源：上述资源的只读列表（clusters、sources、views、roles 等），外加 materialize_egress_ips、materialize_current_cluster、materialize_current_database。全部支持区域过滤。

跨资源模式

这些约定适用于大多数资源，逐页阅读文档时容易遗漏。

一个完整示例：连接、源和源表通过嵌套引用块组合，凭据来自 secret：

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，后两者默认为 materialize 和 public。
Secret 或文本：凭据参数接受内联文本或 secret {} 引用块，如上述示例。优先使用 secret。
通用参数：大多数资源支持 database_name、schema_name、comment、ownership_role 和 region；连接还支持 validate。
按名称识别：materialize_cluster 和 materialize_schema 支持 identify_by_name = true，使用对象名称作为状态 ID 而非内部 Materialize 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>
# 或使用 identify_by_name：
terraform import materialize_cluster.my_cluster <region>:name:<cluster_name>

每个生成的资源文档显示确切的导入格式。在 mz_catalog 系统表中查找对象 ID（mz_clusters、mz_databases、mz_schemas、mz_sources、mz_sinks、mz_views、mz_connections、mz_secrets、mz_roles）。

常见陷阱

云与自托管：依赖 Frontegg 的资源（用户、SSO、SCIM、应用密码）在自托管实例上会失败。
无 public schema 的数据库：materialize_database 不会自动创建 public schema。如需要请显式创建。
源表迁移：源资源中的内联 table {} 块已弃用，推荐使用单独的 materialize_source_table_* 资源。参见提供程序仓库中的 docs/guides/materialize_source_table.md。
Webhook 源：materialize_source_webhook 是旧版。新 webhook 应使用支持 webhook 的 materialize_table，但尚无自动迁移。
集群副本已弃用：托管集群请使用带 size 的 materialize_cluster。
状态中的 secret：标记为敏感的值在计划输出中隐藏，但存储在状态中。在 Terraform 1.11+ 上使用只写（*_wo）参数将其完全排除在状态之外。

保持此技能更新

每个资源的参考在此不会过时，因为它没有在此重复：提供程序仓库中的生成文档始终对其随附的版本保持最新。frontmatter 中的 verified-against 值记录精选内容（模式、陷阱、资源地图）最后验证的提供程序提交。刷新方法：

从该提交到当前 main 对比提供程序仓库，关注新增或弃用的资源、docs/guides/ 和 CHANGELOG 条目。
如果行为改变，更新此处的资源地图、模式和陷阱。
将 verified-against 提升到新的提交 SHA。