解决已启用 Azure Arc 的 Kubernetes 群集的平台问题

项目
01/08/2024

本文档提供了已启用 Azure Arc 的 Kubernetes 的连接性、权限和代理问题的故障排除指南。它还提供了 Azure GitOps 的故障排除指南，可用于已启用 Azure Arc 的 Kubernetes 或 Azure Kubernetes 服务 (AKS) 群集。

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.cn: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-agent Pod 是否显示 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-agent Pod 正在运行，但缺少 kube-aad-proxy Pod，请检查 Pod 安全策略。此 Pod 使用 azure-arc-kube-aad-proxy-sa 服务帐户，该帐户没有管理员权限，但需要拥有装载主机路径的权限。
如果 kube-aad-proxy Pod 处于 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.chinacloudapi.cn 启用了 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

后续步骤

直观地了解如何诊断连接问题。

通过