Azure Local离线模式部署 Appliance（系列篇之九）

1. 关键注意点（官方原文 Important 段）

|--------------|------------------------------------------------------------------------------|
| 项 | 说明 |
| 网络/名称一致性 | Portal 输入的参数必须与已建交换机命名/网段一致 |
| 不支持虚拟部署 | 必须用物理机 |
| VLAN | Appliance 如果需要 VLAN，用 Set-VMNetworkAdapterIsolation -ManagementOS 设置 |
| 节点数 | 最少 3 节点 ；管理 instance 最多 16 节点 |
| 部署时长 | 可能数小时（详见 §10.4） |
| 控制面可用性 | 节点重启/升级期间可能短暂不可用（详见 §10.2） |
| 部署盘 | 会建一个 2 TB thin-provisioned infrastructure volume ------不要动（详见 §10.1） |
| Appliance 迁移 | 集群创建后，appliance VM 会从单节点迁到 cluster storage、转为 clustered VM（详见 §10.3） |

2. 部署前置条件（官方清单）

|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 需求 | 文档 |
| 硬件 | Eligibility criteria |
| 身份 | Identity 文档 |
| 网络 | Network 文档 |
| PKI | PKI 文档 |
| 准备节点 | Prepare 文档 |
| 获取文件 | Acquire 文档 |

部署前 Checklist（官方原文）

网络计划（IP pool、ingress IP、FQDN、DNS、网关）
DNS server 能解析 FQDN
Azure Local 节点本地凭据
部署用的 Active Directory 凭据
AD OU 和网络需求（按 Azure Local 部署前置）
密码复杂度满足要求
AD 已准备好 Azure Local 部署
约 23 张 ingress 证书 + 根 CA 公钥（具体数量以 Manifest 和 Endpoint Matrix 为准------后续版本可能调整）
2 张 management 证书
身份提供商参数（AD FS 应用、credential、服务器、证书链）
Disconnected operations 部署文件（manifest + appliance）
Azure Local composite ISO
OEM 固件/驱动

⚠️ 证书数量说明 ：当前 Azure Local 2601 版本共需约 23 张 Ingress Endpoint Certificates，未来版本（2602/2603/...）可能为 25、27 等不同数量 ------具体以 Manifest 和 Endpoint Matrix 为准，不要硬记数字。

3. 部署序列（工具 / 执行节点 / 权限全景）

|-------------------------------------------|------------------------------|---------------|--------------------|
| 阶段 | 工具 | 实际执行节点 | 权限 |
| 1. OS 安装/配置 | 标准工具 | 全部节点 | 本地管理员 |
| 2. Operations module + bootstrap | PowerShell | Seed Node | 本地管理员 |
| 3. Install-Appliance（基础设施卷 + K8s + ARM） | PowerShell | Seed Node | 本地管理员 |
| 4. 集群创建 + Appliance 迁移 | 自动（无需手动干预） | Cluster | Owner RBAC role |
| 5. 注册 / 日常运维 | 本地 Portal / PowerShell / CLI | Cluster | Operator RBAC role |

Seed Node = 节点名排序最小的节点；只作为 bootstrap 协调者，集群建好之后没有特殊身份（详见 §10.5）。

4. 部署详细步骤（PowerShell 流水）

4.1 准备基础路径与文件

复制代码

$applianceConfigBasePath = 'C:\AzureLocalDisconnectedOperations'

# 复制下载文件到 seed node
Copy-Item \\fileserver\share\azurelocalfiles\* $applianceConfigBasePath

# 期望看到的文件
Get-ChildItem $applianceConfigBasePath
# AzureLocal.DisconnectedOperations.zip
# AzureLocal.DisconnectedOperations.manifest
# ArcA_LocalData_A.vhdx
# ArcA_SharedData_A.vhdx
# OSAndDocker_A.vhdx
# ArcA_SharedData_ACSTable_A.vhdx
# ArcA_SharedData_ACSBlob_A.vhdx
# ThirdPartyNotices.txt

4.2 解压 zip

复制代码

Expand-Archive "$($applianceConfigBasePath)\AzureLocal.DisconnectedOperations.zip" `
    -DestinationPath $applianceConfigBasePath
# 解压后删除 zip 省空间

解压后期望：

复制代码

OperationsModule/
AzureLocal.DisconnectedOperations.manifest
manifest.xml
IRVM.zip
ArcA_LocalData_A.vhdx
ArcA_SharedData_A.vhdx
ArcA_SharedData_ACSBlob_A.vhdx
ArcA_SharedData_ACSTable_A.vhdx
OSAndDocker_A.vhdx
Storage.json

4.3 拷贝证书

复制代码

$certsPath = "$($applianceConfigBasePath)\certs"
Copy-Item \\fileserver\share\azurelocalcerts $certspath -recurse

# 期望结构
Get-ChildItem $certsPath
Get-ChildItem $certsPath -recurse -filter *.pfx
# ManagementEndpointsCerts/
# IngressEndpointsCerts/
# 总共 ≥ 24 张证书

4.4 导入 OperationsModule

复制代码

Import-Module "$applianceConfigBasePath\OperationsModule\Azure.Local.DisconnectedOperations.psd1" -Force

$mgmntCertFolderPath = "$certspath\ManagementEndpointsCerts"
$ingressCertFolderPath = "$certspath\IngressEndpointsCerts"

5. 三组配置对象（必填）

5.1 Management 网络配置

复制代码

$CertPassword = "retracted" | ConvertTo-Securestring -AsPlainText -Force
$ManagementIngressIpAddress = "192.168.50.100"
$ManagementNICPrefixLength = 24

$mgmtNetworkConfigParams = @{
    ManagementIpAddress           = $ManagementIngressIpAddress
    ManagementIpv4PrefixLength    = $ManagementNICPrefixLength
    TlsCertificatePath            = "$mgmntCertFolderPath\ManagementEndpointSsl.pfx"
    TlsCertificatePassword        = $CertPassword
    ClientCertificatePath         = "$mgmntCertFolderPath\ManagementEndpointClientAuth.pfx"
    ClientCertificatePassword     = $CertPassword
}
$managementNetworkConfiguration = New-ApplianceManagementNetworkConfiguration @mgmtNetworkConfigParams

5.2 Ingress 网络配置

复制代码

$azureLocalDns = "192.168.200.150"
$NodeGw = "192.168.200.1"
$IngressIpAddress = "192.168.200.115"
$NICPrefixLength = 24

$ingressNetworkConfigurationParams = @{
    DnsServer                  = $azureLocalDns
    IngressNetworkGateway      = $NodeGw
    IngressIpAddress           = $IngressIpAddress
    IngressNetworkPrefixLength = $NICPrefixLength
    ExternalDomainSuffix       = "autonomous.cloud.private"
}
$ingressNetworkConfiguration = New-ApplianceIngressNetworkConfiguration @ingressNetworkConfigurationParams

5.3 Identity 配置

复制代码

$oidcCertChain = Get-CertificateChainFromEndpoint -requestUri 'https://adfs.azurestack.local/adfs'

# 没 LDAPS 可省略下一行
$ldapsCertChain = Get-CertificateChainFromEndpoint -requestUri 'https://dc01.azurestack.local'

$ldapPort = 3269  # 3268 = 非加密
$ldapPassword = 'RETRACTED' | ConvertTo-SecureString -AsPlainText -Force

$identityParams = @{
    Authority                     = "https://adfs.azurestack.local/adfs"
    ClientId                      = "<ClientId>"
    RootOperatorUserPrincipalName = "operator@azurestack.local"
    LdapServer                    = "adfs.azurestack.local"   # demo 值
    LdapPort                      = $ldapPort
    LdapCredential                = New-Object PSCredential -ArgumentList @("ldap", $ldapPassword)
    SyncGroupIdentifier           = "<SynGroupIdentifier>"
    OidcCertChainInfo             = $oidcCertChain
    LdapsCertChainInfo            = $ldapsCertChain
}
$identityConfiguration = New-ApplianceExternalIdentityConfiguration @identityParams

⚠️ 企业最佳实践（推荐）：

|-----------------|-----------------------|-----------|-------------------------------------------------------------|
| 协议 | 推荐目标 | 不推荐目标 | 原因 |
| OIDC（身份认证） | AD FS | 直接连 DC | AD FS 是 OIDC 标准实现，承载 Federation 协议；DC 不直接对外暴露 OIDC endpoint |
| LDAPS（目录同步） | Domain Controller | ADFS | LDAP/LDAPS 是目录访问协议，身份同步最终来源就是 AD；AD FS 本身也只是 AD 的代理 |

即：LdapServer = dc01.contoso.com（直接 DC），Authority = https://adfs.contoso.com/adfs（AD FS）。

OidcCertChainInfo 和 LdapsCertChainInfo 可以省略（demo 用），但生产强烈建议填。

6. 安装 / 启动 Appliance

OperationsModule 提供 Install-Appliance cmdlet（在 deploy 文档后续章节会展开，因文档超过抓取上限未能完整捕获）。输入上述三个配置对象开始 bootstrap。

⚠️ 安装会：①建 2 TB infrastructure volume；②部署 appliance VM；③从 seed node 出发扩展为集群 VM。预计数小时（详见 §10.4）。

7. 部署后注册（下一节）

部署完成后必须用一次联网做 self-attestation 注册------见 deploy-register.md。

8. Appliance 内部架构（官方未展开）

官方没有提供 Appliance 内部架构图------但了解组件构成有助于理解部署时长、迁移逻辑、故障定位。下面的图示基于官方文档 + Arc Resource Bridge 公开技术资料综合推断。

关键解读：

Infrastructure Volume 才是核心------Appliance VM 只是这个卷上的一个 VHDX，所有 K8s / ARM 数据都在卷上

Appliance 是"自带 K8s 的"------它不是传统 Windows Server 角色，而是一个 Arc Resource Bridge + K8s + Local ARM 的复合体

注册为 Cluster Role 之后------Appliance 像其他 VM 一样享受 HA 能力（节点故障时自动迁移）

9. 部署后注册（自我证明 / Self-Attestation）

部署完成后，必须用一次联网做 self-attestation 注册------见 deploy-register.md。

理论上 Air-gapped 模式可以通过双向便携介质完成 self-attestation，但实务上建议至少在控制面初始化阶段临时开放一次出站 ------这是 Microsoft 支持链路里最难离线化的环节。

10. 技术分析（官方未展开说明）

本节专门解释官方文档没有明说的技术原理。每个点都是企业部署时绕不开的"为什么"。

10.1 Infrastructure Volume 的本质（2 TB Thin）

官方原文（Important 段）： "A 2 TB thin-provisioned infrastructure volume gets created as part of this step. Don't attempt to modify, expand, or use the volume."

技术分析：

Infrastructure Volume 本质是 Azure Local 创建的 Storage Spaces Direct（S2D）Thin-Provisioned Virtual Disk。

因此，它天然继承 S2D Virtual Disk 的标准能力，包括：

Online Expand（在线扩容）
Storage Pool 扩容
ReFS 在线扩展

微软当前文档没有单独讨论该卷的扩容策略，因为这是 S2D 的基础能力，而不是 Deploy 文档关注点。

企业环境如果确有容量需求 ：可以按 Azure Local / S2D 的标准方式扩容，但应避免影响 Appliance 生命周期管理------扩容后 Operations Module 的版本检测、镜像校验等流程需要重新跑。

10.2 Control Plane 不可用的影响范围

官方原文："The control plane might be down for a while during node reboots and upgrades."

技术分析：

Control Plane 主要承载 ARM API、Portal、Operations Module 等管理能力。节点升级期间，Control Plane VM 可能发生迁移或重启，因此 Portal / API 会短暂不可用。

这并不意味着 S2D 或 Hyper-V 工作负载会同时停止。

正常情况下：

Management Plane（Portal / ARM / Operations Module）------ 受影响
Compute Plane （CSV / VM / Storage Stack）------ 继续运行
Workload 业务 VM------ 不受影响（高可用由 Hyper-V Cluster 保证）

两者生命周期不同：Compute Plane 升级是逐节点的滚动升级，Management Plane 是整体重启/迁移。

写"正常情况下"而不是绝对化 ------极端场景（如 S2D 同时出问题）下两者会一起受影响，但这是 Azure Local 整体异常，不是断开操作特有。

10.3 Appliance Migration 的实际步骤

官方原文："Once the cluster is created, the appliance is moved to cluster storage, and the VM is registered as a cluster VM."

技术分析：

Bootstrap 初期 Appliance VM 部署在 Seed Node 本地存储上。Cluster 创建完成以后，按以下顺序自动迁移：

Infrastructure Volume 建立（S2D 池中创建 2 TB thin 卷）
CSV Online（Cluster Shared Volume 联机，作为共享存储后端）
Appliance VM 存储迁移（从 Seed Node 本地存储 → CSV 上的 Infrastructure Volume）
VM 注册为 Cluster Role（成为 Hyper-V Cluster 资源，享受 HA 能力）

之后 Appliance 不再依赖 Seed Node------Seed Node 可以下线/重启，Appliance 会自动迁移到其他节点。

10.4 `Install-Appliance` 为什么"数小时"

官方原文："This step takes a few hours. Don't try to interrupt the process."

技术分析：

Install-Appliance 并不是"部署一个 VM"------而是在按顺序部署多个组件栈：

|--------|-------------------------------------------------|-----------|
| 阶段 | 部署内容 | 典型耗时 |
| 1 | 创建 Infrastructure Volume（S2D thin） | 分钟级 |
| 2 | 部署 Appliance VM（OS + 基础镜像） | 10-30 min |
| 3 | 初始化 Kubernetes Runtime（Arc Resource Bridge 拉镜像） | 30-60 min |
| 4 | 部署 Local ARM / Identity / Monitoring Stack | 30-60 min |
| 5 | 注册 Cluster Role / 迁移到 CSV | 10-30 min |

总耗时 1.5-3 小时是正常范围------最慢的环节是 K8s 镜像拉取与初始化（如果是 Air-gapped，OperationsModule 会从本地介质加载，时间可能更短但仍需等待 K8s 自身 ready）。

10.5 Seed Node 的真实角色

官方原文："Run the deploy step on the first machine by alphabetical order."

技术分析：

Seed Node 只是 Bootstrap Coordinator（启动协调者）------负责：

发起 Install-Appliance 命令
提供本地暂存（部署初期 Appliance VM 跑在它的本地存储上）
触发 cluster create + appliance migration

最终 Appliance 迁移到 Cluster 之后，Seed Node 没有特殊身份------它就是集群里的一个普通节点。

因此 Seed Node 选谁并不关键 ------但选硬件配置最好 的节点、或网络位置最便利的节点，可减少后期运维摩擦。

10.6 部署脚本时序（哪个节点先跑什么）

官方原文："All nodes must complete prepare steps first, then deploy on seed node."
官方没说"其余节点何时加入集群"------按 Azure Local 集群创建标准流程：seed node 触发 cluster create 后，剩余节点通过 Add-ClusterNode 或 Azure Local AddNode cmdlet 加入；具体顺序由 OperationsModule 自动协调，无需人工干预。

10.7 "可能数小时"的最长时限

官方没明确给出 SLA 上限。实务经验：

健康部署：1.5--3 小时

拉镜像缓慢：4--6 小时

超过 8 小时未完成：按 Troubleshoot 文档排查

进度查看路径：OperationsModule 实时输出 + Cluster Event Log（Get-WinEvent -LogName "Microsoft-Windows-FailoverClustering/Operational"）

10.8 `Install-Appliance` 的 Idempotency

官方没说"失败后能否重跑"------按已知 issue 与 OperationsModule 行为：

失败重跑前 通常需要先 Remove-Appliance 或手工清理残留 VHDX / Cluster Role

如果 control plane 部署卡住 > 8 小时，官方建议直接 redeploy（不是 fix，是重建）

详细 cleanup 流程：Azure Local Cleanup Script

Azure Local离线模式部署 Appliance（系列篇之九）

1. 关键注意点（官方原文 Important 段）

2. 部署前置条件（官方清单）

部署前 Checklist（官方原文）

3. 部署序列（工具 / 执行节点 / 权限 全景）

4. 部署详细步骤（PowerShell 流水）

4.1 准备基础路径与文件

4.2 解压 zip

4.3 拷贝证书

4.4 导入 OperationsModule

5. 三组配置对象（必填）

5.1 Management 网络配置

5.2 Ingress 网络配置

5.3 Identity 配置

6. 安装 / 启动 Appliance

7. 部署后注册（下一节）

8. Appliance 内部架构（官方未展开）

9. 部署后注册（自我证明 / Self-Attestation）

10. 技术分析（官方未展开说明）

10.1 Infrastructure Volume 的本质（2 TB Thin）

10.2 Control Plane 不可用的影响范围

10.3 Appliance Migration 的实际步骤

10.4 Install-Appliance 为什么"数小时"

10.5 Seed Node 的真实角色

10.6 部署脚本时序（哪个节点先跑什么）

10.7 "可能数小时"的最长时限

10.8 Install-Appliance 的 Idempotency

3. 部署序列（工具 / 执行节点 / 权限全景）

10.4 `Install-Appliance` 为什么"数小时"

10.8 `Install-Appliance` 的 Idempotency