解决 AKS Arc 安装过程中的问题和错误

运行 Install-AksHci 后出现此错误消息。

如果不使用专用链接，请使用以下步骤解决此问题：

1. 打开 PowerShell 并运行 Uninstall-AksHci。
2. 打开 Azure 门户，并导航到运行 Install-AksHci 时使用的资源组。
3. 检查任何处于“断开连接”状态和包括显示为随机生成的 GUID 的名称的已连接群集资源。
4. 删除这些群集资源。
5. 关闭 PowerShell 会话并打开新会话，然后再次运行 Install-AksHci。

此错误可能是由于安装过程尝试违反在 Azure Arc 载入过程中提供的 Azure 订阅或资源组上设置的 Azure 策略而导致的。 对于在订阅或资源组级别定义了 Azure 策略的用户，然后尝试在违反 Azure Policy 的 Azure 本地上安装 AKS 的用户，可能会出现此错误。

若要解决此问题，请阅读错误消息，了解 Azure 管理员设置的 Azure Policy 已被违反，然后通过对 Azure 策略发出异常来修改 Azure 策略。 若要了解有关 Policy 例外的详细信息，请参阅 Azure Policy 例外结构。

以前安装的功能仍处于失败状态，并且尚未清除。 你可能会看到以下错误：

Exception [An error occurred while creating resource 'MOC Cloud Agent Service' for the clustered role 'ca-3f72bdeb-xxxx-4ae9-a721-3aa902a998f0'.]
Stacktrace [at Add-FailoverClusterGenericRole, C:\Program Files\WindowsPowerShell\Modules\Moc\1.0.20\Common.psm1: line 2987
at Install-CloudAgent, C:\Program Files\WindowsPowerShell\Modules\Moc\1.0.20\Moc.psm1: line 1310
at Install-MocAgents, C:\Program Files\WindowsPowerShell\Modules\Moc\1.0.20\Moc.psm1: line 1229
at Initialize-Cloud, C:\Program Files\WindowsPowerShell\Modules\Moc\1.0.20\Moc.psm1: line 1135
at Install-MocInternal, C:\Program Files\WindowsPowerShell\Modules\Moc\1.0.20\Moc.psm1: line 1078
at Install-Moc, C:\Program Files\WindowsPowerShell\Modules\Moc\1.0.20\Moc.psm1: line 207
at Install-AksHciInternal, C:\Program Files\WindowsPowerShell\Modules\AksHci\1.1.25\AksHci.psm1: line 3867
at Install-AksHci, C:\Program Files\WindowsPowerShell\Modules\AksHci\1.1.25\AksHci.psm1: line 778
at <ScriptBlock>, <No file>: line 1]
InnerException[The object already exists]

或者，你可能看到：

Install-Moc failed.
Exception [Unable to save property changes for 'IPv4 Address xxx.168.18.0'.]
Stacktrace [at Add-FailoverClusterGenericRole, C:\Program Files\WindowsPowerShell\Modules\Moc\1.0.20\Common.psm1: line 2971
at Install-CloudAgent, C:\Program Files\WindowsPowerShell\Modules\Moc\1.0.20\Moc.psm1: line 1310
at Install-MocAgents, C:\Program Files\WindowsPowerShell\Modules\Moc\1.0.20\Moc.psm1: line 1229
at Initialize-Cloud, C:\Program Files\WindowsPowerShell\Modules\Moc\1.0.20\Moc.psm1: line 1135
at Install-MocInternal, C:\Program Files\WindowsPowerShell\Modules\Moc\1.0.20\Moc.psm1: line 1078
at Install-Moc, C:\Program Files\WindowsPowerShell\Modules\Moc\1.0.20\Moc.psm1: line 207
at Install-AksHciInternal, C:\Program Files\WindowsPowerShell\Modules\AksHci\1.1.25\AksHci.psm1: line 3867
at Install-AksHci, C:\Program Files\WindowsPowerShell\Modules\AksHci\1.1.25\AksHci.psm1: line 778
at <ScriptBlock>, <No file>: line 1]
InnerException[A matching cluster network for the specified IP address could not be found]

若要解决此问题，请手动清理群集角色。 可以通过运行以下 PowerShell cmdlet 从故障转移群集管理器中删除资源： Remove-ClusterResource -name <resource name>

该 Install-AksHci cmdlet 失败，并显示“API 调用返回的 GetRelease 错误：文件下载错误：哈希不匹配”。

1. 打开 PowerShell 并运行 Uninstall-AksHci。
2. 重试安装。
3. 如果问题仍然存在，请将-concurrentDownloads参数与 Set-AksHciConfig 一起使用，并在重试安装之前将其设置为低于默认 10 的数字。 减少并发下载数可能有助于敏感网络成功完成大型文件下载。 此参数是预览功能。

部署后，重新启动 Azure 本地节点时，AKS 报告会显示计费失败状态。

要解决此问题，请按照说明手动轮换令牌并重启 KMS 插件。

运行 Install-AksHci 后，安装停止并显示以下错误消息：

\kubectl.exe --kubeconfig=C:\AksHci\0.9.7.3\kubeconfig-clustergroup-management 
get akshciclusters -o json returned a non zero exit code 1 
[Unable to connect to the server: dial tcp 192.168.0.150:6443: 
connectex: A connection attempt failed because the connected party 
did not properly respond after a period of time, or established connection 
failed because connected host has failed to respond.]

有多种原因导致安装可能失败并出现 waiting for API server 错误。

以下部分概述了此错误的可能原因和解决方案。

原因 1：如果 使用的是静态 IP 地址，并且收到以下错误消息，请确认 IP 地址和网关的配置是否正确。

Install-AksHci 
C:\AksHci\kvactl.exe create --configfile C:\AksHci\yaml\appliance.yaml  --outfile C:\AksHci\kubeconfig-clustergroup-management returned a non-zero exit code 1 [ ]

若要检查 IP 地址和网关是否配置正确，请运行以下命令：

ipconfig /all

在显示的配置设置中，确认配置。 还可以尝试 ping IP 网关和 DNS 服务器。

ping <DNS server>

如果这些方法不起作用，请使用 New-AksHciNetworkSetting 更改配置。

原因 2：如果 使用的是静态 IP 地址，请确认 DNS 服务器已正确配置。 若要检查主机的 DNS 服务器地址，请使用以下命令：

Get-NetIPConfiguration.DNSServer | ?{ $_.AddressFamily -ne 23} ).ServerAddresses

通过运行以下命令确认 DNS 服务器地址与运行 New-AksHciNetworkSetting 时使用的地址相同：

Get-MocConfig

如果 DNS 服务器配置不正确，请使用正确的 DNS 服务器重新安装 Azure 本地 AKS。 有关详细信息，请参阅 Azure 本地上的重启、删除或重新安装Azure Kubernetes 服务。

删除配置并使用新配置重启 VM 后，解决了此问题。

Install-AksHci 失败并出现此错误是因为另一个进程正在访问 mocstack.cab。

若要解决此问题，请关闭所有打开的 PowerShell 窗口，然后重新打开新的 PowerShell 窗口。

由于另一个进程正在使用该文件，因此无法进行访问。

可通过重启 PowerShell 会话来解决此问题。 关闭 PowerShell 窗口，然后再次尝试 Install-AksHci。

Install-AksHci 由于 Azure 本地配置的 AKS 中提供的 IP 池范围在 CIDR 中已关闭 1，并可能导致 CloudAgent 崩溃，因此失败。 例如，如果子网 10.0.0.0/21 的地址范围为 10.0.0.0-10.0.7.255，但你使用 10.0.0.1 作为起始地址，使用 10.0.7.254 作为结束地址，这将导致 CloudAgent 崩溃。

若要解决此问题，请运行 New-AksHciNetworkSetting，并为 VIP 池和 Kubernetes 节点池使用任何其他有效的 IP 地址范围。 请确保在地址范围的开头或末尾，所使用的值不会关闭 1。

在单节点安装上运行 Install-AksHci 时，安装运行正常，但在设置故障转移群集时，安装失败并出现错误消息。 但对云代理执行 ping 操作时又显示 CloudAgent 是可访问的。

若要确保所有节点都可以解析 CloudAgent 的 DNS，请在每个节点上运行以下命令：

Resolve-DnsName <FQDN of cloudagent>

在节点上成功执行上述步骤后，请确保节点可以访问 CloudAgent 端口，以验证代理是否未尝试阻止此连接，并且是否已打开端口。 若要进行此验证，请在每个节点上运行以下命令：

Test-NetConnection  <FQDN of cloudagent> -Port <Cloudagent port - default 65000>

此错误源于下载错误。

如果收到此错误，则应使用最新版本的 Microsoft Edge 或 Google Chrome，然后重试。

在 Azure 本地安装的 AKS 中运行 Set-AksHciRegistration 后，会出现此错误。 此错误表示没有为当前已登录的租户注册 Kubernetes 资源提供程序。

若要解决此问题，请执行以下 Azure CLI 或 PowerShell 步骤：

az provider register --namespace Microsoft.Kubernetes
az provider register --namespace Microsoft.KubernetesConfiguration

Register-AzResourceProvider -ProviderNamespace Microsoft.Kubernetes
Register-AzResourceProvider -ProviderNamespace Microsoft.KubernetesConfiguration

完成注册大约需要 10 分钟时间。 可以使用以下命令来监视注册过程。

az provider show -n Microsoft.Kubernetes -o table
az provider show -n Microsoft.KubernetesConfiguration -o table

Get-AzResourceProvider -ProviderNamespace Microsoft.Kubernetes
Get-AzResourceProvider -ProviderNamespace Microsoft.KubernetesConfiguration

Install-AksHci 在超时之前会在 Waiting for azure-arc-onboarding to complete 处挂起，但有以下前提条件：

• 服务主体用于 Azure 本地注册上的 AKS（Set-AksHciRegistration）。
• 安装了 Az.Accounts PowerShell 模块版本 (2.7.x)。

Az.Accounts 2.7.x 版本会 ServicePrincipalSecret 删除 Azure Local for Azure Arc 载入的 AKS 使用的 and CertificatePassword in PSAzureRmAccount。

重现步骤：

1. 安装 Az.Accounts PowerShell 模块版本 (>= 2.7.0)。
2. 使用服务主体的 Set-AksHciRegistration。
3. Install-AksHci。

预期行为：

1. Azure 本地安装的 AKS 挂起。Waiting for azure-arc-onboarding to complete
2. Azure-arc-onboarding pod 进入崩溃循环。
3. Azure-arc-onboarding Pod 错误，出现以下错误：
   Starting onboarding process ERROR: variable CLIENT_SECRET is required

若要解决此问题，请执行下列操作：

卸载 Az.Accounts 模块版本 2.7.x。运行以下 cmdlet：

Uninstall-Module -Name Az.Accounts -RequiredVersion 2.7.0 -Force

当 Azure 本地策略不足时，会发生此错误。 群集上的连接状态可能显示其已连接，但事件日志则显示警告消息：Azure Local's subscription is expired, run Sync-AzureStackHCI to renew the subscription。

若要解决此错误，请使用计算机上提供的 Get-AzureStackHCI PowerShell cmdlet 验证群集是否已注册到 Azure。 Windows Admin Center 面板也会显示群集的 Azure 注册状态信息。

如果群集已注册，则应在 Get-AzureStackHCI 的输出中查看 LastConnected 字段。 如果该字段显示 30 天以上，应尝试使用 Sync-AzureStackHCI cmdlet 来解决此问题。

还可使用以下 cmdlet 来验证群集的每个节点是否都具有所需的许可证：

Get-ClusterNode | % { Get-AzureStackHCISubscriptionStatus -ComputerName $_ }

Computer Name Subscription Name           Status   Valid To
------------- -----------------           ------   --------
MS-HCIv2-01   Azure Local             Active   12/23/2021 12:00:14 AM
MS-HCIv2-01   Windows Server Subscription Inactive

MS-HCIv2-02   Azure Local             Active   12/23/2021 12:00:14 AM
MS-HCIv2-02   Windows Server Subscription Inactive

MS-HCIv2-03   Azure Local             Active   12/23/2021 12:00:14 AM
MS-HCIv2-03   Windows Server Subscription Inactive

如果运行 Sync-AzureStackHCI cmdlet 后未解决此问题，应联系 Microsoft 支持部门。

发生此问题的原因是安装失败可能会导致必须清理的资源泄漏，然后才能再次安装。

如果使用 安装失败，应在再次运行 Install-AksHci 之前运行 Uninstall-AksHci。

在未运行 Set-AksHciConfig 的情况下运行Install-AksHci时，可以触发这些错误。

若要解决此错误，请运行 uninstall-akshci 并关闭所有 PowerShell 窗口。 打开新的 PowerShell 会话，并在 Azure 本地安装过程中重启 AKS，方法是 使用 PowerShell 在 Azure 本地安装 AKS。

Set-AksHciConfig PowerShell cmdlet 失败并出现错误：

GetCatalog error returned by API call: ... proxyconnect tcp: tls: first record does not look like a TLS Handshake

如果将 AKS 与代理服务器配合使用，则设置所需的 HTTPS 代理 URL 值时，可能使用了错误的 URL。 使用代理服务器配置 AKS 时，HTTP 代理 URL 和 HTTPS 代理 URL 值都是必需的，但通常需要这两个值来共享相同的 HTTP 前缀 URL。

如果环境中可能存在这种情况，请尝试执行以下缓解步骤：

1. 关闭 PowerShell 窗口并打开一个新窗口。
2. New-AksHciNetworkSetting再次运行 cmdletNew-AksHciProxySetting。 运行New-AksHciProxySetting时，请使用为其设置-http的相同 HTTP 前缀 URL 值设置-https参数。
3. 运行 Set-AksHciConfig 并继续。

在 Azure 本地部署 AKS 时，部署可能会在过程的不同点超时，具体取决于发生错误配置的位置。 应查看错误消息以确定原因及其发生位置。

例如，在以下错误中，发生错误配置的点为 Get-DownloadSdkRelease -Name "mocstack-stable"：

$vnet = New-AksHciNetworkSettingSet-AksHciConfig -vnet $vnetInstall-AksHciVERBOSE: 
Initializing environmentVERBOSE: [AksHci] Importing ConfigurationVERBOSE: 
[AksHci] Importing Configuration Completedpowershell : 
GetRelease - error returned by API call: 
Post "https://msk8s.api.cdp.microsoft.com/api/v1.1/contents/default/namespaces/default/names/mocstack-stable/versions/0.9.7.0/files?action=generateDownloadInfo&ForegroundPriority=True": 
dial tcp 52.184.220.11:443: connectex: 
A connection attempt failed because the connected party did not properly
respond after a period of time, or established connection failed because
connected host has failed to respond.At line:1 char:1+ powershell -command
{ Get-DownloadSdkRelease -Name "mocstack-stable"}

这表示物理 Azure 本地节点可以解析下载 URL 的名称， msk8s.api.cdp.microsoft.com但节点无法连接到目标服务器。

若要解决此问题，需要确定连接流中发生故障的位置。 下面是尝试从物理群集节点解决问题的一些步骤：

1. Ping 目标 DNS 名称：ping msk8s.api.cdp.microsoft.com。
2. 如果返回响应且没有超时，则基本网络路径将正常工作。
3. 如果连接超时，则数据路径中可能存在中断。 有关详细信息，请参阅 检查代理设置。 或者，返回路径中可能存在中断，因此应检查防火墙规则。

运行 Set-AksHciConfig 时，可能会遇到以下错误：

WinRM service is already running on this machine.
WinRM is already set up for remote management on this computer.
Powershell remoting to TK5-3WP08R0733 was not successful.
At C:\Program Files\WindowsPowerShell\Modules\Moc\0.2.23\Moc.psm1:2957 char:17
+ ...             throw "Powershell remoting to "+$env:computername+" was n ...
+                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : OperationStopped: (Powershell remo...not successful.:String) [], RuntimeException
    + FullyQualifiedErrorId : Powershell remoting to TK5-3WP08R0733 was not successful.

发生此错误是因为用户的安全令牌更改（由于组成员身份更改）、密码更改或密码过期。 在大多数情况下，可以通过从计算机注销并重新登录来修正此问题。 如果仍然失败，可以在 GitHub AKS Azure 本地问题中 提出问题。

Moc 代理应仅保留最后的 100 条代理日志。 它们应删除较旧的日志。 但日志轮换不会发生，并且日志会不断累积并消耗磁盘空间。

重现步骤：Install AksHci 并让群集启动并运行，直到代理日志数量超过 100 条。 创建第 n 条日志时，应删除第 n-100 条日志（如果存在）。

若要解决问题，请执行以下操作：

1. 修改云代理和节点代理的 logconf 文件。 云代理 logconfig 位于：
   (Get-MocConfig).cloudConfigLocation+"\log\logconf"。
   节点代理 logconfig 位于：
   (Get-MocConfig).cloudConfigLocation+"\log\logconf"。

2. 将“限制”的值更改为“100”，将“槽位数”更改为 100 并保存配置文件。

3. 重启云代理和节点代理以注册这些更改。

这些步骤仅在从代理重启生成了 100 条新日志后才开始进行日志轮换。 如果在重启时已有 n 条代理日志，则日志轮换将仅在生成了 n+ 100 条日志后才会开始。

使用 Set-AksHciConfig 指定路径名包含空格字符（例如 D:\Cloud Share\AKS HCI）的 -imageDir、-workingDir、-cloudConfigLocation 或 -nodeConfigLocation 参数时，云代理群集服务将无法启动，并显示以下（或类似）错误消息：

Failed to start the cloud agent generic cluster service in failover cluster. The cluster resource group os in the 'failed' state. Resources in 'failed' or 'pending' states: 'MOC Cloud Agent Service'

若要解决此问题，请使用不包含空格的路径，例如 C:\CloudShare\AKS-HCI。

如果基础结构配置不正确，可能就会出现此错误。

请使用以下步骤解决此错误：

1. 检查主机 DNS 服务器配置和网关设置：

   1. 确认正确配置了 DNS 服务器。 若要检查主机的 DNS 服务器地址，请运行以下命令：

      ((Get-NetIPConfiguration).DNSServer | ?{ $_.AddressFamily -ne 23}).ServerAddresses
      

   2. 若要检查 IP 地址和网关配置是否正确，请运行命令 ipconfig/all。
   3. 尝试对 IP 网关和 DNS 服务器执行 ping 操作。

2. 检查 CloudAgent 服务，确保该服务正在运行：

   1. 对 CloudAgent 服务执行 ping 操作，确保它可访问。
   2. 确保在每个节点上运行以下命令，确保所有节点都可以解析 CloudAgent 的 DNS：

      Resolve-DnsName <FQDN of cloudagent>
      

   3. 在节点上成功执行前述步骤后，请确保节点可以访问 CloudAgent 端口，以验证代理是否未尝试阻止此连接，并且是否已打开端口。 若要进行此验证，请在每个节点上运行以下命令：

      Test-NetConnection <FQDN of cloudagent> -Port <Cloudagent port - default 65000>
      

   4. 若要检查群集服务是否正在为故障转移群集运行，还可以运行以下命令：

      Get-ClusterGroup -Name (Get-AksHciConfig).Moc['clusterRoleName']
      

这通常表示表示Active Directory 域服务（AD DS）中表示基础故障转移群集的群集名称对象（CNO）无权在组织单位（OU）或群集所在的容器中创建虚拟计算机对象（VCO）。

如果你不是域管理员，可以要求他们 向 OU 授予 CNO 权限，或 为云代理通用群集服务预留 VCO。

如果你是域管理员，则 OU 或容器仍可能没有所需的权限。 例如，在 KB5008383 中引入的强制模式可能在 Active Directory 中启用。 尝试重新安装之前，请尝试以下操作。

1. 导航到Active Directory 用户和计算机。
2. 右键单击群集所在的 OU 或容器。
3. 选择 “委托控件...” 以打开 控制委派向导。
4. 单击“下一步>单击添加...”以打开“选择用户、计算机或组”窗口。
5. 选择要向其委派控件 > 的组或用户，单击“ 确定”。
6. 选择“创建自定义任务”以委托>“下一步”转到“Active Directory 对象类型”页。
7. 仅选择文件夹中>的以下对象“选择计算机对象>”选择此文件夹中的选定对象，并在此文件夹中>删除所选对象，单击“下一步”转到“权限”页。
8. 选择“创建所有子对象”并从权限>列表中选择“删除所有子对象”，单击“下一步>完成”

如果重新安装失败，请重试上述步骤 7 和步骤 8 的更改：

• 步骤 7：选择 此文件夹、此文件夹中的现有对象，并在此文件夹中> 创建新对象，单击“ 下一步”。
• 步骤 8：选择“读取”、“写入”、“创建所有子对象”，并从权限>列表中删除所有子对象，单击“下一>步单击完成”。

运行 Install-AksHci 时，可能会收到此错误。

可以通过运行 $error = Install-AksHci ，然后 $error[0].Exception.InnerException获取更多信息。

在创建 Kubernetes 节点之前，Aks-Hci PowerShell 命令不会验证主机服务器上的可用内存。 此问题可能会导致内存耗尽和虚拟机无法启动。 此失败当前未正常处理，部署将停止响应，不会显示明确的错误消息。

如果部署停止响应，请打开事件查看器并检查与 Hyper-V 相关的错误消息，指示没有足够的内存来启动 VM。

当你的 Azure 帐户中包含多个租户时，可能会出现此错误。

用于 $tenantId = (Get-AzContext).Tenant.Id 设置正确的租户。 然后，在运行 Set-AksHciRegistration 时将此租户作为参数包含在内。

尝试在 Azure VM 上部署 AKS 群集时，安装停滞在一起 Waiting for pod 'Cloud Operator' to be ready...，然后在两小时后失败并超时。 尝试通过检查网关和 DNS 服务器来排除故障，使其能够正常工作。 检查是否找不到 IP 或 MAC 地址冲突。 日志未显示 VIP 池。 使用会返回传输层安全性 (TLS) 超时，而不是“未授权”的 sudo docker pull ecpacr.azurecr.io/kube-vip:0.3.4 来拉取容器映像时，有一个限制。

若要解决此问题，请执行以下步骤：

1. 开始部署你的群集。
2. 部署群集后，通过 SSH 连接到管理群集 VM，如下所示：

ssh -i (Get-MocConfig)['sshPrivateKey'] clouduser@<IP Address>

3. 更改最大传输单位 (MTU) 设置。 毫不犹豫地做出改变：如果更改太晚，部署会失败。 修改 MTU 设置有助于取消阻止容器映像拉取。

sudo ifconfig eth0 mtu 1300

4. 若要查看容器的状态，请运行以下命令：

sudo docker ps -a

执行这些步骤后，应取消阻止容器映像拉取。

此错误表示云服务的 IP 地址不是群集网络的一部分，并且与启用了 client and cluster communication 角色的任何群集网络都不匹配。

若要解决此问题，请运行 Get-ClusterNetwork，其中 Role 等于 ClusterAndClient。 然后，在其中一个群集节点上，选择名称、地址和地址掩码，验证为 New-AksHciNetworkSetting 的 -cloudServiceIP 参数提供的 IP 地址是否与显示的其中一个网络匹配。

Enable-AksHciArcConnection 可以将 AKS 群集连接到 Azure，但当客户使用服务主体进行身份验证时，会显示以下警告：

WARNING: Error occurred while executing GetServicePrincipals
Code: Authorization_RequestDenied
Message: Insufficient privileges to complete the operation.
RequestId: <removed>
DateTimeStamp: <removed>
HttpStatusCode: Forbidden
HttpStatusDescription: Forbidden
HttpResponseStatus: Completed
WARNING: Custom locations has not been enabled on the AKS on Azure Local cluster. To enable custom locations manually, visit aka.ms/enable-custom-location

Arc 载入的当前行为是默认启用自定义位置。 若要启用自定义位置， GetServicePrincipals 操作在已登录 Azure 用户的上下文中执行。 如果用户（或 SPN）没有足够的权限才能执行此操作，该命令会发出警告，指出这些权限不存在，因此不会启用自定义位置功能。

如果不希望启用自定义位置，可以安全地忽略此警告，因为这不会影响群集加入 Arc。另一方面，如果需要启用自定义位置，则必须向用户（或 SPN）授予必要的权限。

后续步骤

• 疑难解答概述
• Windows Admin Center 已知问题
• 排查 Kubernetes 群集问题

如果在使用 AKS Arc 时继续遇到问题，可以通过 GitHub 提交 bug。