你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：使用 Azure Managed Instance for Apache Cassandra 配置混合群集

2025-07-22

Azure Managed Instance for Apache Cassandra 是针对纯开源 Apache Cassandra 群集的完全托管服务。该服务还允许替代配置，具体取决于每个工作负载的特定需求，以实现最大的灵活性和控制。

本快速入门演示如何使用 Azure CLI 命令配置混合群集。如果本地或自承载环境中已有数据中心，可以使用适用于 Apache Cassandra 的 Azure 托管实例将这些数据中心添加到这些群集并维护这些数据中心。

Prerequisites

在 Azure Cloud Shell 中使用 Bash 环境。有关详细信息，请参阅 Azure Cloud Shell 入门。
如果要在本地运行 CLI 引用命令，请安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
- 如果使用的是本地安装，请使用 az login 命令登录到 Azure CLI。要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 向 Azure 进行身份验证。
- 如果系统发出提示，则在首次使用时安装 Azure CLI 扩展。有关扩展的详细信息，请参阅使用和管理 Azure CLI 中的扩展。
- 运行 az version 以查找所安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

本文需要 Azure CLI 2.30.0 或更高版本。如果你使用的是 Azure Cloud Shell，则表示已安装最新版本。
使用 Azure 虚拟网络与自承载环境或本地环境建立连接。有关如何将本地环境连接到 Azure 的详细信息，请参阅将本地网络连接到 Azure。

配置混合群集

登录到 Azure 门户并转到虚拟网络资源。
选择“ 子网 ”选项卡，并创建新子网。若要详细了解 “添加子网 ”窗体上的字段，请参阅 “添加子网”。

Azure 托管实例用于 Apache Cassandra 的部署需要互联网访问。在限制 Internet 访问权限的环境中，部署将失败。确保不会阻止虚拟网络中访问以下重要的 Azure 服务，这些服务是 Apache Cassandra 的 Azure 托管实例正常运行所必需的。有关 IP 地址和端口依赖项的列表，请参阅所需的出站网络规则。
- Azure 存储
- Azure Key Vault
- Azure 虚拟机规模集
- Azure Monitor
- Microsoft Entra ID
- Microsoft Defender for Cloud
使用 Azure CLI 将一些特殊权限应用于 Azure 托管实例 for Apache Cassandra 所需的虚拟网络和子网。使用 az role assignment create 命令。替换 <subscriptionID>、<resourceGroupName> 和 <vnetName> 为相应的值。
```
az role assignment create \
  --assignee a232010e-820c-4083-83bb-3ace5fc29d0b \
  --role 4d97b98b-1d4f-4787-a291-c67834d212e7 \
  --scope /subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.Network/virtualNetworks/<vnetName>
```
在上一命令中，assignee值是固定的服务主体标识符，role值是角色标识符。
为混合群集配置资源。由于已有群集，因此群集名称是用于标识现有群集名称的逻辑资源。在以下脚本中定义 clusterName 和 clusterNameOverride 变量时，请使用现有群集的名称。

你还至少需要来自现有数据中心的种子节点，以及节点到节点加密所需的 gossip 证书。 Azure Managed Instance for Apache Cassandra 需要将节点到节点加密用于数据中心之间的通信。如果没有在现有群集中实现节点到节点加密，则需要实现它。有关详细信息，请参阅节点到节点加密。提供证书位置的路径。每个证书应采用隐私增强邮件（PEM）格式，例如 -----BEGIN CERTIFICATE-----\n...PEM format 1...\n-----END CERTIFICATE-----。一般情况下，可通过两种方法实现证书：
- 自签名证书。 每个节点都没有证书颁发机构 (CA) 的专用和公共证书。在这种情况下，需要所有公共证书。
- 由 CA 签名的证书。 由自签名 CA 或公共 CA 颁发的证书。在这种情况下，需要根 CA 证书和所有中间证书（如果适用）。有关详细信息，请参阅准备用于生产的安全套接字层（SSL）证书。
（可选）如果要实现客户端到节点证书身份验证或相互传输层安全性（TLS），请以与创建混合群集时相同的格式提供证书。请参阅本文后面的 Azure CLI 示例。参数中 --client-certificates 提供了证书。

此方法将客户端证书上传到 Azure Managed Instance for Apache Cassandra 群集的信任存储。无需编辑 cassandra.yaml 设置。应用证书后，群集要求 Cassandra 在客户端连接时验证证书。有关详细信息，请参阅 require_client_auth: true Cassandra client_encryption_options。

在此代码中提供的变量的值 delegatedManagementSubnetId 与前面命令中提供的变量值 --scope 相同：
```
resourceGroupName='MyResourceGroup'
clusterName='cassandra-hybrid-cluster-legal-name'
clusterNameOverride='cassandra-hybrid-cluster-illegal-name'
location='eastus2'
delegatedManagementSubnetId='/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>'

# You can override the cluster name if the original name isn't legal for an Azure resource:
# overrideClusterName='ClusterNameIllegalForAzureResource'
# the default cassandra version will be v3.11

az managed-cassandra cluster create \
  --cluster-name $clusterName \
  --resource-group $resourceGroupName \
  --location $location \
  --delegated-management-subnet-id $delegatedManagementSubnetId \
  --external-seed-nodes 10.52.221.2 10.52.221.3 10.52.221.4 \
  --external-gossip-certificates /usr/csuser/clouddrive/rootCa.pem /usr/csuser/clouddrive/gossipKeyStore.crt_signed
  # optional - add your existing datacenter's client-to-node certificates (if implemented):
  # --client-certificates /usr/csuser/clouddrive/rootCa.pem /usr/csuser/clouddrive/nodeKeyStore.crt_signed
```
如果群集已具有节点到节点和客户端到节点加密，则你应知道现有客户端或 gossip TLS/SSL 证书的保存位置。如果不确定，请运行 keytool -list -keystore <keystore-path> -rfc -storepass <password> 以打印证书。

创建群集资源后，运行以下命令获取群集设置详细信息：

resourceGroupName='MyResourceGroup'
clusterName='cassandra-hybrid-cluster'

az managed-cassandra cluster show \
   --cluster-name $clusterName \
   --resource-group $resourceGroupName \

上述命令会返回托管实例环境的相关信息。你需要 gossip 证书，以便可将它们安装在现有数据中心内节点的信任存储上。以下屏幕截图显示了上一命令的输出和证书格式。

从上述命令行返回的证书包含以文本表示的换行符。示例为 \r\n。将每个证书复制到一个文件，并在尝试将其导入现有信任存储之前对其进行格式化。

将 gossipCertificates 屏幕截图中显示的数组值复制到文件中。使用以下 Bash 脚本设置证书的格式，并为每个证书创建单独的 PEM 文件。若要下载 Bash 脚本，请参阅适用于平台的下载 jq 。
```
readarray -t cert_array < <(jq -c '.[]' gossipCertificates.txt)
# iterate through the certs array, format each cert, write to a numbered file.
num=0
filename=""
for item in "${cert_array[@]}"; do
let num=num+1
filename="cert$num.pem"
cert=$(jq '.pem' <<< $item)
echo -e $cert >> $filename
sed -e 's/^"//' -e 's/"$//' -i $filename
done
```
接下来，在混合群集中创建新的数据中心。将变量值替换为群集详细信息：
```
resourceGroupName='MyResourceGroup'
clusterName='cassandra-hybrid-cluster'
dataCenterName='dc1'
dataCenterLocation='eastus2'
virtualMachineSKU='Standard_D8s_v4'
noOfDisksPerNode=4

az managed-cassandra datacenter create \
  --resource-group $resourceGroupName \
  --cluster-name $clusterName \
  --data-center-name $dataCenterName \
  --data-center-location $dataCenterLocation \
  --delegated-subnet-id $delegatedManagementSubnetId \
  --node-count 9
  --sku $virtualMachineSKU \
  --disk-capacity $noOfDisksPerNode \
  --availability-zone false
```
在以下可用的产品层中选择 --sku 的值。
- Standard_E8s_v4
- Standard_E16s_v4
- Standard_E20s_v4
- Standard_E32s_v4
- Standard_DS13_v2
- Standard_DS14_v2
- Standard_D8s_v4
- Standard_D16s_v4
- Standard_D32s_v4
--availability-zone 的值设置为 false。若要启用可用性区域，请将此值设置为 true。可用性区域增加了服务的可用性服务级别协议（SLA）。有关详细信息，请参阅联机服务的 SLA。

并非所有区域都支持可用性区域。如果选择不支持可用性区域的区域，则部署会失败。有关支持的区域，请参阅 Azure 区域列表。

成功部署可用性区域也会受到特定区域中所有区域中计算资源的可用性。如果所选产品层或容量在所有区域中不可用，则部署可能会失败。

创建新数据中心后，请运行以下命令 datacenter show 以查看其详细信息：

resourceGroupName='MyResourceGroup'
clusterName='cassandra-hybrid-cluster'
dataCenterName='dc1'

az managed-cassandra datacenter show \
  --resource-group $resourceGroupName \
  --cluster-name $clusterName \
  --data-center-name $dataCenterName

上一个命令显示新数据中心的种子节点。

将新数据中心的种子节点添加到 cassandra.yaml 文件中现有数据中心的种子节点配置。将之前收集的托管实例 gossip 证书安装到现有群集中每个节点的信任存储中。使用keytool命令对每个证书。
```
keytool -importcert -keystore generic-server-truststore.jks -alias CassandraMI -file cert1.pem -noprompt -keypass myPass -storepass truststorePass
```
如果要添加更多数据中心，请重复上述步骤，但只需要种子节点。

重要说明

如果现有的 Apache Cassandra 群集只有一个数据中心，并且该数据中心是第一个添加的数据中心，请确保将 cassandra.yaml 参数设置为 GossipingPropertyFileSnitch。

如果您的现有应用程序代码使用QUORUM来保持一致性，请确保在下一步更改复制设置之前，您的现有应用程序代码使用LOCAL_QUORUM连接到现有群集。否则，在以下步骤中更改复制设置后，实时更新将失败。更改复制策略后，可以根据需要还原为 QUORUM 。

最后，使用以下 Cassandra 查询语言查询更新每个密钥空间中的复制策略，以包括群集中的所有数据中心：

ALTER KEYSPACE "ks" WITH REPLICATION = {'class': 'NetworkTopologyStrategy', 'on-premise-dc': 3, 'managed-instance-dc': 3};

还需要更新几个系统表：

ALTER KEYSPACE "system_auth" WITH REPLICATION = {'class': 'NetworkTopologyStrategy', 'on-premise-dc': 3, 'managed-instance-dc': 3}
ALTER KEYSPACE "system_distributed" WITH REPLICATION = {'class': 'NetworkTopologyStrategy', 'on-premise-dc': 3, 'managed-instance-dc': 3}
ALTER KEYSPACE "system_traces" WITH REPLICATION = {'class': 'NetworkTopologyStrategy', 'on-premise-dc': 3, 'managed-instance-dc': 3}

如果现有群集中的数据中心未强制实施客户端到节点加密（SSL），并且你打算让应用程序代码直接连接到 Azure 托管实例 for Apache Cassandra，则还需要在应用程序代码中启用 TLS/SSL。

使用混合群集进行实时迁移

上述说明提供有关如何配置混合群集的指导。此方法也是实现无缝零停机迁移的好方法。以下过程显示了如何在零故障时间的情况下，将你想要停用的本地或其他 Cassandra 环境迁移到 Azure Managed Instance for Apache Cassandra。

配置混合群集。按照前面的说明进行。

在迁移期间暂时禁用 Azure 适用于 Apache Cassandra 的托管实例中的自动修复。

az managed-cassandra cluster update \
  --resource-group $resourceGroupName \
  --cluster-name $clusterName --repair-enabled false

在 Azure CLI 中，使用以下命令在新 Azure 托管实例 for Apache Cassandra 数据中心的每个节点上运行 nodetool rebuild 。将 <ip address> 替换为节点的 IP 地址。将 <sourcedc> 替换为你现有的、要从中进行迁移的数据中心的名称：
```
az managed-cassandra cluster invoke-command \
  --resource-group $resourceGroupName \
  --cluster-name $clusterName \
  --host <ip address> \
  --command-name nodetool --arguments rebuild="" "<sourcedc>"=""
```
仅在执行所有上述步骤后运行此命令。此方法应确保所有历史数据都复制到 Azure Managed Instance for Apache Cassandra 中的新数据中心。可以同时在一个或多个节点上运行 rebuild 。一次在一个节点上运行，以减少对现有群集的影响。当群集可以处理额外的 I/O 和网络压力时，在多个节点上运行。对于大多数安装，只能并行运行一两个，这样就不会重载群集。
警告

运行nodetool rebuild时必须指定源data center。如果在首次尝试时未正确提供数据中心，则会为非系统表复制令牌范围，而不是复制数据。即使正确提供数据中心，后续尝试也会失败。若要解决此问题，请使用目标 Azure Managed Instance for Apache Cassandra 数据中心中的 cqlsh 查询工具删除 system.available_ranges 中每个非系统密钥空间的条目：
```
delete from system.available_ranges where keyspace_name = 'myKeyspace';
```
直接转换应用程序代码，以便指向 Azure Managed Instance for Apache Cassandra 数据中心中的种子节点。

如混合安装说明中所述，如果现有群集中的数据中心未强制实施客户端到节点加密（SSL），请在应用程序代码中启用此功能。适用于 Apache Cassandra 的 Azure 托管实例强制实施此要求。
针对每个密钥空间运行 ALTER KEYSPACE ，方式与之前完成的方式相同。现在，可以删除旧数据中心。
为每个旧数据中心节点运行节点工具停用。
如有必要或首选，请将应用程序代码切换回 QUORUM。

重新启用自动修复：

az managed-cassandra cluster update \
  --resource-group $resourceGroupName \
  --cluster-name $clusterName --repair-enabled true

疑难解答

如果使用 Azure CLI 将权限应用到虚拟网络时遇到错误，可以从 Azure 门户手动应用相同的权限。此类错误的一个示例是“在图形数据库中找不到用户或服务主体e5007d2c-4b13-4a74-9b6a-605d99f03501。”有关详细信息，请参阅使用 Azure 门户添加 Azure Cosmos DB 服务主体。

Azure Cosmos DB 角色分配仅用于部署目的。适用于 Apache Cassandra 的 Azure 托管实例在 Azure Cosmos DB 上没有后端依赖项。

清理资源

如果不打算继续使用此托管实例群集，请执行以下步骤将其删除：

在 Azure 门户的左侧菜单上选择“资源组” 。
从列表中选择为本快速入门创建的资源组。
在资源组的“概述”窗格上，选择“删除资源组”。
在下一个窗格中，输入要删除的资源组的名称，然后选择“ 删除”。

后续步骤

使用 Azure CLI 管理 Azure Managed Instance for Apache Cassandra 资源

反馈

此页面是否有帮助？