快速入門：使用 Azure Managed Instance for Apache Cassandra 設定混合式叢集

發行項
08/15/2024

Azure Managed Instance for Apache Cassandra 是純開放原始碼 Apache Cassandra 叢集的完全受控服務。此服務也允許根據每個工作負載的特定需求來覆寫組態，而能視需要提供最大彈性和控制。

本快速入門示範如何使用 Azure CLI 命令來設定混合式叢集。如果您在內部部署或自我裝載環境中有現有的資料中心，您可以使用 Azure Managed Instance for Apache Cassandra，將其他資料中心新增至該叢集並加以維護。

必要條件

在 Azure Cloud Shell 中使用 Bash 環境。如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。請遵循您終端機上顯示的步驟，完成驗證程序。如需其他登入選項，請參閱使用 Azure CLI 登入。
- 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。
- 執行 az version 以尋找已安裝的版本和相依程式庫。若要升級至最新版本，請執行 az upgrade。

此文章需要 Azure CLI 2.30.0 版或更新版本。若您使用的是 Azure Cloud Shell，即已安裝最新版本。
可連線到自我裝載或內部部署環境的 Azure 虛擬網路。如需將內部部署環境連線至 Azure 的詳細資訊，請參閱將內部部署網路連線到 Azure 一文 (部分機器翻譯)。

設定混合式叢集

登入 Azure 入口網站，並瀏覽至您的虛擬網路資源。
開啟 [子網路] 索引標籤並建立新的子網路。若要深入了解新增子網路表單中欄位的詳細資訊，請參閱虛擬網絡一文：
注意

部署 Azure Managed Instance for Apache Cassandra 需要網際網路存取。在網際網路存取受到限制的環境中，部署失敗。請確定您不會封鎖 VNet 內對下列重要 Azure 服務進行存取，這些是受控 Cassandra 正常運作所需的重要 Azure 服務。您也可以在這裡找到廣泛的 IP 位址和連接埠相依性清單。
- Azure 儲存體
- Azure KeyVault
- Azure 虛擬機器擴展集
- Azure 監視
- Microsoft Entra ID
- Azure 安全性
現在，我們將使用 Azure CLI，將一些特殊權限套用至 Cassandra 受控執行個體所需的 VNet 和子網路。使用 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-----。一般而言，實作憑證的方式有兩種：
1. 自我簽署憑證。這表示每個節點的私密和公開 (無 CA) 憑證：在此情況下，我們需要所有公開憑證。
2. 由 CA 簽署的憑證。這可以是自我簽署 CA，甚至是公開 CA。在此情況下，我們需要根 CA 憑證 (請參閱準備生產環境 SSL 憑證的指示)，以及所有媒介 (如果適用的話)。
或者，若要實作用戶端對節點憑證驗證或相互傳輸層安全性 (mTLS)，則必須以與建立混合式叢集時相同的格式提供憑證。請參閱下面的 Azure CLI 範例：憑證是在 --client-certificates 參數中提供。這會將用戶端憑證上傳並套用至 Cassandra 受控執行個體叢集的信任存放區 (亦即您不需要編輯 cassandra.yaml 設定)。套用之後，您的叢集將會要求 Cassandra 在用戶端連線時驗證憑證 (請參閱 Cassandra client_encryption_options 中的 require_client_auth: true)。

注意

您將會在下面提供 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 is not 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 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 指令碼 (您需要下載並安裝適用於您平台的 jq) 來格式化憑證，並為每個憑證建立個別的 pem 檔案。
```
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 的值可以從下列可用的 SKU 中選擇：
- Standard_E8s_v4
- Standard_E16s_v4
- Standard_E20s_v4
- Standard_E32s_v4
- 標準 DS13_v2
- 標準 DS14_v2
- Standard_D8s_v4
- Standard_D16s_v4
- Standard_D32s_v4
也請注意，--availability-zone 設為 false。若要啟用可用性區域，請將此設定為 true。可用性區域會增加服務的可用性 SLA。如需詳細資訊，請檢閱這裡的完整 SLA 詳細資料。
警告

並非所有區域都支援可用性區域。如果您選取不支援可用性區域的區域，部署將會失敗。如需支援的區域，請參閱這裡。可用性區域是否能成功部署也受限於指定區域中所有區域的計算資源可用性。如果您選取的 SKU 或容量無法在所有區域使用，部署可能會失敗。

現在已建立新的資料中心，請執行 show datacenter 命令來檢視其詳細資料：

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 中的 endpoint_snitch 參數已設定為 GossipingPropertyFileSnitch。

重要

如果現有應用程式程式碼使用 QUORUM 進行一致性，您應該先確定在下列步驟中變更複寫設定之前，現有的應用程式程式碼會使用 LOCAL_QUORUM 連線到現有的叢集 (否則您在下列步驟中變更複寫設定之後，即時更新將會失敗)。複寫策略變更後，您可以視需要還原為 QUORUM。

最後，使用下列 CQL 查詢來更新每個 keyspace 中的複寫策略，以包含叢集內所有的資料中心：

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)，而且您想要讓應用程式程式碼直接連線到 Cassandra 受控執行個體，您也必須在應用程式程式碼中啟用 SSL。

使用混合式叢集進行即時移轉

上述指示提供設定混合式叢集的指引。不過，這也是達成無縫零停機移轉的絕佳方式。如果您有想要以零停機時間解除委任的內部部署或其他 Cassandra 環境，以利於在 Azure Managed Instance for Apache Cassandra 中執行工作負載，則必須依此順序完成下列步驟：

設定混合式叢集：請遵循上述指示。

在移轉期間，暫時停用 Azure Managed Instance for Apache Cassandra 中的自動修復：

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

在 Azure CLI 中，執行下列命令，在新的 Azure Managed Instance for Apache Cassandra 資料中心的每個節點上執行 nodetool rebuild，並以節點的 IP 位址取代 <ip address>，以您現有的資料中心名稱 (您要移轉的來源) 取代 <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 中的新資料中心。您可以同時在一或多個節點上執行重建。一次在一個節點上執行，以減少對現有叢集的影響。請在叢集可以處理額外的 I/O 和網路壓力時，才在多個節點上執行。對於大部分安裝，您只能平行執行一或兩個，以免叢集超載。
警告

執行 nodetool rebuild 時，您必須指定來源資料中心。如果您在第一次嘗試時提供的資料中心不正確，這會導致複製權杖範圍，而不會為非系統資料表複製資料。即使後續您提供正確的資料中心，後續嘗試也會失敗。您可以透過目標 Cassandra MI 資料中心的 cqlsh 查詢工具，刪除 system.available_ranges 中每個非系統 keyspace 的項目來解決此問題：
```
delete from system.available_ranges where keyspace_name = 'myKeyspace';
```
完全移轉您的應用程式程式碼，以指向新 Azure Managed Instance for Apache Cassandra 資料中心的種子節點。

重要

如混合式設定指示中所述，如果現有叢集中的資料中心未強制執行用戶端對節點加密 (SSL)，您必須在應用程式程式碼中啟用此功能，因為 Cassandra 受控執行個體會強制執行此動作。
對每個 keyspace 執行 ALTER KEYSPACE，方式與先前相同，但現在移除舊的資料中心。
對每個舊資料中心節點執行 nodetool 解除委任。
將應用程式程式碼切換回仲裁 (如有需要/偏好)。

重新啟用自動修復：

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

疑難排解

若使用 Azure CLI 將權限套用至虛擬網路時發生錯誤 (例如「在圖形資料庫中找不到 'e5007d2c-4b13-4a74-9b6a-605d99f03501' 的使用者或服務主體」)，則可從 Azure 入口網站手動套用相同的權限。若要了解如何操作，請參閱這裡。

注意

Azure Cosmos DB 角色指派僅供部署之用。 Azure Managed Instanced for Apache Cassandra 沒有與 Azure Cosmos DB 的後端相依性。

清除資源

如果您不打算繼續使用這個受控執行個體叢集，請使用下列步驟將其刪除：

從 Azure 入口網站的左側功能表中，選取 [資源群組]。
在該清單中，選取您在本快速入門中建立的資源群組。
在資源群組 [概觀] 窗格中，選取 [刪除資源群組]。
在下個視窗中輸入要刪除的資源群組名稱，然後選取 [刪除]。

下一步

在本快速入門中，您已瞭解如何使用 Azure CLI 和 Azure Managed Instance for Apache Cassandra 來建立混合式叢集。您現在可以開始使用叢集。

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

共用方式為