materialize-terraform-provider

Materialize Terraform Provider

MaterializeInc/materialize Terraform 提供程序以声明式方式管理 Materialize 资源。它同时适用于 Materialize Cloud（SaaS）和自托管部署。

本技能不会重复介绍各资源的参数参考。该提供程序会根据架构自动生成所有资源和数据源的完整文档，这些文档是权威信息来源。本技能会告诉你在哪里可以找到这些参考文档，并仅介绍生成文档中没有的内容：提供程序设置、跨资源模式、导入工作流和注意事项。

权威参考文档的位置

生成的文档位于提供程序代码库中，也可在 Terraform Registry 上找到：

• 代码库：terraform-provider-materialize 中的 docs/，见 terraform-provider-materialize
• 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}
• Sink：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
• 数据源：以上资源的只读列表（集群、源、视图、角色等），以及 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，后两者默认值分别为 materialize 和 public。
• 密钥或文本：凭据参数接受内联 text 或 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>
# or with 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）。

常见注意事项

• Cloud 与自托管实例：依赖 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）参数，可将这些值完全排除在状态之外。

让此技能保持最新

这里的每项资源参考都不会过时，因为这里没有重复这些内容：提供程序仓库中生成的文档始终与其随附的版本保持同步。frontmatter 中的 verified-against 值记录了最后一次核验整理内容（模式、注意事项、资源映射）所依据的提供程序提交。要更新：

1. 对比该提交与当前 main 分支之间的提供程序仓库差异，重点关注新增或已弃用的资源、docs/guides/ 和 CHANGELOG 条目。
2. 如果行为发生变化，请在此处更新资源映射、模式和注意事项。
3. 将 verified-against 更新为新的提交 SHA。