Azure Local VM 部署第 1 篇：Hyperconverged 路径完整实战

未经同意，请勿转载！

TL;DR ：Azure Local 2606 在 Hyperconverged（单集群、超融合） 路径下创建 VM，完整流程分为两大阶段：

阶段 1（前置条件）：订阅 + RBAC + Resource Group + VM image + Custom Location + Network Interface

阶段 2（创建 VM）：5 种部署方式（CLI / Portal / ARM / Bicep / Terraform）+ 3 类 VM 类型（Standard / Trusted Launch / Dynamic Memory）+ 3 类扩展能力（Proxy / Arc Gateway / Managed Identity）

本篇按"先 prereqs、再 create"的叙事主线展开。Multi-rack 路径见第 2 篇。

作者声明

本文中所有 Prerequisites 项、命令、参数、限制条件均直接引用自 Microsoft Learn 官方页面：
- Create Azure Local Virtual Machines Enabled by Azure Arc
"作者总结"小节是作者对官方文档中容易踩坑 或术语严谨性的整理，文中显式标注 $误区$ 与 $作者总结$ 区分官方原话。
文档版本：azloc-2606（2026 年 7 月视图）。

〇、HC vs MR 路径选型速查（5 秒决策）

业务需求	HC 路径	MR 路径
单集群 / 单机房	✅ 典型场景	✅ 可用但偏重
多机架 / 跨机房	❌ 不适用	✅ 典型场景
Trusted Launch（secure boot + vTPM）	✅ 支持	❌ 不支持
Dynamic Memory	✅ 支持	❌ 不支持
Availability Zone（机架级容灾）	❌ 不适用	✅ `--zone`
Strict Placement	❌ 不适用	✅ `--strict-placement`
Arc Gateway	✅ 支持	❌ 不支持
Marketplace 镜像	✅ 支持	❌ 仅 Storage account
Linux 仅 Ubuntu Server + Proxy	✅ 验证	✅ 强制
Proxy 强制	❌ 建议	✅ 强制

一句话选型：

HC 路径：单集群、需要 Trusted Launch / Dynamic Memory / Arc Gateway / Marketplace 镜像
MR 路径：多机架、需要机架级容灾、可接受 Standard + Static 内存降级

如果选 MR 路径，请看第 2 篇 · Multi-Rack 完整实战。

第一部分：前置条件（Prerequisites）

一、为什么 Hyperconverged 的 Prerequisites "只有一页"

维度	Hyperconverged（本篇）	Multi-rack（第 2 篇）
Prerequisites 位置	内嵌在 `create-arc-virtual-machines` 综合页	独立页 `multi-rack-vm-management-prerequisites`
章节结构	1 段（含 5 种 tab）	5 个 H2 章节
网络底座	单一 logical network	Network Fabric + L3 isolation domain
VM image 要求	仅列 3 种来源链接	明确内容要求：en-us / cloud-init / serial / VirtIO
客户端 CLI	1 项 prereq	5 步流程（含 extension 安装）

二、共同 Prerequisites：5 种部署方式都必须满足的 5 项

无论选择 Azure CLI / Azure Portal / ARM template / Bicep template / Terraform template 中哪一种，下面 5 项是必须的：

2.1 Azure 订阅 + RBAC 角色

官方原文（5 种 tab 全部包含） ："Access to an Azure subscription with the appropriate Azure role-based access control (RBAC) role and permissions assigned. For more information, see RBAC roles for Azure Local VM management."

角色配置细节见官方 assign-vm-rbac-roles 页面
HC 路径下沿用通用 built-in RBAC；MR 路径推荐"Infrastructure admin / Application admin"双角色模型
部署时只需要订阅级访问即可

2.2 Resource Group（资源组）

官方原文（5 种 tab 全部包含）："Access to a resource group where you want to provision the VM."

微软官方建议："For ease of management, we recommend that you use the same resource group as your Azure Local instance."
VM 与 Azure Local instance 同 RG 是建议做法------不强求
跨 RG 引用资源（disk / NIC / image / storage path）时，必须传完整 ARM resource ID

2.3 VM images（VM 镜像）

官方原文（5 种 tab 全部包含）："Access to one or more VM images on your Azure Local instance."

三种来源：

VM image starting from an image in Azure Marketplace

VM image starting from an image in an Azure Storage account

VM image starting from an image in a local share

来源	适用场景
Azure Marketplace	公开发行版 OS（Ubuntu / Windows Server 等）
Azure Storage account	客户上传到 Azure Storage 的自定义镜像
本地共享（local share）	本地 VHDX / 离线拷贝的镜像

作者展开：

galleryImage 是集群级资源------创建后可在多个 VM 创建命令中复用
三种来源是互斥的"或"关系------一次 VM 创建命令只用一种 image
MR 路径仅支持 Storage account------其他两种来源在 MR 下不可用

2.4 Custom Location（自定义位置）

官方原文（5 种 tab 全部包含） ："A custom location for your Azure Local instance that you use to provision VMs. The custom location shows up on the Overview page for your Azure Local instance."

Custom Location 是在 Azure Arc 注册 Azure Local 时自动创建 的 ARM 资源（RP Microsoft.ExtendedLocation/customLocations）
VM 创建命令中通过 --custom-location 参数传入 ARM resource ID
Custom Location 不是 Azure 区域------它是 Azure Local 集群定位符

2.5 Network Interface（网络接口）

官方原文（CLI tab 包含）："Access to a network interface that you created on a logical network associated with your Azure Local instance."

官方原文（ARM / Bicep / Terraform tab）："Access to a logical network that you associate with the VM on your Azure Local instance."

CLI 部署可以直接引用已创建的 NIC
ARM / Bicep / Terraform 部署通常引用 logical network
必须至少有 1 个 NIC 才能启用 guest management------这是官方明确要求

三、5 种部署方式差异项速查

部署方式	比共同项多需要的 prereq
Azure CLI	`az` 客户端；已创建好的 NIC；可选 storage path
Azure Portal	（仅共同项）
ARM template	GitHub `aka.ms/hci-vmarmtemp` 模板；logical network
Bicep template	`aka.ms/hci-vmbiceptemplate` 模板；logical network
Terraform template	Terraform v1.9.8 + Git + 4 个 provider（`azure/azapi` / `azure/modtm` / `hashicorp/azurerm` / `hashicorp/random`）；logical network

作者总结：

Azure Portal 路径 prereq 最小------浏览器 + Azure 订阅即可
ARM / Bicep 路径需要 sample template ------微软在 GitHub azure-quickstarts 仓库维护
Terraform 路径 prereq 最复杂------Terraform CLI + Git + 多个 Azure provider

四、VM images 是 VM 创建的"上游依赖"

复制代码

Azure Local 集群（已注册到 Arc，custom location 存在）
  ├─► galleryImage（VM image，三种来源）
  │    ├─ Marketplace 镜像
  │    ├─ Storage account 镜像
  │    └─ Local share 镜像
  ├─► logicalNetwork / virtualNetwork（网络底座）
  ├─► networkInterface（绑定到 logical network）
  └─► VM 实例（绑定 image + NIC + custom location）

第二部分：创建 VM（实战命令）

五、两条总前提

前提	文档出处
Provisioning State = Succeeded	"The VM is successfully created when the `provisioningState` parameter appears as `succeeded` in the output."
Guest Management 默认启用	"The VM created has guest management enabled by default. If for any reason guest management fails during VM creation, follow the steps in Enable guest management on the Azure Local VM..."

作者展开：

两个 DVD drives 默认创建------VM 配置过程中会临时挂载两个 ISO 文件（用于 guest agent 安装）；成功后 ISO 被删除，但 Windows Device Manager / Linux dmesg 可能仍看到空 DVD 设备
跨 RG 引用资源必须传完整 ARM resource ID------disk / NIC / image / storage path

六、Azure CLI 路径（最常用）

6.1 准备工作

复制代码

az login --use-device-code
az account set --subscription <Subscription ID>

6.2 必填参数速查

参数	说明
`--name`	VM 名称
`--resource-group`	VM 所在 RG
`--admin-username`	VM 管理员用户名
`--admin-password`	VM 管理员密码
`--image`	VM 镜像名 / ARM resource ID
`--location`	Azure 区域（`eastus` / `westeurope`）
`--custom-location`	Custom Location ARM resource ID
`--nics`	NIC 名称或 ID；至少 1 个
`--authentication-type`	`all` / `password` / `ssh`
`--memory-mb`	内存 MB
`--processors`	vCPU 数
`--storage-path-id`	可选；存储路径

6.3 三种 VM 类型

A. 标准 VM

复制代码

az stack-hci-vm create \
  --name $vmName \
  --resource-group $resource_group \
  --admin-username $userName \
  --admin-password $password \
  --computer-name $computerName \
  --image $imageName \
  --location $location \
  --authentication-type all \
  --nics $nicName \
  --custom-location $customLocationID \
  --hardware-profile memory-mb="8192" processors="4" \
  --storage-path-id $storagePathId

B. Trusted Launch VM（含 secure boot + vTPM）

复制代码

az stack-hci-vm create \
  --name $vmName \
  --resource-group $resource_group \
  --admin-username $userName \
  --admin-password $password \
  --computer-name $computerName \
  --image $imageName \
  --location $location \
  --authentication-type all \
  --nics $nicName \
  --custom-location $customLocationID \
  --hardware-profile memory-mb="8192" processors="4" \
  --storage-path-id $storagePathId \
  --enable-secure-boot true \
  --enable-vtpm true \
  --security-type "TrustedLaunch"

官方原文（关键） ："When you specify that security type as TrustedLaunch, you must enable secure boot and vTPM. Otherwise, TrustedLaunch VM creation fails."

作者展开 $误区$ ：

❌ 常见误区："我可以先创建标准 VM，然后再开 Trusted Launch" ✅ 真相：Trusted Launch 不可后开启------必须创建时指定

验证 Trusted Launch 生效：

复制代码

# 在集群节点上找到 VM owner node
Get-ClusterGroup $vmName
# 在 owner node 上验证
(Get-VM $vmName).GuestStateIsolationType
# 应返回 TrustedLaunch

C. Dynamic Memory VM

复制代码

az stack-hci-vm create \
  --name "my_dynmemory" \
  -g "my_registration" \
  --admin-username "admin" \
  --admin-password "<password>" \
  --custom-location "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ExtendedLocation/customLocations/<cl>" \
  --location "eastus2euap" \
  --image "/subscriptions/<sub>/resourceGroups/<rg>/microsoft.azurestackhci/marketplacegalleryimages/<image>" \
  --hardware-profile vm-size="Custom" processors=1 memory-mb=1024 maximum-memory-mb=2048 minimum-memory-mb=1024 target-memory-buffer=20 \
  --enable-agent true \
  --nics "dynnic"

Dynamic Memory 参数	说明
`vm-size="Custom"`	必须设为 Custom
`memory-mb`	启动内存（最少 1024）
`maximum-memory-mb`	上限；≥ memory-mb
`minimum-memory-mb`	下限；≤ memory-mb
`target-memory-buffer`	百分比（20 = 20%）

6.4 Linux VM

同一条 az stack-hci-vm create 命令
--image 必须指向 Linux image
SSH keys：--ssh-key-values <keyfile> + --authentication-type ssh
用户名密码：--authentication-type password

官方原文（关键） ："Setting the proxy server during VM creation is supported for Ubuntu Server VMs."

作者总结：

⚠️ HC 路径下 Linux VM 用 Proxy 仅 Ubuntu Server 验证过------其他发行版需手动配置

6.5 Windows Server 2012 / 2012 R2 特殊处理

官方原文："Windows Server 2012 and Windows Server 2012 R2 do not support enabling guest management as this operating system lacks support for Hyper-V sockets which is required for enabling guest management."

关键参数：

复制代码

--enable-agent false
--enable-vm-config-agent false

Flag	作用
`--enable-agent`	控制 Azure Connected Machine Agent 是否在 VM 内启动
`--enable-vm-config-agent`	控制 VM agent 通过 Hyper-V sockets 从 host 注入；WS 2012/2012 R2 不支持 Hyper-V sockets

七、Azure Portal 路径（最少 prereq）

7.1 5 步流程

Azure Arc cluster view → Virtual machines
顶部命令栏 → + Create VM
Basics tab → Project details + Instance details
VM extensions → 启用 Guest Management
提交

7.2 关键参数

字段	说明
Subscription	计费绑定
Resource group	新建或选已有
Virtual machine name	小写字母 + 可含连字符/数字
Custom location	自动筛选已注册 Azure Local
Virtual machine kind	自动设为 Azure Local
Security type	Standard 或 Trusted launch
Image	Marketplace 镜像或客户管理镜像
Virtual processor count	vCPU 数
Memory	MB 单位
Memory type	Static 或 Dynamic

八、ARM template 路径

官方 quickstart：https://aka.ms/hci-vmarmtemp
关键差异：使用 logical network（CLI 用 NIC）
部署通过 az deployment group create 触发
适用场景：与 ARM 标准工作流 / Azure Policy / Blueprints / CI/CD 集成

九、Bicep template 路径

官方 quickstart：https://aka.ms/hci-vmbiceptemplate
与 ARM 差异：更简洁语法 + 强类型 + 模块化
部署命令：

az bicep build --file main.bicep
az deployment group create --resource-group $resource_group --template-file main.json --parameters @parameters.json

十、Terraform 路径（Azure Verified Module）

10.1 模块来源

Azure Verified Module ：terraform-azurerm-avm-res-azurestackhci-virtualmachineinstance
含两个 examples：default/ （1 个 VM）、multi/（多个 VM）

10.2 部署流程

复制代码

git clone https://github.com/Azure/terraform-azurerm-avm-res-azurestackhci-virtualmachineinstance
cd terraform-azurerm-avm-res-azurestackhci-virtualmachineinstance/examples/default
terraform init
terraform plan
terraform apply

10.3 Provider 依赖（官方示例）

Provider	版本
`hashicorp/azurerm`	v3.116.0
`azure/azapi`	v1.15.0
`azure/modtm`	v0.3.2
`hashicorp/random`	v3.6.3
Terraform CLI	v1.9.8

十一、3 类扩展能力

11.1 Proxy 配置（生产环境必备）

官方原文 ："Use the optional parameter proxy-configuration to configure a proxy server for your VM."

子参数	说明
`http_proxy`	HTTP 代理 URL
`https_proxy`	HTTPS 代理 URL（仍可用 HTTP 地址）
`no_proxy`	绕过代理的 URL 列表
`cert_file_path`	代理服务器证书路径

典型命令（含认证）：

复制代码

az stack-hci-vm create ... \
  --proxy-configuration \
    http_proxy="http://ubuntu:***@192.168.200.200:3128" \
    https_proxy="http://ubuntu:***@192.168.200.200:3128" \
    no_proxy="localhost,127.0.0.1,.svc,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,100.0.0.0/8,s-cluster.test.contoso.com" \
    cert_file_path="C:\ClusterStorage\UserStorage_1\server.crt"

官方原文（重要警告） ："Don't pass cert_file_path="" (an empty value), because the command fails when it tries to open a nonexistent file."

作者总结 $误区$ ：

❌ 常见误区："配了 Proxy，VM 内所有流量都走代理" ✅ 真相：Proxy 只设置环境变量 给 Azure Connected Machine Agent。浏览器 / WinInet / netsh / 用户应用需自己配置

11.2 Arc Gateway（简化网络配置）

官方原文："Configure the Azure Arc gateway to reduce the number of required endpoints that are needed to provision and manage Azure Local VMs with the Azure Connected Machine Agent."

复制代码

# 不带 Proxy
az stack-hci-vm create ... --gateway-id $gw

# 带 Proxy
az stack-hci-vm create ... --gateway-id $gw \
  --proxy-configuration http_proxy="..." https_proxy="..." no_proxy="..." cert_file_path="..."

端点白名单（必须放行）：

"For Windows VMs, allow the following endpoints: https://agentserviceapi.guestconfiguration.azure.com and https://<azurelocalregion>-gas.guestconfiguration.azure.com."

"For Linux VMs, allow the following endpoints: https://agentserviceapi.guestconfiguration.azure.com, https://<azurelocalregion>-gas.guestconfiguration.azure.com, and https://packages.microsoft.com."

端点	Windows	Linux
`agentserviceapi.guestconfiguration.azure.com`	✅	✅
`<azurelocalregion>-gas.guestconfiguration.azure.com`	✅	✅
`packages.microsoft.com`	❌	✅

作者总结：

⚠️ Linux 多一个端点 ：packages.microsoft.com（用于 apt/yum/zypper 包管理）。这条容易被遗漏 ⚠️ MR 路径 Arc Gateway 不支持------见第 2 篇

11.3 Managed Identity（自动启用）

官方原文 ："When the VMs are created on your Azure Local instance via the Azure CLI or the Azure portal, a system-assigned managed identity is also created that lasts for the lifetime of the VMs."

"The VMs on your Azure Local instance are extended from Azure Arc-enabled servers and can use system-assigned managed identity to access other Azure resources that support authentication based on Microsoft Entra ID."

"For example, the VMs can use a system-assigned managed identity to access Azure Key Vault."

作者展开：

Azure Local VM 启用 Guest Management 后自动注册到 Azure Arc（成为 Arc-enabled server）
system-assigned managed identity 不需要 az identity assign------全自动
可直接访问 Azure Key Vault / Azure Storage / Azure SQL 等支持 Microsoft Entra ID 认证的资源

十二、5 种部署方式 × 3 类能力交叉速查

能力	Azure CLI	Portal	ARM	Bicep	Terraform
Trusted Launch	✅	✅	✅	✅	✅
Dynamic Memory	✅	✅	✅	✅	✅
Proxy	✅	✅	✅	✅	✅
Arc Gateway	✅	✅	✅	✅	✅
WS 2012/2012 R2	✅	✅	✅	✅	✅
Linux Ubuntu + Proxy	✅	✅	✅	✅	✅
system-assigned MI	✅	✅	✅	✅	✅

第三部分：常见误区、Takeaway、附录

十三、常见误区

误区 1："我准备用 Portal，为什么还需要 az CLI？"

真相：Azure Portal 路径不需要 az CLI------这是 Azure CLI tab 的专属 prereq。但其他 4 种部署方式都需要各自工具链（CLI / ARM / Bicep / Terraform）。

误区 2："创建 VM 时一定要装 Guest Management"

真相：Guest Management 默认启用 ，但Windows Server 2012 / 2012 R2 不支持 。WS 2012/2012 R2 → 必须 --enable-agent false + --enable-vm-config-agent false。

误区 3："Custom Location 是个 Azure 区域吗？"

真相：不是 Azure 区域 ------是 Azure Arc 体系下的"扩展定位符"。Azure 区域参数（--location eastus）依然需要；Custom Location 是叠加在 Azure 区域之上的 Azure Local 集群定位。

误区 4："Trusted Launch 创建后可以再开启"

真相：不可后开启 。--security-type TrustedLaunch 是创建时参数。

误区 5："HC 也强制 Proxy"

真相：HC 路径 Proxy 是建议（"Use the optional parameter"）。MR 路径才是强制。

误区 6："cert_file_path 可以传空字符串"

真相：绝对不可以------命令会失败（找不到文件）。

误区 7："Arc Gateway 可以替代 Proxy"

真相：不完全替代 ------Arc Gateway 只接管 Azure Arc 流量；企业应用流量仍走 Proxy / 防火墙。

误区 8："我配了 Linux 端点白名单，但 Linux VM 装包仍失败"

真相：Linux 比 Windows 多一个端点 https://packages.microsoft.com------不在 Windows 列表里。

十四、Takeaway

HC 路径 Prerequisites 内嵌------5 种部署方式共用 5 项 prereq
Azure Portal 路径 prereq 最小------浏览器 + Azure 订阅即可
ARM / Bicep 路径多需要 sample template ------GitHub azure-quickstarts 仓库
Terraform 路径 prereq 最复杂------Terraform CLI + 4 个 provider + Git
VM image 是 VM 创建的"上游"------Marketplace / Storage account / Local share 三选一
Custom Location 不是 Azure 区域------是 Azure Local 集群定位符
Provisioning State = Succeeded 是创建成功的唯一标志
Guest Management 默认启用------WS 2012/2012 R2 必须显式 false
Trusted Launch 不可后开启------必须创建时指定
Proxy 是建议 （HC）/ 强制（MR）------Multi-rack 不配 Proxy → Guest Management 失败
cert_file_path 不能传空字符串------否则命令失败
Arc Gateway 简化端点 ------但 Linux 多 packages.microsoft.com 一条
system-assigned managed identity 自动创建 ------不需要 az identity assign

附录 A：术语约定

术语	含义
Azure Local VM	运行在 Azure Local 集群上、已注册到 Azure Arc 的 VM（资源类型 `Microsoft.AzureStackHCI/virtualMachineInstances`）
Guest Management	Azure Connected Machine Agent 在 VM 内的部署能力
Custom Location	Azure Arc 扩展定位符，标识 Azure Local 集群位置
Logical Network	Azure Local 的网络底座
Trusted Launch	VM 安全类型（含 secure boot + vTPM）；2602+ 默认推荐
Hyperconverged	Azure Local 的"经典形态"------单集群、超融合
Arc Gateway	Azure Arc 流量聚合 endpoint
system-assigned managed identity	Azure 自动给 VM 分配的托管标识

附录 B：参考链接

主文档：Create Azure Local Virtual Machines Enabled by Azure Arc
RBAC 角色：assign-vm-rbac-roles
VM image 三种来源：Marketplace / Storage account / Local share
ARM template quickstart：https://aka.ms/hci-vmarmtemp
Bicep template quickstart：https://aka.ms/hci-vmbiceptemplate
Terraform AVM 仓库：terraform-azurerm-avm-res-azurestackhci-virtualmachineinstance
Managed Identity：System-assigned managed identities
第 2 篇（Multi-rack 完整路径）：Azure-Local-VM-Deploy-02-Multi-Rack.md

文档维护：本篇对应 azloc-2606（2026 年 7 月视图）。如官方在更高版本拆分 Create VM 章节为按 workload 类型（GPU / SQL / AVD）的子页面，本篇将随之更新。