Azure Local 离线模式 Azure CLI 配置（系列篇十一）

Azure Local 离线模式 Azure CLI 配置 Runbook生产级适用场景Azure Local Azure CLI Disconnected Operations 文档定位可直接用于生产执行的 Runbook工程 SOP来源Use Azure CLI for Disconnected Operations for Azure Local体例说明本 Runbook 用 3 类标签组织✔执行步骤必须按顺序完成⚠故障模式已知问题与排查方向Best Practice仅 production hardening不重复官方内容理论推断统一收纳到末尾 Technical AnalysisIncluding Inferred Behavior——不混入执行步骤。0. 执行前置条件Pre-flight Checklist✔ 必须满足Azure Local appliance 已部署完成已存在Appliance Root CAapplianceRoot.cerLocal portal FQDN例autonomous.cloud.private已具备LocalMachine 管理员权限离线软件分发路径SMB / ISO / Repo⚠ 风险检查部署前签字项目状态Root CA 已导入⬜CLI 版本已确认⬜离线 extension 源已就绪⬜Cloud config FQDN 已与 portal 一致⬜1. 安装 Azure CLI统一 64-bit✔ 执行步骤Step 1从内网镜像源下载官方 64-bit MSIStep 2静默安装msiexec /i AzureCLI.msi /quiet或标准安装# 官方 MSI64-bit only # https://aka.ms/install-azure-cli-windows✔ 验证az version期望输出azure-cli: 2.81.0⚠ 故障模式问题原因排查azcommand not foundPATH 未刷新重启 shell / 重新登录CLI version mismatch装错 MSI32-bit / 旧版重装 64-bit 官方 MSIextension load failarchitecture mismatch32-bit 卸载统一 64-bit Best Practice所有节点统一 64-bit CLI禁止混用 32-bit CLI离线环境不要az upgrade——直接重新装新版 MSI2. 安装 CA 信任链企业级标准✔ 执行步骤Step 1导入根 CA 到 OS Trust Store唯一推荐方式Import-Certificate -FilePath C:\AzureLocal\applianceRoot.cer -CertStoreLocation Cert:\LocalMachine\RootStep 2安装pip-system-certs让 Python 走 OS trust store C:\Program Files\Microsoft SDKs\Azure\CLI2\python.exe -m pip install pip-system-certs✔ 验证Get-ChildItem Cert:\LocalMachine\Root | Where-Object { $_.Subject -like *Azure* }期望看到 appliance root CA 出现在列表中。⚠ 故障模式问题影响修复未导入 CAaz loginTLS failure重新 import仅改cacert.pemupgrade 后失效改回 OS trust store多节点不一致部署漂移GPO / Intune 统一分发 Best Practice关键✔唯一推荐方式OS Trust Store GPO / Intune 分发❌禁止修改certifi/cacert.pem3. 配置 Azure CLI CloudDisconnected Cloud✔ 执行步骤Step 1加载 OperationsModuleImport-Module OperationsModule\Azure.Local.DisconnectedOperations.psd1Step 2生成 cloud config参数以 module introspection 为准$cloudConfig Get-ApplianceAzCliCloudConfig -ExternalFqdn autonomous.cloud.private⚠️不要硬编码其他参数——用Get-Help Get-ApplianceAzCliCloudConfig -Full查实际参数集。Step 3写入配置$cloudConfig | Set-Content $env:APPDATA\Azure\myCloud.jsonStep 4应用 cloudaz cloud set --cloud-config $env:APPDATA\Azure\myCloud.json az cloud show✔ 验证az cloud list期望当前 cloud custom disconnected cloudendpoints 全部指向本地 FQDN。⚠ 故障模式问题原因排查login 仍走azure.comcloud 未 set重新az cloud setendpoint resolution failFQDN 不匹配 portal比对 portal 实际 FQDNJSON schema errormodule version mismatch升级 OperationsModule Best PracticeCloud config当成不可解析配置文件——不要复制字段名当 schema必须纳入CMDB / Git version control——多节点共享同一份每次升级 OperationsModule 后重新生成cloud config4. 登录验证Disconnected Login✔ 执行步骤az login --use-device-code浏览器打开显示的 URL在本地 portal 输入 device code 完成认证。✔ 验证az account show期望返回包含本地 subscription 的 JSON。⚠ 故障模式问题原因排查device code failportal endpoint 不可达Test-NetConnection portal FQDN 443login redirect to public cloudcloud config error重新跑 §35. 安装 Azure CLI Extensions离线模式✔ 执行步骤❗不允许直接 online install离线下会失败Step 1在能联网的镜像机上下载az extension add -n aksarc az extension add -n stack-hci-vm az extension add -n customlocationStep 2复制 extension 目录到内网分发路径%USERPROFILE%\.azure\cliextensions\Step 3在离线节点安装az extension add --source local-path✔ 验证az extension list期望列出 3 个 extension状态为Installed。⚠ 故障模式问题原因排查extension not foundrepo missing检查分发路径version conflictCLI 不兼容升级 / 降级 CLImodule load failcorrupted cacheaz extension remove -n name后重装 Best Practice不写死版本号——extension 版本会随 Azure Local release train 变化内网镜像机每月同步一次最新 extension 索引6. CLI 升级离线模式❗ 关键约束az upgrade在离线环境不可直接使用——会拉https://aka.ms/...失败。✔ 正确流程Step 1从内网 mirror repo 下载新版 MSIStep 2静默升级安装msiexec /i AzureCLI.msi /quietStep 3重启 shell重新加载✔ 验证az version期望azure-cli字段显式显示新版本号不是缓存旧值——这是假升级陷阱。⚠ 故障模式问题原因排查upgrade no effectcached CLI重启 shell /where.exe az确认路径extension brokenversion drift重新装匹配版本的 extension7. 健康检查Post-Install Validation Gate✔ 必须全部通过az version az cloud show az account show az extension list✔ 成功标准项目条件CLI2.81.0或当前文档版本cloudcustom disconnected cloudloginaz account show返回本地 subscriptionextension全部Installed4 项检查全部通过才能认为 CLI 配置完成——任一失败不能进入下一阶段。8. Failure Recovery恢复路径❌ Cloud misconfigurationaz cloud set --name AzureCloud # 重新生成 cloud config参考 §3❌ CA failure# 删除错误 cert Get-ChildItem Cert:\LocalMachine\Root | Where-Object { ... } | Remove-Item # 重新 import Import-Certificate -FilePath C:\AzureLocal\applianceRoot.cer -CertStoreLocation Cert:\LocalMachine\Root❌ Extension corruptionaz extension remove -n name # 重新 copy 离线包 az extension add --source local-path❌ CLI 假升级缓存旧版where.exe az # 确认实际加载的 CLI 路径 # 删除旧 MSI 残留重装新版9. 最终架构总结理解层User CLI ↓ Azure CLI Runtime (Python) ↓ Cloud Config (custom endpoint) ↓ OS Trust Store (CA chain) ↓ Azure Local Control Plane一句话总结这套 Runbook 的本质是把 Azure CLI 从云 CLI变成本地控制平面客户端。 Technical AnalysisIncluding Inferred Behavior本节是 Runbook 推理依据的存档——所有为什么这么做都在这里。不混入执行步骤。A. CLI 与架构选择A.1 为什么统一 64-bit官方从未说 Azure Local 禁止 32-bit但也不支持 32-bit 作为推荐路径。32-bit不是 hard failure而是unsupported untested32-bit Azure CLI 实际可装、可运行但不在 Microsoft 测试矩阵内可能引入兼容性 / 内存 / extension 加载问题企业部署原则按 supported 路径走不赌 untested 边缘场景。A.2 32-bit 实际风险不是技术禁止Python 32-bit 内存上限典型 2 GB—— 大型 ARM 调用可能 OOMExtension 兼容性矩阵窄32-bit MSI 不是 Microsoft 在 Azure Local 场景的推荐路径结论技术上不禁止但工程上不推荐——Runbook 不应该把unsupported包装成禁止。B. CA 信任链B.1pip-system-certs的真实作用范围pip-system-certs只影响 Pythonrequests库的 HTTP 调用。关键点Python-based extension→ 受影响 ✔Go / .NET / native binary extension→不受影响❌WinHTTP / Schannel 路径→不受影响❌因此 OS trust store pip-system-certs是增强信任不是完全替代 trust chain——但已经是最稳妥的方案。B.2 完整 CA 信任链路企业部署应全部覆盖信任层是否受pip-system-certs影响OS trust storeLocalMachine\RootOS 层 多数 native TLSPythonrequests信任✔通过pip-system-certsCLI extension 内部 native TLS❌自行保证Embedded toolsK8s client、Arc bridge❌走各自 trust chain浏览器用于本地 portal系统级OS trust store 已覆盖缺失任一环节都可能导致部分功能 SSL 失败。B.3 为什么禁止改cacert.pem风险说明az upgrade覆盖CLI 升级时cacert.pem被重置pip upgrade重置任何包管理操作都可能 drift配置漂移多节点场景下很快不一致审计风险标为 enterprise security baseline 偏离C. Extension 与 VersioningC.1 Extension 版本是 release-train 绑定stack-hci-vm/aksarc/customlocation强依赖 Azure Arc / Azure Local release train经常月更甚至周更不存在跨文档统一推荐版本VM 文档与 AKS 文档给的版本经常不一致——优先以最新文档为准C.2 Extension 解析源implementation-dependent⚠️ extension resolution 取决于configured source——不是固定机制可能是以下之一或组合Azure endpointaz extension add默认Arc resource provider feedlocal cache离线环境custom repo内网镜像不要在文档中固化Appliance 内置 extension 索引这种说法——它不是稳定公开机制。C.3Get-ApplianceAzCliCloudConfig的版本漂移官方没说参数会变化——但 OperationsModule 是 Microsoft 持续更新的组件。真实风险字段命名 / 必需参数可能随版本调整输出 JSON schema 可能更新甚至 function itself may be replaced across module versions更激进的版本变化应对不要把生成的 JSON 当成稳定 API每次升级 OperationsModule 后重新跑Get-HelpD. CLI 升级与假升级风险D.1 Air-gapped 下az upgrade的陷阱Air-gapped 模式下az upgrade拉https://aka.ms/...会失败部分 CLI 工具会静默 fallback到本地缓存版本表面看az version没变——实际你以为升级了但没有验证升级后az version必须显式显示新版本号否则视为升级失败。D.2 正确的离线升级路径步骤操作1内网 mirror repo 下载新版 MSI2msiexec /i AzureCLI.msi /quiet3重启 shell4where.exe az确认路径5az version显式验证E. Cloud Config 的实际语义Azure Local disconnected environment 确实需要custom cloud definitionendpoint override 指向本地 portal 的 ingress FQDN这是离线场景的核心——没有这一步az login会去找management.azure.com然后失败F. 跨版本兼容性官方没给出完整兼容矩阵——但可以从 release train 推断组件升级顺序Azure Local release notes起点Appliance build配套OperationsModule配套CLI与 OperationsModule 兼容extension绑定到 CLI release train生产升级顺序升级前看 Azure Local release notesCLI→ 2.extension→ 3.OperationsModule→ 4.Appliance逐项验证——不要跨大版本G. 为什么离线下az login --use-device-code是关键--use-device-code不要求本地有浏览器用户在任何能访问 local portal 的机器上输入 code 即可这正是离线场景的登录模式——az login走 local portal认证回调走 device codeH. 文档未明确的边界汇总文档没说Runbook 推断是否能装 32-bitunsupported untested按 64-bit 走cacert.pem修改的后果drift / 升级丢失 / 审计风险禁止extension source 机制implementation-dependent看内网配置Get-ApplianceAzCliCloudConfig稳定性每次升级重新跑Get-Helpaz upgrade离线行为静默 fallback必须显式验证