解决 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 Stack HCI 上的 AKS 时违反了 Azure Policy，则可能会发生此错误。

若要解决此问题，请阅读错误消息，了解 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 Stack HCI 节点时，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 Stack HCI 上的 AKS。 有关详细信息，请参阅 Azure Stack HCI 上的重启、删除或重新安装Azure Kubernetes 服务。

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

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

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

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

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

Install-AksHci 由于 Azure Stack HCI 上的 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 Stack HCI 上的 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 Stack HCI 上的 AKS 注册 (Set-AksHciRegistration) 中使用了服务主体。
• 安装了 Az.Accounts PowerShell 模块版本 (2.7.x)。

Az.Accounts 2.7.x 版本删除了 PSAzureRmAccount 中的 ServicePrincipalSecret 和 CertificatePassword，但 Azure Stack HCI 上的 AKS 需要使用它才能加入 Azure Arc。

重现步骤：

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

预期行为：

1. Azure Stack HCI 上的 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 Stack HCI 违反策略时，会出现此错误。 群集上的连接状态可能显示其已连接，但事件日志则显示警告消息：Azure Stack HCI'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 Stack HCI             Active   12/23/2021 12:00:14 AM
MS-HCIv2-01   Windows Server Subscription Inactive

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

MS-HCIv2-03   Azure Stack HCI             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 会话，并按照使用 PowerShell 安装 AKS-HCI 中的说明，重新启动 AKS-HCI 安装过程。

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 Stack HCI 上部署 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 Stack HCI 节点可以解析下载 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 HCI 问题中 提出问题。

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-HCI 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。