本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 端到端设置自定义域名
<a name="custom-domain-setup"></a>

本主题介绍自定义域名的集群端配置。网络层（网络负载均衡器、DNS 和 TLS 证书）是您拥有的先决条件，详见 AWS 大数据博客[上的 Amazon MSK 集群](https://aws.amazon.com/blogs/big-data/configure-a-custom-domain-name-for-your-amazon-msk-cluster/)配置自定义域名。联网到位后，以下步骤将涵盖集群端设置。

**在应用配置之前验证网络**  
当您申请时`custom.advertised.listeners`，您的自定义域名将替换被覆盖侦听器的默认地址。在应用配置之前，您的网络层必须到位并经过验证。如果客户无法解析自定义域，他们就会断开连接。

## 第 1 步：将自定义域添加到您的亚马逊 MSK 配置中
<a name="custom-domain-setup-step1"></a>

创建或更新包含该`custom.advertised.listeners`属性的 Amazon MSK 配置，与您在网络负载均衡器上配置的主机名和端口相匹配。对于以端口 9001—9003 的网络负载均衡器为前端的三代理 IAM 集群，请将该属性放入文件中。

```
custom.advertised.listeners=CLIENT_IAM://b-{broker_id}.example.com:9000+{broker_id}
```

然后创建配置，将该文件作为服务器属性传递。

```
aws kafka create-configuration \
    --name "custom-domain-iam" \
    --description "Custom advertised listeners for CLIENT_IAM" \
    --server-properties fileb://custom-domain-config.txt
```

使用`fileb://`（不使用`file://`），这样可以将文件 AWS CLI 读取为字节并对其进行 base64 编码。由于有大`{broker_id}`括号，内联传递值很脆弱。在文件中保留`{broker_id}`文字，因为 Amazon MSK 会在申请时针对每个经纪人进行解析。响应返回配置`Arn`和`LatestRevision.Revision`，供您在下一步中使用。

## 步骤 2：应用配置
<a name="custom-domain-setup-step2"></a>

使用控制台`UpdateClusterConfiguration`、、、 AWS CDK 或 Terraform 将配置应用于您的集群。 AWS CLI AWS CloudFormation这与您已经用于代理配置更改的工作流程相同。

```
aws kafka update-cluster-configuration \
    --cluster-arn {{your-cluster-arn}} \
    --configuration-info arn={{configuration-arn}},revision={{revision}} \
    --current-version {{current-cluster-version}}
```

使用`DescribeCluster`操作查找集群的当前版本。集群版本不是简单的整数。

在应用任何配置之前，Amazon MSK 会同步验证配置，因此格式错误的值永远不会到达您的经纪人。亚马逊 MSK 拒绝带有 HTTP 400 错误的无效配置。有关错误的示例，请参阅[自定义域名配置错误](troubleshooting.md#troubleshoot-custom-domain-name-errors)。修复报告的问题并重新申请。

## 第 3 步：追踪上线情况
<a name="custom-domain-setup-step3"></a>

```
aws kafka describe-cluster-operation-v2 \
    --cluster-operation-arn {{operation-arn}}
```

接受配置后，Amazon MSK 将通过滚动重启来应用该配置。等到操作报告`UPDATE_COMPLETE`。如果它报告`UPDATE_FAILED`，则经纪人无法应用变更。该代理的部署将暂停，其余代理保留其先前的配置，您可以修复配置并重新应用以进行恢复。

## 第 4 步：验证
<a name="custom-domain-setup-step4"></a>

通过列出使用侦听器身份验证设置的客户端的主题，确认客户端可以通过自定义域进行连接。

如果您可以通过自定义域终端节点列出主题，则客户端已成功通过您的自定义域进行连接。如果操作已报告`UPDATE_COMPLETE`但客户端无法连接，则集群端配置正确，但您的网络层可能需要注意。请检查以下事项：
+ **网络路径**：确认客户端使用的代理和端口存在网络负载均衡器监听器、目标组和安全组规则，并且可以从客户端的网络访问网络负载均衡器。
+ **DNS 解析**：确认自定义域已从运行 Apache Kafka 客户端的每个网络解析到您的网络负载均衡器。
+ **证书**：确认网络负载均衡器的 TLS 证书涵盖已解析的代理主机名（通过公用名或主题备用名称），并且客户端信任 CA（私有 CA 的根和中间服务器）。

## 扩容和代理更换
<a name="custom-domain-setup-scaling"></a>

当您扩展集群或在自动修复期间更换代理时，Amazon MSK 会自动将配置应用于新代理。Amazon MSK 解析`{broker_id}`代理的 ID，无需在集群端执行手动步骤。

**注意**  
为任何新代理添加相应的网络负载均衡器监听器、目标组和 DNS 记录。网络层不会自动扩展。

## 移除自定义域
<a name="custom-domain-setup-remove"></a>

要恢复为默认的亚马逊 MSK-generated 地址，请从您的亚马逊 MSK 配置中删除该`custom.advertised.listeners`属性，然后使用`UpdateClusterConfiguration`应用更新的配置。亚马逊 MSK 执行滚动重启，经纪人恢复公布其原始地址。在删除自定义域名配置之前，请确保您的客户可以访问原始的亚马逊 MSK-generated 地址。