如何一键盘点整个 Kafka 集群?terraform-provider-kafka 的 kafka_topics 数据源完全指南
如何一键盘点整个 Kafka 集群?terraform-provider-kafka 的 kafka_topics 数据源完全指南
📊 terraform-provider-kafka 是一个 Terraform Provider,用于管理 Apache Kafka 的 Topic、ACL 和 Quota。它的 kafka_topics 数据源只需一行声明,就能把整个 Kafka 集群里的所有 Topic 一次性"盘点"出来:名称、分区数、副本数、自定义配置,全部自动拉取。本文将带你从零配置到实战,用 3 步完成集群级 Topic 审计。
为什么需要 kafka_topics 数据源?
集群里 Topic 越积越多,常见难题:
- 🔍 不知道集群里到底有哪些 Topic,哪些是废弃的?
- 📦 迁移/扩容前,需要一份完整的 Topic 配置清单?
- ✅ 合规审计,要检查每个 Topic 的
retention.ms、replication_factor是否达标?
传统做法是手动登录节点执行 kafka-topics.sh --describe,而 kafka_topics 数据源让你用声明式配置一次完成,且结果可以直接被 Terraform 的其他资源引用。
项目速览:terraform-provider-kafka 能做什么?
| 功能 | 类型 | 说明 |
|---|---|---|
kafka_topic |
资源 + 数据源 | 创建/管理单个 Topic |
kafka_topics |
数据源 | 一次性读取集群中所有 Topic |
kafka_acl |
资源 | 管理 Topic/Group/Cluster 的访问控制 |
kafka_quota |
资源 | 管理消费/生产速率配额 |
kafka_user_scram_credential |
资源 | 管理 SCRAM 用户凭证 |
Provider 支持 TLS 双向认证、SASL(plain / scram-sha256 / scram-sha512 / aws-iam / oauthbearer),完整参数见 README.md 和 docs/guides/authentication.md。
三步快速上手:一键盘点集群
第 1 步:配置 provider 连接集群
只需一个必填参数 bootstrap_servers,加上 TLS 证书即可完成安全连接:
provider "kafka" {
bootstrap_servers = ["kafka1:9092", "kafka2:9092"]
tls_enabled = true
ca_cert = file("secrets/ca.crt")
client_cert = file("secrets/client.pem")
client_key = file("secrets/client.key")
}
💡 开发环境可设置
skip_tls_verify = true;AWS MSK 则改用sasl_mechanism = "aws-iam",参考 docs/guides/quick-start.md。
第 2 步:声明 kafka_topics 数据源
data "kafka_topics" "inventory" {}
就这么简单,无需任何必填属性。它会自动连接集群并枚举全部 Topic。
第 3 步:查看盘点结果
output "total_topics" {
value = length(data.kafka_topics.inventory.list)
}
output "topic_report" {
value = data.kafka_topics.inventory.list
}
执行 terraform apply 后,terraform output topic_report 即可看到每个 Topic 的完整信息。🎉
理解返回的数据结构
kafka_topics 返回一个 list 属性(Topic 对象数组),每个对象包含 4 个字段(源码定义见 kafka/data_source_kafka_topics.go):
| 字段 | 类型 | 说明 |
|---|---|---|
topic_name |
String | Topic 名称 |
partitions |
Number | 分区数量 |
replication_factor |
Number | 副本数量 |
config |
Map of String | 自定义配置键值对 |
两个实用细节:
config只返回非默认配置——Provider 内部会过滤掉集群默认值(见 kafka/client.go),所以输出精简、没有噪音。- 数据源自身的
id就是 Topic 总数,方便快速判断集群规模。
底层读取逻辑在 kafka/client.go:先 Topics() 枚举全部 Topic,再逐个 ReadTopic 拉取分区、副本和配置详情。
实战场景:把盘点结果用起来 🛠
场景 1:生成集群 Topic 清单文件
把盘点结果导出为 JSON,交给团队存档或用于迁移规划:
resource "local_file" "cluster_inventory" {
filename = "kafka-topic-inventory.json"
content = jsonencode(data.kafka_topics.inventory.list)
}
场景 2:合规检查——找出副本数不足的 Topic
locals {
weak_topics = [
for t in data.kafka_topics.inventory.list : t.topic_name
if t.replication_factor < 3
]
}
output "topics_below_rf3" {
value = local.weak_topics
}
配合 config 中的 retention.ms、min.insync.replicas 等参数,可以构建完整的 Topic 健康度报表。
场景 3:与 kafka_topic 数据源组合使用
kafka_topics 负责"看全局",kafka_topic 数据源 负责"查单个",二者可配合:先盘点发现可疑 Topic,再单独深挖其配置。
常见问题排查 ❓
| 问题 | 排查思路 |
|---|---|
| 连接超时 | 检查 bootstrap_servers 地址/端口,必要时调大 timeout(默认 120 秒) |
| TLS 握手失败 | 确认 ca_cert 与集群证书匹配;Provider 内置 TLS 诊断日志,开启 -log-level=DEBUG 查看 |
| Topic 列表为空 | 确认当前用户具备 Describe 权限(参考 docs/guides/authentication.md) |
MSK Serverless 下 segment.bytes 缺失 |
属正常行为,Provider 会主动跳过该参数以避免无谓变更(kafka/client.go) |
更多问题参考 docs/guides/troubleshooting.md。
相关文档与源码
- 数据源 Schema 文档:docs/data-sources/topics.md
- 数据源实现:kafka/data_source_kafka_topics.go
- 数据源验收测试(可参考其中的断言写法):kafka/data_source_kafka_topics_test.go
- Provider 参数注册:kafka/provider.go
- 完整使用示例:examples/main.tf
总结
kafka_topics 数据源是 terraform-provider-kafka 中做集群级 Topic 盘点的最佳工具:
- ⚡ 零属性声明,一行代码读取全集群 Topic
- 📋 输出结构化数据(名称/分区/副本/配置),可直接用于审计报表和迁移规划
- 🔗 与
kafka_topic、kafka_acl等资源无缝组合,把"盘点"延伸为"治理"
如果你正在管理多环境 Kafka 集群,不妨今天就把它加进你的 Terraform 工作流。