使用 Azure CLI 建立和佈建叢集

發行項
12/18/2024

本文說明如何使用 Azure 命令列介面 (AzCLI) 來建立叢集。本文也會示範如何檢查狀態、更新或刪除叢集。

必要條件

確認您的 Azure 區域中有網路網狀架構控制器和叢集管理員
確認網路網狀架構已成功佈建

API 指南和計量

API 指南提供資源提供者和資源模型以及 API 的相關資訊。

從記錄資料產生的計量可在 Azure 監視器計量取得。

限制

命名 - 可以在此處找到命名規則。

建立叢集

基礎結構叢集資源代表叢集管理員內平台的內部部署。所有其他平台特定資源都相依於其生命週期。

您應該在此內部部署之前建立網路網狀架構。每個運算子連接點內部部署執行個體都有與網路網狀架構的一對一關聯。

使用 Azure CLI 建立叢集：

az networkcloud cluster create --name "$CLUSTER_NAME" --location "$LOCATION" \
  --extended-location name="$CL_NAME" type="CustomLocation" \
  --resource-group "$CLUSTER_RG" \
  --analytics-workspace-id "$LAW_ID" \
  --cluster-location "$CLUSTER_LOCATION" \
  --network-rack-id "$AGGR_RACK_RESOURCE_ID" \
  --rack-sku-id "$AGGR_RACK_SKU"\
  --rack-serial-number "$AGGR_RACK_SN" \
  --rack-location "$AGGR_RACK_LOCATION" \
  --bare-metal-machine-configuration-data "["$AGGR_RACK_BMM"]" \
  --storage-appliance-configuration-data '[{"adminCredentials":{"password":"$SA_PASS","username":"$SA_USER"},"rackSlot":1,"serialNumber":"$SA_SN","storageApplianceName":"$SA_NAME"}]' \
  --compute-rack-definitions '[{"networkRackId": "$COMPX_RACK_RESOURCE_ID", "rackSkuId": "$COMPX_RACK_SKU", "rackSerialNumber": "$COMPX_RACK_SN", "rackLocation": "$COMPX_RACK_LOCATION", "storageApplianceConfigurationData": [], "bareMetalMachineConfigurationData":[{"bmcCredentials": {"password":"$COMPX_SVRY_BMC_PASS", "username":"$COMPX_SVRY_BMC_USER"}, "bmcMacAddress":"$COMPX_SVRY_BMC_MAC", "bootMacAddress":"$COMPX_SVRY_BOOT_MAC", "machineDetails":"$COMPX_SVRY_SERVER_DETAILS", "machineName":"$COMPX_SVRY_SERVER_NAME"}]}]'\
  --managed-resource-group-configuration name="$MRG_NAME" location="$MRG_LOCATION" \
  --network fabric-id "$NF_ID" \
  --cluster-service-principal application-id="$SP_APP_ID" \
    password="$SP_PASS" principal-id="$SP_ID" tenant-id="$TENANT_ID" \
  --subscription "$SUBSCRIPTION_ID" \
  --secret-archive "{key-vault-id:$KVRESOURCE_ID, use-key-vault:true}" \
  --cluster-type "$CLUSTER_TYPE" --cluster-version "$CLUSTER_VERSION" \
  --tags $TAG_KEY1="$TAG_VALUE1" $TAG_KEY2="$TAG_VALUE2"

叢集作業的參數

參數名稱	描述
CLUSTER_NAME	叢集的資源名稱
LOCATION	部署叢集的 Azure 區域
CL_NAME	來自 Azure 入口網站的叢集管理員自訂位置
CLUSTER_RG	叢集資源群組名稱
LAW_ID	叢集的 Log Analytics 工作區識別碼
CLUSTER_LOCATION	叢集的本機名稱
AGGR_RACK_RESOURCE_ID	彙總工具機架的 RackID
AGGR_RACK_SKU	匯總工具機架的機架 SKU *請參閱操作員 Nexus 網路雲端 SKU
AGGR_RACK_SN	彙總工具機架的機架序號
AGGR_RACK_LOCATION	彙總工具機架的機架實體位置
AGGR_RACK_BMM	僅用於單一機架部署，針對多機架為空白
SA_NAME	儲存體設備裝置名稱
SA_PASS	儲存體設備管理員密碼
SA_USER	儲存體設備管理使用者
SA_SN	儲存體設備序號
COMPX_RACK_RESOURCE_ID	適用於 CompX Rack 的 RackID；針對 compute-rack-definitions 中的每個機架重複
COMPX_RACK_SKU	CompX Rack 的機架 SKU;針對電腦架定義中的每個機架重複執行 *請參閱操作員 Nexus 網路雲端 SKU
COMPX_RACK_SN	適用於 CompX Rack 的機架序號；針對 compute-rack-definitions 中的每個機架重複
COMPX_RACK_LOCATION	適用於 CompX Rack 的機架實體位置；針對 compute-rack-definitions 中的每個機架重複
COMPX_SVRY_BMC_PASS	CompX Rack ServerY 基礎板管理控制器（BMC）密碼;針對電腦架定義中的每個機架重複，並針對機架中的每個伺服器重複
COMPX_SVRY_BMC_USER	CompX Rack ServerY BMC 使用者;針對電腦架定義中的每個機架重複，並針對機架中的每個伺服器重複
COMPX_SVRY_BMC_MAC	CompX Rack ServerY BMC MAC 位址;針對電腦架定義中的每個機架重複，並針對機架中的每個伺服器重複
COMPX_SVRY_BOOT_MAC	CompX Rack ServerY 開機網路適配器（NIC） MAC 位址;針對電腦架定義中的每個機架重複，並針對機架中的每個伺服器重複
COMPX_SVRY_SERVER_DETAILS	CompX Rack ServerY 詳細數據;針對電腦架定義中的每個機架重複，並針對機架中的每個伺服器重複
COMPX_SVRY_SERVER_NAME	CompX Rack ServerY 名稱;針對電腦架定義中的每個機架重複，並針對機架中的每個伺服器重複
MRG_NAME	叢集受控資源群組名稱
MRG_LOCATION	叢集 Azure 區域
NF_ID	網路網狀架構的參考
SP_APP_ID	服務主體應用程式識別碼
SP_PASS	服務主體密碼
SP_ID	服務主體識別碼
TENANT_ID	訂用帳戶租用戶識別碼
SUBSCRIPTION_ID	訂用帳戶識別碼
KV_RESOURCE_ID	Key Vault 識別碼
CLUSTER_TYPE	叢集類型，單一或 MultiRack
CLUSTER_VERSION	網路雲端（NC）叢集版本
TAG_KEY1	要傳遞至叢集建立的選擇性 tag1
TAG_VALUE1	要傳遞至叢集建立的選擇性 tag1 值
TAG_KEY2	要傳遞至叢集建立的選擇性 tag2
TAG_VALUE2	要傳遞至叢集建立的選擇性 tag2 值

叢集身分識別

從 2024-07-01 API 版本開始，客戶可以將受控識別指派給叢集。支援系統指派和使用者指派的受控識別。

在建立或更新作業期間，您可以藉由提供下列參數，將受控識別指派給叢集：

--mi-system-assigned - 啟用系統指派的受控識別。新增之後，您目前只能透過 API 呼叫移除身分識別。
--mi-user-assigned - 要新增之使用者指派受控識別的空間分隔資源標識符。新增之後，您目前只能透過 API 呼叫移除身分識別。

使用 Azure Resource Manager 範本編輯器建立叢集

建立叢集的另一種方法是使用 ARM 範本編輯器。

若要以這種方式建立叢集，需要提供範本檔案 (cluster.jsonc) 和參數檔案 (cluster.parameters.jsonc)。您可以使用這兩個檔案，找到 8 機架 2M16C SKU 叢集的範例：

cluster.jsonc、cluster.parameters.jsonc

注意

若要取得正確的格式，請複製原始程式碼檔案。 cluster.parameters.jsonc 檔案中的值是客戶特定的值，可能不是完整清單。請更新特定環境的值欄位。

流覽至網頁瀏覽器中 Azure 入口網站並登入。
在 Azure 入口網站搜尋列中搜尋[部署自定義範本]，然後從可用的服務中選取它。
在編輯器中按一下 [建置自己的範本]。
按一下 [載入檔案]。找到 cluster.jsonc 範本檔案並加以上傳。
按一下 [檔案] 。
按一下 [編輯參數]。
按一下 [載入檔案]。找到 cluster.parameters.jsonc 參數檔案並加以上傳。
按一下 [檔案] 。
選取正確的訂用帳戶。
搜尋資源群組，以查看資源群組是否已存在。如果不存在，請建立新的資源群組。
請確定所有執行個體詳細資料都正確無誤。
按一下 [檢閱 + 建立] 。

叢集驗證

成功的操作員 Nexus 叢集建立會導致在訂用帳戶內建立 Azure 資源。叢集識別碼、叢集佈建狀態和部署狀態會因為 cluster create 成功而傳回。

檢視叢集的狀態：

az networkcloud cluster show --cluster-name "<clusterName>" /
--resource-group "<resourceGroupName>" /
--subscription <subscriptionID>

當資源的 provisioningState 顯示為下列項目時，叢集建立即完成："provisioningState": "Succeeded"

叢集記錄檔

叢集建立記錄可以在下列位置檢視：

Azure 入口網站資源/ResourceGroup 活動記錄。
在命令列上傳遞 --debug 旗標的 Azure CLI。

設定部署閾值

在叢集部署之前，可以在叢集上設定兩種類型的部署閾值。其中包括 compute-deployment-threshold 和 update-strategy。

--compute-deployment-threshold - 驗證閾值，指出環境硬體驗證期間計算節點的允許失敗。

如果未 compute-deployment-threshold 設定，預設值如下：

      "strategyType": "Rack",
      "thresholdType": "PercentSuccess",
      "thresholdValue": 80,
      "waitTimeMinutes": 1

如果客戶要求 compute-deployment-threshold 它不同於預設值 80%，您可以執行下列叢集更新命令。

下列範例適用於要求類型為「PercentSuccess」且成功率為 97% 的客戶。

az networkcloud cluster update --name "<clusterName>" /
--resource-group "<resourceGroup>" /
--compute-deployment-threshold type="PercentSuccess" grouping="PerCluster" value=97 /
--subscription <subscriptionID>

驗證更新

az networkcloud cluster show --resource-group "<resourceGroup>" --name "<clusterName>" | grep -a3 computeDeploymentThreshold

  "clusterType": "MultiRack",
  "clusterVersion": "<CLUSER_VERSION>",
  "computeDeploymentThreshold": {
    "grouping": "PerCluster",
    "type": "PercentSuccess",
    "value": 97

在此範例中，如果部署的計算節點少於97%通過硬體驗證，叢集部署將會失敗。 注意：所有 kubernetes 控制平面（KCP）和 nexus 管理平面（NMP）都必須通過硬體驗證。 如果正在部署的 97% 以上的計算節點通過硬體驗證，叢集部署將會繼續執行啟動程式佈建階段。在計算啟動程式佈建期間， update-strategy 會針對計算節點使用（以下）。

--update-strategy - 更新叢集的策略，指出啟動程式布建期間允許的計算節點失敗。

如果客戶要求閾值 update-strategy 與預設值 80% 不同，您可以執行下列叢集更新命令。

az networkcloud cluster update --name "<clusterName>" /
--resource-group "<resourceGroup>" /
--update-strategy strategy-type="Rack" threshold-type="PercentSuccess" /
threshold-value="<thresholdValue>" wait-time-minutes=<waitTimeBetweenRacks> /
--subscription <subscriptionID>

策略類型可以是 “Rack” （Rack by Rack）或 “PauseAfterRack” （等候客戶回應繼續）。

臨界值類型可以是「PercentSuccess」或「CountSuccess」。。

如果未設定 updateStrategy，預設值如下：

      "strategyType": "Rack",
      "thresholdType": "PercentSuccess",
      "thresholdValue": 80,
      "waitTimeMinutes": 1

下列範例適用於使用Rack by Rack 策略的客戶，其成功百分比為60%且暫停1分鐘。

az networkcloud cluster update --name "<clusterName>" /
--resource-group "<resourceGroup>" /
--update-strategy strategy-type="Rack" threshold-type="PercentSuccess" /
threshold-value=60 wait-time-minutes=1 /
--subscription <subscriptionID>

確認更新：

az networkcloud cluster show --resource-group "<resourceGroup>" /
--name "<clusterName>" /
--subscription <subscriptionID>| grep -a5 updateStrategy

      "strategyType": "Rack",
      "thresholdType": "PercentSuccess",
      "thresholdValue": 60,
      "waitTimeMinutes": 1

在此範例中，如果在機架中布建的計算節點少於 60% 無法布建（以機架為基礎），叢集部署將會失敗。如果已成功布建 60% 以上的計算節點，叢集部署就會移至下一個計算節點機架。

下列範例適用於使用Rack by Rack策略的客戶，其閾值類型為每個機架 10 個節點的 CountSuccess，且暫停 1 分鐘。

az networkcloud cluster update --name "<clusterName>" /
--resource-group "<resourceGroup>" /
--update-strategy strategy-type="Rack" threshold-type="CountSuccess" /
threshold-value=10 wait-time-minutes=1 /
--subscription <subscriptionID>

確認更新：

az networkcloud cluster show --resource-group "<resourceGroup>" /
--name "<clusterName>" /
--subscription <subscriptionID>| grep -a5 updateStrategy

      "strategyType": "Rack",
      "thresholdType": "CountSuccess",
      "thresholdValue": 10,
      "waitTimeMinutes": 1

在此範例中，如果在機架中布建的計算節點少於10個無法布建（以機架為基礎），叢集部署將會失敗。如果已成功布建 10 個以上的計算節點，叢集部署就會移至下一個計算節點機架。

注意

叢集部署啟動之後，就無法變更部署閾值。

部署叢集

建立叢集之後，可以觸發部署叢集動作。部署叢集動作會建立啟動程序映像並部署叢集。

部署叢集會起始一系列會在叢集管理員中發生的事件。

驗證叢集/機架屬性。
產生暫時性啟動程序叢集的可開機映像 (基礎結構驗證)。
與目標啟動程序機器的 Intelligent Platform Management Interface （IPMI）介面互動。
執行硬體驗證檢查。
監視叢集部署程序。

部署內部部署叢集：

az networkcloud cluster deploy \
  --name "$CLUSTER_NAME" \
  --resource-group "$CLUSTER_RG" \
  --subscription "$SUBSCRIPTION_ID" \
  --no-wait --debug

提示

若要檢查 az networkcloud cluster deploy 命令的狀態，可以使用 --debug 旗標來執行。這可讓您取得用來查詢 operationStatuses 資源的 Azure-AsyncOperation 或 Location 標頭。如需詳細步驟，請參閱叢集部署失敗一節。或者，命令可以使用 --no-wait 旗標以非同步方式執行。

使用硬體驗證進行叢集部署

在叢集部署程序期間，執行的其中一個步驟是硬體驗證。硬體驗證程序會針對透過叢集機架定義所提供的電腦執行各種測試和檢查。根據這些檢查的結果和任何使用者略過的電腦，判斷是否有足夠的節點通過和/或可用，以符合部署所需的閾值以便繼續作業。

重要

硬體驗證程序會將結果寫入叢集建立時指定的 analyticsWorkspaceId。此外，叢集物件中提供的服務主體會用於針對 Log Analytics 工作區資料收集 API 進行驗證。這項功能只有在新的部署期間才會顯示 (綠色欄位)；現有的叢集不會有可追溯的記錄。

注意

RAID 控制器會在叢集部署期間重設，以抹除伺服器虛擬磁碟的所有資料。除非有額外的實體磁碟和/或 RAID 控制器警示，否則通常可以忽略任何基礎板管理控制器（BMC）虛擬磁碟警示。

根據預設，硬體驗證程序會將結果寫入已設定的叢集 analyticsWorkspaceId。不過，由於 Log Analytics 工作區資料收集和結構描述評估的性質，可能會有幾分鐘或更多時間的擷取延遲。因此，即使無法將結果寫入 Log Analytics 工作區，叢集部署仍會繼續。為了協助解決這個可能的事件，結果也會記錄在叢集管理員內作為備援。

在提供的叢集物件的 Log Analytics 工作區中，應該會出現具有叢集名稱作為前置詞和後置詞的新自訂資料表 *_CL。在 LAW 資源的 [記錄] 區段中，您可以針對新的 *_CL 自訂記錄資料表執行查詢。

使用略過特定裸機機器的叢集部署

參數 --skip-validation-for-machines 代表叢集中的裸機計算機名稱，應在硬體驗證期間略過。略過的節點不會進行驗證，也不會新增至節點集區。此外，略過的節點不會計入閾值計算所使用的總計。

az networkcloud cluster deploy \
  --name "$CLUSTER_NAME" \
  --resource-group "$CLUSTER_RG" \
  --subscription "$SUBSCRIPTION_ID" \
  --skip-validations-for-machines "$COMPX_SVRY_SERVER_NAME"

失敗的叢集部署

若要追蹤非同步作業的狀態，請使用已啟用 --debug 旗標執行。指定 --debug 時，可以監視要求的進度。檢查偵錯輸出以尋找建立要求的 HTTP 回應上的 Azure-AsyncOperation 或 Location 標頭，即可找到作業狀態 URL。標頭可以提供 HTTP API 呼叫中使用的 OPERATION_ID 欄位。

OPERATION_ID="aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e*99399E995..."
az rest -m GET -u "https://management.azure.com/subscriptions/${SUBSCRIPTION_ID}/providers/Microsoft.NetworkCloud/locations/${LOCATION}/operationStatuses/${OPERATION_ID}?api-version=2022-12-12-preview"

輸出類似 JSON 結構範例。當錯誤碼為 HardwareValidationThresholdFailed 時，錯誤訊息會包含硬體驗證失敗的裸機電腦清單 (例如，COMP0_SVR0_SERVER_NAME、COMP1_SVR1_SERVER_NAME)。這些名稱可用來剖析記錄以取得進一步的詳細資料。

{
  "endTime": "2023-03-24T14:56:59.0510455Z",
  "error": {
    "code": "HardwareValidationThresholdFailed",
    "message": "HardwareValidationThresholdFailed error hardware validation threshold for cluster layout plan is not met for cluster $CLUSTER_NAME in namespace nc-system with listed failed devices $COMP0_SVR0_SERVER_NAME, $COMP1_SVR1_SERVER_NAME"
  },
  "id": "/subscriptions/$SUBSCRIPTION_ID/providers/Microsoft.NetworkCloud/locations/$LOCATION/operationStatuses/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e*99399E995...",
  "name": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e*99399E995...",
  "resourceId": "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$CLUSTER_RESOURCE_GROUP/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME",
  "startTime": "2023-03-24T14:56:26.6442125Z",
  "status": "Failed"
}

如需其他範例，請參閱使用 Azure CLI 追蹤非同步作業一文。如需特定計算機驗證或部署失敗時可能有幫助的詳細資訊，請參閱針對 BMM 布建進行疑難解答一文。

叢集部署驗證

在入口網站上或透過 Azure CLI 檢視叢集的狀態：

az networkcloud cluster show --resource-group "$CLUSTER_RG" \
  --name "$CLUSTER_NAME"

當 detailedStatus 設定為 Deploying 時，表示叢集部署正在進行中，而且 detailedStatusMessage 會顯示部署的進度。詳細StatusMessage Hardware validation is in progress. 中顯示的一些部署進度範例為（如果叢集是以硬體驗證部署）、 Cluster is bootstrapping.、 KCP initialization in progress.、 Management plane deployment in progress.、 Cluster extension deployment in progress.、 waiting for "<rack-ids>" to be ready等。

當 detailedStatus 設定為 Running 且 detailedStatusMessage 顯示訊息 Cluster is up and running 時，叢集部署就會完成。

檢視叢集的管理版本：

az k8s-extension list --cluster-name "$CLUSTER_NAME" --resource-group "$MRG_NAME" --cluster-type connectedClusters --query "[?name=='nc-platform-extension'].{name:name, extensionType:extensionType, releaseNamespace:scope.cluster.releaseNamespace,provisioningState:provisioningState,version:version}" -o table --subscription "$SUBSCRIPTION_ID"

叢集部署記錄

叢集建立記錄可以在下列位置檢視：

Azure 入口網站資源/ResourceGroup 活動記錄。
在命令列上傳遞 --debug 旗標的 Azure CLI。

透過 API 更新叢集身分識別

叢集受控識別可透過 CLI 指派。您可以透過 API 呼叫來取消指派身分識別。請注意， <APIVersion> 是 API 版本 2024-07-01 或更新版本。

若要移除所有受控識別，請執行：

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body "{\"identity\":{\"type\":\"None\"}}"

如果已新增使用者指派和系統指派的受控識別，則可以藉由將更新 type 為 SystemAssigned來移除使用者指派：

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body @~/uai-body.json

要求本文（uai-body.json）範例：

{
  "identity": {
      "type": "SystemAssigned"
  }
}

如果已新增使用者指派和系統指派的受控識別，則可以藉由將更新 type 為 UserAssigned來移除系統指派：

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body @~/uai-body.json

要求本文（uai-body.json）範例：

{
  "identity": {
      "type": "UserAssigned",
  	"userAssignedIdentities": {
  		"/subscriptions/$SUB_ID/resourceGroups/$UAI_RESOURCE_GROUP/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$UAI_NAME": {}
  	}
  }
}

如果已新增多個使用者指派的受控識別，則可以執行下列其中一項來移除：

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body @~/uai-body.json

要求本文（uai-body.json）範例：

{
  "identity": {
      "type": "UserAssigned",
  	"userAssignedIdentities": {
  		"/subscriptions/$SUB_ID/resourceGroups/$UAI_RESOURCE_GROUP/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$UAI_NAME": null
  	}
  }
}

刪除叢集

刪除叢集會刪除 Azure 中的資源，以及位於內部部署環境中的叢集。

注意

如果叢集中存在任何租用戶資源，則要等到刪除這些資源後，才會刪除叢集。

az networkcloud cluster delete --name "$CLUSTER_NAME" --resource-group "$CLUSTER_RG"

共用方式為

使用 Azure CLI 建立和佈建叢集

必要條件

API 指南和計量

限制

建立叢集

使用 Azure CLI 建立叢集：

叢集作業的參數

叢集身分識別

使用 Azure Resource Manager 範本編輯器建立叢集

叢集驗證

叢集記錄檔

設定部署閾值

驗證更新

部署叢集

使用硬體驗證進行叢集部署

使用略過特定裸機機器的叢集部署

失敗的叢集部署

叢集部署驗證

叢集部署記錄

透過 API 更新叢集身分識別

刪除叢集

意見反應

其他資源