共用方式為

針對已啟用 Azure Arc 的 Kubernetes 叢集平台問題進行疑難排解

  • 發行項

本文件提供已啟用 Azure Arc 的 Kubernetes 連線、權限和代理程式問題的疑難排解指南。 同時也提供 Azure GitOps 的疑難排解指南，您可用於已啟用 Azure Arc 的 Kubernetes 或 Azure Kubernetes Service (AKS) 叢集。

如需針對延伸模組相關問題進行疑難排解，例如 GitOps (Flux v2)、Azure 監視器容器深入解析、Open Service Mesh，請參閱針對已啟用 Azure Arc 的 Kubernetes 叢集延伸模組問題進行疑難排解。

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 connectedk8s connect之前執行az aks install-cli --install-location ~/.azure/kubectl-client/kubectl。 此命令會安裝 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 圖表版本，請嘗試再次將叢集連線至 Azure Arc。

若 Helm 圖表版本呈現 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 服務狀態。 如果是，請等到服務事件解決后，再刪除現有的已連線叢集資源之後，再試一次上線。 如果沒有服務事件，而且您在上線時仍會繼續遇到問題，請開啟支援要求，以便我們可以調查問題。

超額宣告錯誤

如果您收到超額宣告，請確定您的服務主體不屬於超過 200 個 Microsoft Entra 群組。 如果是這種情況，您必須建立並使用另一個不是超過 200 個群組成員的服務主體，或從部分群組中移除原始服務主體，然後再試一次。

如果您所設定的輸出 Proxy 環境不允許輸出流量的端點 https://<region>.obo.arc.azure.com:8084/，也可能發生超額宣告。

如果兩者都不適用，請開啟支援要求，以便我們調查問題。

將 Kubernetes 叢集連線至 Azure Arc 時發生問題

將叢集連線到 Azure Arc 需要 Azure 訂用帳戶的存取權，以及對目標叢集的 cluster-admin 存取權。 如果您無法連線到叢集或權限不足，將叢集連線到 Azure Arc 將會失敗。 請確保您已符合所有連線叢集的必要條件。

提示

如需疑難排解連線問題的視覺指南，請參閱診斷已啟用 Arc 的 Kubernetes 叢集的連線問題。

DNS 解析問題

如需叢集上 DNS 解析相關問題的說明，請參閱 偵錯 DNS 解析。

輸出網路連線問題

自叢集的輸出網路連線問題可能會因不同原因而發生。 首先，請確定已符合所有網路需求。

如果您遇到連線問題，且叢集位於輸出 Proxy 伺服器後方，請確定您在叢集上線期間傳遞 Proxy 參數，且 Proxy 已正確設定。 如需詳細資訊，請參閱使用輸出 Proxy 伺服器連線。

您可能看到類似以下的錯誤：

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

如果 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 代理程式。 如果叢集透過慢速網際網路連線執行，則代理程式的容器映像提取可能會比 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-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

  3. 如果 azure-identity-certificate 未出現，表示尚未安裝系統指派的受控識別。

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

    name: azure-identity-certificate

    為了解決此問題，請嘗試執行 az connectedk8s delete 命令並重新安裝，藉以刪除 Arc 部署。 若問題持續發生，Proxy 設定可能發生問題。 在此情況下，請嘗試透過 Poxy 將叢集連線至 Azure Arc以透過 Poxy 將叢集連線至 Arc。 此外，確認是否已符合所有網路需求。

  4. 如果 clusterconnect-agent 和 config-agent Pod 執行中，但 kube-aad-proxy 遺失，請檢查 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

叢集連線問題

若叢集位於輸出 Proxy 或防火牆後方，請確認 *.servicebus.windows.net 已啟用 Websocket 連線，這是叢集連線功能特定的必要項目。 此外，如果您在使用叢集連線時遇到問題，務必使用最新版的 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，且服務主體沒有必要的權限時，就會出現此警告。 若要避免此錯誤，請依照下列步驟執行：

  1. 使用使用者帳戶登入 Azure CLI。 擷取 Azure Arc 服務所使用的 Microsoft Entra 應用程式的物件識別碼：

    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

下一步