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

使用 Azure CLI 创建和预配群集

项目
12/19/2024

本文介绍如何使用 Azure 命令行接口 (AzCLI) 创建群集。本文档还演示如何检查状态、更新或删除群集。

先决条件

验证 Azure 区域中是否存在网络结构控制器和群集管理器
验证是否已成功预配网络结构

API 指南和指标

API 指南提供有关资源提供程序、资源模型和 API 的信息。

从日志记录数据生成的指标在 Azure Monitor 指标中可用。

限制

命名 - 可在此处找到命名规则。

创建群集

基础结构群集资源表示群集管理器中平台的本地部署。其他所有特定于平台的资源在其生命周期内都依赖于它。

应在此本地部署之前创建网络结构。每个运营商关系本地实例都与网络结构一对一关联。

使用 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 工作区 ID
CLUSTER_LOCATION	群集的本地名称
AGGR_RACK_RESOURCE_ID	聚合器机架的 RackID
AGGR_RACK_SKU	聚合器机架的机架 SKU *请参阅 Operator Nexus 网络云 SKU
AGGR_RACK_SN	聚合器机架的机架序列号
AGGR_RACK_LOCATION	聚合器机架的机架物理位置
AGGR_RACK_BMM	仅用于单机架部署，多机架部署为空
SA_NAME	存储设备的设备名称
SA_PASS	存储设备管理员密码
SA_USER	存储设备管理员用户
SA_SN	存储设备序列号
COMPX_RACK_RESOURCE_ID	CompX 机架的 RackID；在 compute-rack-definitions 中对每个机架重复
COMPX_RACK_SKU	CompX 机架的机架 SKU；在 compute-rack-definitions 中对每个机架重复*请参阅 Operator Nexus 网络云 SKU
COMPX_RACK_SN	CompX 机架的机架序列号；在 compute-rack-definitions 中对每个机架重复
COMPX_RACK_LOCATION	CompX 机架的机架物理位置；在 compute-rack-definitions 中对每个机架重复
COMPX_SVRY_BMC_PASS	CompX Rack ServerY 基板管理控制器 (BMC) 密码；对 compute-rack-definitions 中的每个机架和机架中的每个服务器重复
COMPX_SVRY_BMC_USER	CompX Rack ServerY BMC 用户，对 compute-rack-definitions 中的每个机架和机架中的每个服务器重复
COMPX_SVRY_BMC_MAC	CompX Rack ServerY BMC MAC 地址，对 compute-rack-definitions 中的每个机架和机架中的每个服务器重复
COMPX_SVRY_BOOT_MAC	CompX Rack ServerY boot 网络适配卡 (NIC) MAC 地址；对 compute-rack-definitions 中的每个机架和机架中的每个服务器重复
COMPX_SVRY_SERVER_DETAILS	CompX Rack ServerY 详细信息，对 compute-rack-definitions 中的每个机架和机架中的每个服务器重复
COMPX_SVRY_SERVER_NAME	CompX Rack ServerY 名称；对 compute-rack-definitions 中的每个机架和机架中的每个服务器重复
MRG_NAME	群集托管资源组名称
MRG_LOCATION	群集 Azure 区域
NF_ID	对网络结构的引用
SP_APP_ID	服务主体应用 ID
SP_PASS	服务主体密码
SP_ID	服务主体 ID
TENANT_ID	订阅租户 ID
SUBSCRIPTION_ID	订阅 ID
KV_RESOURCE_ID	密钥保管库 ID
CLUSTER_TYPE	群集类型：Single 或 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 - 要添加的用户分配的托管标识的空格分隔资源 ID。添加后，此时只能通过 API 调用删除该标识。

使用 Azure 资源管理器模板编辑器创建群集

创建群集的另一种方法是使用 ARM 模板编辑器。

若要以这种方式创建群集，需要提供模板文件 (cluster.jsonc) 和参数文件 (cluster.parameters.jsonc)。可以使用以下两个文件查找 8 机架 2M16C SKU 群集的示例：

cluster.jsonc、cluster.parameters.jsonc

注意

若要获取正确的格式，请复制原始代码文件。 cluster.parameters.jsonc 文件中的值特定于客户，可能不是完整列表。更新特定环境的值字段。

在 Web 浏览器中导航到 Azure 门户，然后登录。
在 Azure 门户搜索栏中搜索“部署自定义模板”，然后从可用服务中选择它。
在编辑器中单击“生成自己的模板”。
单击“加载文件”。找到 cluster.jsonc 模板文件并上传它。
单击“ 保存”。
单击“编辑参数”。
单击“加载文件”。找到 cluster.parameters.jsonc 参数文件并上传它。
单击“ 保存”。
选择正确的订阅。
搜索资源组，查看它是否已经存在。如果不存在，创建新的资源组。
确保所有实例详细信息都正确。
单击“查看 + 创建”。

群集验证

成功创建运营商关系群集后，系统会在订阅中创建 Azure 资源。 cluster create 成功后会返回群集 ID、群集预配状态和部署状态。

查看群集的状态：

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

当资源的 provisioningState 显示 "provisioningState": "Succeeded" 时，表示群集创建完成

群集登录

可在以下位置查看群集创建日志：

查看 Azure 门户资源/资源组活动日志。
在 Azure CLI 命令行中传递 --debug 标志。

设置部署阈值

在群集部署之前，可以为其设置两种类型的部署阈值。它们是 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”（逐个机架）或“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（逐个机架）策略，CountSuccess 和暂停时间分别为 10 个节点和 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 个或以上的计算节点成功预配，就可以继续对下一个机架的计算节点进行群集部署。

注意

群集部署开始后无法更改部署阈值。

部署群集

创建群集后，可以触发部署群集操作。 “部署群集”操作会创建启动映像并部署群集。

“部署群集”会启动在群集管理器中发生的一系列事件。

验证群集/机架属性。
为临时启动群集生成可启动映像（验证基础结构）。
与目标启动计算机的智能平台管理接口(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 显示部署进度时，群集部署正在进行中。 detailedStatusMessage 中显示的一些部署进度示例为 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 门户资源/资源组活动日志。
在 Azure CLI 命令行中传递 --debug 标志。

通过 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 资源管理器模板编辑器创建群集

群集验证

群集登录

设置部署阈值

验证更新

部署群集

具有硬件验证的群集部署

跳过特定裸机的群集部署

群集部署失败

群集部署验证

群集部署日志记录

通过 API 更新群集标识

删除群集

反馈

其他资源