Terraform AWS Provider 数据源 aws_msk_bootstrap_brokers 完全指南:获取 MSK 集群引导 Broker 端点

原创2026-09-19 12:25:481,670 阅读
文章标签:IaC云原生DevOps运维配置管理

Terraform AWS Provider 数据源 aws_msk_bootstrap_brokers 完全指南:获取 MSK 集群引导 Broker 端点

aws_msk_bootstrap_brokers 是 Terraform AWS Provider 中用于获取 Amazon Managed Streaming for Apache Kafka(MSK)集群引导端点(bootstrap broker)列表的数据源。本指南以 官方数据源文档 为主体,结合仓库源码与测试用例,系统讲解其用法、全部输出属性、底层 API 调用原理与实战注意事项;读完你将能够为任意 MSK 集群(含 Serverless 与 DUAL 双栈网络)精准取回各接入方式下的 broker 端点,并直接用于客户端引导连接。

数据源概览:bootstrap brokers 是什么

Kafka 客户端要连接一个 Kafka 集群,必须先通过一组"引导服务器"(bootstrap servers)发现集群内的 broker 拓扑。MSK 会在集群创建后为不同接入方式分别生成一组 hostname:port 端点,例如普通明文、TLS、SASL/IAM、SASL/SCRAM、公网访问、VPC connectivity 以及 IPv6 双栈等组合。aws_msk_bootstrap_brokers 数据源的作用就是把"根据集群 ARN 查询并整理这些端点"的过程封装成一次只读的数据查询,供 Terraform 配置内直接引用。

它与 aws_msk_cluster、aws_msk_serverless_cluster 等资源天然配合:集群资源创建完成后,通过该数据源拿到端点,再注入到下游 Kafka 客户端配置、ECS 任务定义或 EC2 user-data 中,即可完成"基础设施即代码"式的客户端引导。

基本用法

在 Terraform 配置中声明该数据源,唯一必填参数是目标集群的 ARN:

data "aws_msk_bootstrap_brokers" "example" {
  cluster_arn = aws_msk_cluster.example.arn
}

完整可运行示例

结合仓库中 bootstrap_brokers_data_source_test.go 的验收测试配置,一个完整的最小示例(含 MSK 集群本身)如下:

resource "aws_msk_cluster" "example" {
  cluster_name           = "example-msk-cluster"
  kafka_version          = "3.8.x"
  number_of_broker_nodes = 3

  broker_node_group_info {
    client_subnets  = aws_subnet.example[*].id
    instance_type   = "kafka.t3.small"
    security_groups = [aws_security_group.example.id]

    storage_info {
      ebs_storage_info {
        volume_size = 10
      }
    }
  }

  tags = {
    Name = "example-msk-cluster"
  }
}

data "aws_msk_bootstrap_brokers" "example" {
  cluster_arn = aws_msk_cluster.example.arn
}

# 将明文引导端点注入客户端引导参数
output "bootstrap_brokers" {
  value = data.aws_msk_bootstrap_brokers.example.bootstrap_brokers
}

数据源本身是只读操作,不创建任何资源;它将查询到的端点集合以逗号分隔字符串的形式暴露为属性,供 output、template、user_data 等任意下游引用。

参数(Argument Reference)

参数 类型 必填 说明
cluster_arn string 是 broker 所属 MSK 集群的 ARN。在源码中,该参数由 schema.TypeString 定义并标记为 Required: true,同时通过 verify.ValidARN 做了 ARN 格式校验,传入非 ARN 值会直接报错(见 bootstrap_brokers_data_source.go)
region string 否 数据源所属区域,默认取 provider 配置 中设置的区域;仅当数据源需要在与 provider 不同的区域查询集群时显式指定

输出属性(Attribute Reference)

除参数本身外,数据源还导出以下 13 个计算属性。它们与 MSK GetBootstrapBrokers API 的返回字段一一对应,全部为逗号分隔的 hostname:port 端点字符串:

属性 内容
bootstrap_brokers 一个或多个 hostname:port 对,适用于以明文方式引导连接 Kafka 集群(默认接入方式)
bootstrap_brokers_public_sasl_iam 公网接入下的 SASL/IAM 端口对(用于 IAM 认证的公网访问)
bootstrap_brokers_public_sasl_scram 公网接入下的 SASL/SCRAM 端口对
bootstrap_brokers_public_tls 公网接入下的 TLS 端口对
bootstrap_brokers_sasl_iam VPC 内 SASL/IAM 端口对
bootstrap_brokers_sasl_scram VPC 内 SASL/SCRAM 端口对
bootstrap_brokers_tls VPC 内 TLS 端口对
bootstrap_brokers_vpc_connectivity_sasl_iam VPC connectivity 接入方式下的 SASL/IAM 端口对
bootstrap_brokers_vpc_connectivity_sasl_scram VPC connectivity 接入方式下的 SASL/SCRAM 端口对
bootstrap_brokers_vpc_connectivity_tls VPC connectivity 接入方式下的 TLS 端口对
bootstrap_brokers_ipv6 网络类型为 DUAL(双栈)时,明文端点的 IPv6 主机名(或 IP 地址)与端口对
bootstrap_brokers_sasl_iam_ipv6 双栈集群下 SASL/IAM 认证的 IPv6 端点对
bootstrap_brokers_sasl_scram_ipv6 双栈集群下 SASL/SCRAM 认证的 IPv6 端点对
bootstrap_brokers_tls_ipv6 双栈集群下 TLS 认证的 IPv6 端点对

实际返回哪些属性取决于集群自身的配置:只有启用了公网访问(public_access)、VPC connectivity 或 DUAL 网络类型的集群,对应的 public_*、vpc_connectivity_*、*_ipv6 属性才会有值;未启用的属性为空字符串。这一点从 bootstrap_brokers_data_source.go 中所有属性均为 Computed: true 的 schema 定义可以印证——它们是只读计算结果,不是用户输入。

底层实现剖析:一次数据源读取发生了什么

从源码看,该数据源的完整读取链路如下(见 bootstrap_brokers_data_source.go):

  1. 通过 meta.(*conns.AWSClient).KafkaClient(ctx) 取得当前 provider 配置下的 Kafka SDK v2 客户端;
  2. 从 Terraform state 中读取 cluster_arn;
  3. 调用 findBootstrapBrokersByARN(ctx, conn, clusterARN) 发起查询;
  4. 以集群 ARN 作为资源 ID(d.SetId(clusterARN));
  5. 将返回的每个端点字符串经 sortEndpointsString 排序后写入对应属性。

查询函数:findBootstrapBrokersByARN

该函数定义在 cluster.go,本质上是对 MSK GetBootstrapBrokers API 的封装:

func findBootstrapBrokersByARN(ctx context.Context, conn *kafka.Client, arn string) (*kafka.GetBootstrapBrokersOutput, error) {
	input := kafka.GetBootstrapBrokersInput{
		ClusterArn: aws.String(arn),
	}
	return findBootstrapBrokers(ctx, conn, &input)
}

func findBootstrapBrokers(ctx context.Context, conn *kafka.Client, input *kafka.GetBootstrapBrokersInput) (*kafka.GetBootstrapBrokersOutput, error) {
	output, err := conn.GetBootstrapBrokers(ctx, input)

	if errs.IsA*types.NotFoundException {
		return nil, &retry.NotFoundError{LastError: err}
	}
	if err != nil {
		return nil, err
	}
	if output == nil {
		return nil, tfresource.NewEmptyResultError()
	}
	return output, nil
}

值得注意的细节:

  • 请求只携带 ClusterArn 一个字段,一次调用即可取回全部接入方式的端点;
  • 对 NotFoundException 做了显式转换(retry.NotFoundError),并把 nil 响应转换为空结果错误,这使数据源在集群不存在时能给出清晰、可重试的错误语义;
  • 数据源读取出错时,错误信息会带上集群 ARN 以方便定位:reading MSK Cluster (%s) bootstrap brokers: ...。

端点排序:sortEndpointsString

MSK API 返回的端点顺序并不保证稳定,因此 provider 在写入属性前统一做了排序。实现位于 sort.go:

func sortEndpointsString(s string) string {
	parts := strings.Split(s, endpointSeparator) // endpointSeparator = ","
	slices.Sort(parts)
	return strings.Join(parts, endpointSeparator)
}

即按逗号切分、字典序排序、再以逗号拼接。这样无论底层 API 返回顺序如何,同一集群查询多次得到的属性值都是确定性的,避免 Terraform 因顺序变化产生无意义的 diff。

同一个 Finder 被多处复用

findBootstrapBrokersByARN 并非该数据源独享,而是整个 MSK 服务包的共享工具:

因此,无论你通过 aws_msk_cluster 资源、aws_msk_cluster 数据源还是本数据源获取端点,底层都走同一条 GetBootstrapBrokers 链路,结果一致、可互相印证。

测试验证:属性一一对应的验收用例

仓库为数据源提供了完整的验收测试(bootstrap_brokers_data_source_test.go)。测试 TestAccKafkaBootstrapBrokersDataSource_basic 会真实创建 aws_msk_cluster.test,然后用 resource.TestCheckResourceAttrPair 将数据源的 13 个输出属性与集群资源上对应的 13 个属性逐一比对:

resource.TestCheckResourceAttrPair(dataSourceName, "bootstrap_brokers", resourceName, "bootstrap_brokers"),
resource.TestCheckResourceAttrPair(dataSourceName, "bootstrap_brokers_public_sasl_iam", resourceName, "bootstrap_brokers_public_sasl_iam"),
// ... 其余 11 个属性同理

这组断言同时验证了两件事:数据源取回的端点与集群资源读取的端点完全一致;schema 中所有计算属性都能正确写入 state。如果你扩展了 MSK 相关功能,可以以此测试为模板补充新的属性断言。

实战建议与常见问题

  1. 按认证方式选择属性:客户端配置时应根据集群实际启用的认证方式选择对应端点。明文接入用 bootstrap_brokers,TLS 用 bootstrap_brokers_tls,IAM 认证用 bootstrap_brokers_sasl_iam,SCRAM 认证用 bootstrap_brokers_sasl_scram。属性返回空字符串通常意味着该接入方式未在集群上启用,属于预期行为而非错误。
  2. 公网与 VPC connectivity:只有为集群配置了公网访问(Public Access)或 VPC connectivity 时,bootstrap_brokers_public_*、bootstrap_brokers_vpc_connectivity_* 才非空;结合对应安全组与网络配置使用。
  3. IPv6 双栈集群:网络类型为 DUAL 的集群请使用 *_ipv6 系列属性,它们返回 IPv6 形式的 DNS 名(或 IP 地址)与端口对。
  4. Serverless 集群:aws_msk_serverless_cluster 只暴露 bootstrap_brokers_sasl_iam,Serverless 场景下客户端应固定使用 IAM 认证端点。
  5. 确定性输出:provider 已对端点做排序归一化,同一集群反复 apply 不会产生 diff;你可以在 output 或 user_data 中安全地依赖这些字符串。
  6. cluster_arn 必须为合法 ARN:参数在 schema 层就通过 verify.ValidARN 校验,传错格式会在 plan/apply 阶段直接报错,便于尽早发现问题。

延伸阅读

登录后查看全文
terraform-provider-aws