Compartir a través de

排查启用了 Azure Arc 的 Kubernetes 群集的平台问题

本文提供有关启用 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

如果看到错误（如 cli.azext_connectedk8s.custom: Failed to download and install kubectl），请在尝试再次运行 az aks install-cli --install-location ~/.azure/kubectl-client/kubectl 之前运行 az connectedk8s connect。 此命令安装 kubectl 客户端，该客户端是使该命令工作所必需的。

Azure Arc 代理

启用 Azure Arc 的 Kubernetes 的所有 代理都部署在 azure-arc 命名空间中的 pod。 所有 Pod 都应该在运行并通过健康检查。

首先：验证 Azure Arc 的 Helm 图表发布。

$ 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

如果未找到或缺少 Helm Chart 版本，请尝试再次将群集连接到 Azure Arc。

如果存在 Helm Chart 发布版本 STATUS: deployed，请使用 kubectl -n azure-arc get deployments,pods 检查代理的状态：

$ 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 都应在 READY 列下将 STATUS 显示为 Running，并显示 3/3 或 2/2。 提取日志并描述返回 Error 或 CrashLoopBackOff 的 Pod。 如果任何 Pod 停滞在 Pending 状态，则表明群集节点上的资源可能不足。 纵向扩展群集可以使这些 Pod 转换为 Running 状态。

资源预配失败或服务超时错误

如果看到这些错误，请检查 Azure 状态以查看是否有任何活动事件影响已启用Azure Arc的 Kubernetes 服务的状态。 如果是这样，请等待服务事件得到解决，然后在 删除现有的已连接群集资源后再次尝试加入。 如果没有服务事件，并且你在载入时仍面临问题，打开支持请求以便Azure可以调查该问题。

超额索赔错误

如果收到超额声明，请确保服务主体不属于 200 多个Microsoft Entra组。 如果是，请创建和使用不是 200 多个组成员的另一个服务主体，或者从其中一些组中删除原始服务主体，然后重试。

如果配置的出站代理环境不允许出站流量至终结点 https://<region>.obo.arc.azure.cn:8084/ ，也可能发生流量超限申诉。

如果上述两个条件都不适用，打开支持请求，以便Azure可以调查问题。

将 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

当 mcr.microsoft.com 终结点被阻止时会发生此错误。 确保网络允许连接到此终结点并满足所有其他网络要求。

无法检索 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

如果 az connectedk8s connect 发生超时，且在将 OpenShift 群集连接到 Azure Arc 时连接失败：

  1. 确保 OpenShift 群集满足版本先决条件：4.5.41+、4.6.35+ 或 4.7.18+。

  2. 在运行 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。 要解决此问题，请尝试执行以下步骤：

  1. 运行以下命令：

    kubectl get pods -n azure-arc

  2. 检查clusterconnect-agent和config-agentPods是否显示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

  3. 如果azure-identity-certificate不存在，则未安装系统分配的托管身份。

    kubectl get secret -n azure-arc -o yaml | grep name:

    name: azure-identity-certificate

    若要解决此问题，请尝试通过运行以下命令 az connectedk8s delete 删除 Arc 部署，然后重新连接群集。 如果问题仍然存在，则可能是代理设置出现问题。 在这种情况下，尝试通过代理将群集连接到 Azure Arc，以通过代理连接您的群集到 Azure Arc。 此外，请验证是否满足所有 网络先决条件 。

  4. 如果 clusterconnect-agent 和 config-agent Pod 正在运行，但缺少 kube-aad-proxy Pod，请检查 Pod 安全策略。 此 Pod 使用 azure-arc-kube-aad-proxy-sa 服务帐户，该帐户没有管理员权限，但需要拥有装载主机路径的权限。

  5. 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 连接。 这种连接是专为 群集连接 功能所需的。 此外，如果在使用群集连接时遇到问题，请确保使用的是最新版本的 connectedk8s Azure CLI 扩展。

如果clusterconnect-agent和kube-aad-proxy两个 Pods 缺失，群集的连接功能很可能被禁用。 如果是这样， 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，并且服务主体没有必要的权限时，将显示此警告消息。 若要避免此错误，请执行以下步骤：

  1. 使用用户帐户登录到Azure CLI。 检索Azure Arc服务使用的Microsoft Entra应用程序的对象 ID：

    az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query objectId -o tsv

  2. 使用服务主体登录到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

后续步骤

  • Last updated on