你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
解决已启用 Azure Arc 的 Kubernetes 群集的平台问题
本文档提供了已启用 Azure Arc 的 Kubernetes 的连接性、权限和代理问题的故障排除指南。 它还提供了 Azure GitOps 的故障排除指南，可用于已启用 Azure Arc 的 Kubernetes 或 Azure Kubernetes 服务 (AKS) 群集。
若要帮助排查与扩展相关的问题，例如 GitOps (Flux v2)、Azure Monitor 容器见解、开放服务网格，请参阅排查已启用 Azure Arc 的 Kubernetes 群集的扩展问题。
Azure CLI
在使用 az connectedk8s 或 az k8s-configuration CLI 命令之前，请确保 Azure CLI 已设置为针对正确的 Azure 订阅工作。
az account set --subscription 'subscriptionId'
az account show
Azure Arc 代理
已启用 Azure Arc 的 Kubernetes 的所有代理在 azure-arc 命名空间中部署为 Pod。 所有 Pod 都应该在运行并传递它们的健康状况检查。
首先，请验证 Azure Arc Helm Chart 版本：
$ helm --namespace default status azure-arc
NAME: azure-arc
LAST DEPLOYED: Fri Apr 3 11:13:10 2020
NAMESPACE: default
STATUS: deployed
REVISION: 5
TEST SUITE: None
如果找不到或缺少 Chart Helm 版本，请再次尝试将群集连接到 Azure Arc。
如果 Helm Chart 版本存在且状态为 STATUS: deployed，请使用 kubectl 来检查代理状态：
$ kubectl -n azure-arc get deployments,pods
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/cluster-metadata-operator 1/1 1 1 3d19h
deployment.apps/clusterconnect-agent 1/1 1 1 3d19h
deployment.apps/clusteridentityoperator 1/1 1 1 3d19h
deployment.apps/config-agent 1/1 1 1 3d19h
deployment.apps/controller-manager 1/1 1 1 3d19h
deployment.apps/extension-events-collector 1/1 1 1 3d19h
deployment.apps/extension-manager 1/1 1 1 3d19h
deployment.apps/flux-logs-agent 1/1 1 1 3d19h
deployment.apps/kube-aad-proxy 1/1 1 1 3d19h
deployment.apps/metrics-agent 1/1 1 1 3d19h
deployment.apps/resource-sync-agent 1/1 1 1 3d19h
NAME READY STATUS RESTARTS AGE
pod/cluster-metadata-operator-74747b975-9phtz 2/2 Running 0 3d19h
pod/clusterconnect-agent-cf4c7849c-88fmf 3/3 Running 0 3d19h
pod/clusteridentityoperator-79bdfd945f-pt2rv 2/2 Running 0 3d19h
pod/config-agent-67bcb94b7c-d67t8 1/2 Running 0 3d19h
pod/controller-manager-559dd48b64-v6rmk 2/2 Running 0 3d19h
pod/extension-events-collector-85f4fbff69-55zmt 2/2 Running 0 3d19h
pod/extension-manager-7c7668446b-69gps 3/3 Running 0 3d19h
pod/flux-logs-agent-fc7c6c959-vgqvm 1/1 Running 0 3d19h
pod/kube-aad-proxy-84d668c44b-j457m 2/2 Running 0 3d19h
pod/metrics-agent-58fb8554df-5ll67 2/2 Running 0 3d19h
pod/resource-sync-agent-dbf5db848-c9lg8 2/2 Running 0 3d19h
所有 Pod 都应当将 STATUS 显示为 Running，并且 READY 列下为 3/3 或 2/2。 提取日志并描述返回 Error 或 CrashLoopBackOff 的 Pod。 如果任何 Pod 停滞在 Pending 状态，则表明群集节点上的资源可能不足。 纵向扩展群集可以使这些 Pod 转换为 Running 状态。
资源预配失败/服务超时错误
如果看到这些错误，请检查 Azure 状态，看看是否有任何活动事件影响已启用 Azure Arc 的 Kubernetes 服务的状态。 如果有，请等到服务事件得到解决，然后在删除现有连接的群集资源后再次尝试加入。 如果没有服务事件，并且在加入时仍然遇到问题，请提交支持票证，以便我们调查问题。
超额声明错误
如果收到超额声明，请确保你的服务主体所从属的 Microsoft Entra 组不超过 200 个。 否则，必须创建并使用所从属的组数不超过 200 个的另一个服务主体，或者从某些组中移除原始服务主体，然后重试。
如果你配置了出站代理环境而不允许终结点 https://<region>.obo.arc.azure.com:8084/ 用于出站流量，则也可能会出现超额声明。
如果不是这两种情况，请提交支持请求，以便我们调查问题。
将 Kubernetes 群集连接到 Azure Arc 时出现的问题
将群集连接到 Azure Arc 需要对 Azure 订阅的访问权限和对目标群集的 cluster-admin 访问权限。 如果无法访问群集或权限不足，那么将群集连接到 Azure Arc 将失败。 确保已满足所有连接群集的先决条件。
提示
有关解决连接问题的可视化指南，请参阅诊断已启用 Arc 的 Kubernetes 群集的连接问题。
DNS 解析问题
请访问调试 DNS 解析，帮助解决群集上的 DNS 解析问题。
出站网络连接问题
群集的出站网络连接问题可能因不同原因而产生。 首先确保满足所有网络要求。
如果遇到连接问题，并且群集位于出站代理服务器后面，请确保在加入群集期间传递了代理参数，并且正确配置了代理。 有关详细信息，请参阅使用出站代理服务器进行连接。
可能会出现如下错误：
An exception has occurred while trying to execute the cluster diagnostic checks in the cluster. Exception: Unable to pull cluster-diagnostic-checks helm chart from the registry 'mcr.microsoft.com/azurearck8s/helmchart/stable/clusterdiagnosticchecks:0.1.2': Error: failed to do request: Head "https://mcr.microsoft.com/v2/azurearck8s/helmchart/stable/clusterdiagnosticchecks/manifests/0.1.2": dial tcp xx.xx.xx.219:443: i/o timeout
当 https://k8connecthelm.azureedge.net 终结点被阻止时会发生此错误。 确保网络允许连接到此终结点并满足所有其他网络要求。
无法检索 MSI 证书
检索 MSI 证书时出现问题通常是由网络问题引起的。 检查以确保满足所有网络要求，然后重试。
群集权限不足
如果提供的 kubeconfig 文件没有足够的权限来安装 Azure Arc 代理，则 Azure CLI 命令将返回错误：Error: list: failed to list: secrets is forbidden: User "myuser" cannot list resource "secrets" in API group "" at the cluster scope
要解决此问题，请确保将群集连接到 Azure Arc 的用户已分配有 cluster-admin 角色。
无法将 OpenShift 群集连接到 Azure Arc
如果在将 OpenShift 群集连接到 Azure Arc 时 az connectedk8s connect 超时并失败：
确保 OpenShift 群集满足版本先决条件：4.5.41+、4.6.35+ 或 4.7.18+。
在运行
az connectedk8s connnect之前，请在群集上运行以下命令：oc adm policy add-scc-to-user privileged system:serviceaccount:azure-arc:azure-arc-kube-aad-proxy-sa
安装超时
将 Kubernetes 群集连接到已启用 Azure Arc 的 Kubernetes 需要在群集上安装 Azure Arc 代理。 如果该群集通过网速缓慢的 Internet 连接运行，则代理的容器映像拉取可能会需要比 Azure CLI 超时更长的时间。
Helm 超时错误
可能会出现错误 Unable to install helm release: Error: UPGRADE Failed: time out waiting for the condition。 要解决此问题，请尝试执行以下步骤：
运行以下命令：
kubectl get pods -n azure-arc检查
clusterconnect-agent或config-agentPod 是否显示crashloopbackoff，或者是否并非所有容器都在运行：NAME READY STATUS RESTARTS AGE cluster-metadata-operator-664bc5f4d-chgkl 2/2 Running 0 4m14s clusterconnect-agent-7cb8b565c7-wklsh 2/3 CrashLoopBackOff 0 1m15s clusteridentityoperator-76d645d8bf-5qx5c 2/2 Running 0 4m15s config-agent-65d5df564f-lffqm 1/2 CrashLoopBackOff 0 1m14s如果
azure-identity-certificate不存在，则系统分配的托管标识未安装。kubectl get secret -n azure-arc -o yaml | grep name:name: azure-identity-certificate要解决此问题，可以通过运行
az connectedk8s delete命令并重新安装来尝试删除 Arc 部署。 如果问题仍然存在，则可能是代理设置问题。 在这种情况下，请尝试通过代理将群集连接到 Azure Arc，通过代理将群集连接到 Arc。 另请验证是否满足所有网络先决条件。如果
clusterconnect-agent和config-agentPod 正在运行，但缺少kube-aad-proxyPod，请检查 Pod 安全策略。 此 Pod 使用azure-arc-kube-aad-proxy-sa服务帐户，该帐户没有管理员权限，但需要拥有装载主机路径的权限。如果
kube-aad-proxyPod 处于ContainerCreating状态，请检查 kube-aad-proxy 证书是否已下载到群集中。kubectl get secret -n azure-arc -o yaml | grep name:name: kube-aad-proxy-certificate
CryptoHash 模块错误
尝试将 Kubernetes 群集加入 Azure Arc 平台时，本地环境（例如客户端控制台）可能会返回以下错误消息：
Cannot load native module 'Crypto.Hash._MD5'
有时，在通过 Azure CLI 或 Azure PowerShell 添加扩展 connectedk8s 和 k8s-configuration 时，依赖模块无法成功下载。 若要解决此问题，请在本地环境中手动删除再重新添加这些扩展。
若要删除扩展，请使用：
az extension remove --name connectedk8s
az extension remove --name k8s-configuration
若要添加扩展，请使用：
az extension add --name connectedk8s
az extension add --name k8s-configuration
群集连接问题
如果群集位于出站代理或防火墙后面，请验证是否为 *.servicebus.windows.net 启用了 websocket 连接，只有这样才能支持 Cluster Connect 功能。 此外，如果在使用群集连接时遇到问题，请确保你使用的是最新版本的 connectedk8s Azure CLI 扩展。
如果缺少 clusterconnect-agent 和 kube-aad-proxy Pod，则群集上的群集连接功能可能已禁用。 如果是这样，az connectedk8s proxy 无法与群集建立会话，读取 Cannot connect to the hybrid connection because no agent is connected in the target arc resource. 时可能会出错
若要解决此错误，请在群集上启用群集连接功能：
az connectedk8s enable-features --features cluster-connect -n $CLUSTER_NAME -g $RESOURCE_GROUP
有关详细信息，请参阅使用群集连接安全连接到已启用 Azure Arc 的 Kubernetes 群集。
使用服务主体启用自定义位置
将群集连接到 Azure Arc 或在现有群集上启用自定义位置时，可能会看到以下警告：
Unable to fetch oid of 'custom-locations' app. Proceeding without enabling the feature. Insufficient privileges to complete the operation.
使用服务主体登录 Azure，并且该服务主体没有必要的权限时，会出现此警告。 若要避免此错误，请执行以下步骤：
使用用户帐户登录到 Azure CLI。 接收 Azure Arc 服务使用的 Microsoft Entra 应用程序的对象 ID：
az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query objectId -o tsv使用服务主体登录到 Azure CLI。 使用上面步骤中的
<objectId>值在群集上启用自定义位置：- 若要在将群集连接到 Arc 时启用自定义位置，请运行
az connectedk8s connect -n <cluster-name> -g <resource-group-name> --custom-locations-oid <objectId> - 若要在已启用 Azure Arc 的现有 Kubernetes 群集上启用自定义位置，请运行
az connectedk8s enable-features -n <cluster-name> -g <resource-group-name> --custom-locations-oid <objectId> --features cluster-connect custom-locations
- 若要在将群集连接到 Arc 时启用自定义位置，请运行
后续步骤
- 直观地了解如何诊断连接问题。
- 查看与群集扩展相关的故障排除提示。