針對部署 AKS 叢集擴充功能時的錯誤進行疑難解答

發行項
11/20/2024

本文討論如何針對針對 Microsoft Azure Kubernetes Service （AKS）部署叢集擴充功能時發生的錯誤進行疑難解答。

擴充功能建立錯誤

錯誤：無法及時從代理程式取得回應

如果 Azure 服務未收到來自叢集擴充代理程式的回應，就會發生此錯誤。這種情況可能會發生，因為 AKS 叢集無法建立與 Azure 的連線。

原因 1：叢集擴充代理程式和管理員 Pod 未初始化

叢集擴充代理程式和管理員是負責管理 Kubernetes 應用程式生命週期的重要系統元件。叢集擴充代理程式和管理員 Pod 的初始化可能會因為下列問題而失敗：

資源限制
原則限制
節點污點，例如 NoSchedule

解決方案1：確定叢集延伸模組代理程式和管理員 Pod 正常運作

若要解決此問題，請確定叢集延伸模組代理程式和管理員 Pod 已正確排程且可以啟動。如果 Pod 停滯在未讀取狀態，請執行下列 kubectl describe pod 命令來檢查 Pod 描述，以取得基礎問題的詳細數據（例如，防止排程、記憶體不足或原則限制的污點）：

kubectl describe pod -n kube-system extension-operator-{id}

以下是命令輸出範例：

kube-system         extension-agent-55d4f4795f-sqx7q             2/2     Running   0          2d19h
kube-system         extension-operator-56c8d5f96c-nvt7x          2/2     Running   0          2d19h

針對 ARC 連線的叢集，請執行下列命令來檢查 Pod 描述：

kubectl describe pod -n azure-arc extension-manager-{id}

以下是命令輸出範例：

NAMESPACE         NAME                                          READY   STATUS             RESTARTS        AGE
azure-arc         cluster-metadata-operator-744f8bfbd4-7pssr    0/2     ImagePullBackOff   0               6d19h
azure-arc         clusterconnect-agent-7557d99d5c-rtgqh         0/3     ImagePullBackOff   0               6d19h
azure-arc         clusteridentityoperator-9b8b88f97-nr8hf       0/2     ImagePullBackOff   0               6d19h
azure-arc         config-agent-6d5fd59b8b-khw2d                 0/2     ImagePullBackOff   0               6d19h
azure-arc         controller-manager-5bc97f7db6-rt2zs           0/2     ImagePullBackOff   0               6d19h
azure-arc         extension-events-collector-7596688867-sqzv2   0/2     ImagePullBackOff   0               6d19h
azure-arc         extension-manager-86bbb949-6s59q              0/3     ImagePullBackOff   0               6d19h
azure-arc         flux-logs-agent-5f55888db9-wnr4c              0/1     ImagePullBackOff   0               6d19h
azure-arc         kube-aad-proxy-646c475dcc-92b86               0/2     ImagePullBackOff   0               6d19h
azure-arc         logcollector-5cbc659bfb-9v96d                 0/1     ImagePullBackOff   0               6d19h
azure-arc         metrics-agent-5794866b46-j9949                0/2     ImagePullBackOff   0               6d19h
azure-arc         resource-sync-agent-6cf4cf7486-flgwc          0/2     ImagePullBackOff   0               6d19h

當叢集擴充代理程式和管理員 Pod 運作正常且狀況良好時，他們會與 Azure 服務建立通訊，以安裝和管理 Kubernetes 應用程式。

原因 2：問題會影響輸出區塊或防火牆

如果叢集擴充代理程式和管理員 Pod 狀況良好，而且您仍然遇到「無法及時收到代理程式的回應」錯誤，則輸出區塊或防火牆問題可能已經存在。此問題可能會封鎖叢集擴充代理程式和管理員 Pod 與 Azure 通訊。

解決方案2：確定符合網路必要條件

若要解決此問題，請確定您遵循 Azure Kubernetes Service （AKS）叢集的輸出網路和 FQDN 規則中所述的網路必要條件。

原因 3：流量未獲授權

擴充代理程式嘗試呼叫 <region>.dp.kubernetesconfiguration.azure.com 數據平面服務端點失敗。此失敗會產生擴充代理程式 Pod 記錄中的「錯誤碼：403，訊息此流量未獲授權」專案。

kubectl logs -n kube-system extension-agent-<pod-guid>
{  "Message": "2024/02/07 06:04:43 \"Errorcode: 403, Message This traffic is not authorized., Target /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/provider/managedclusters/clusters/<cluster-name>/configurations/getPendingConfigs\"",  "LogType": "ConfigAgentTrace",  "LogLevel": "Information",  "Environment": "prod",  "Role": "ClusterConfigAgent",  "Location": "<region>,  "ArmId": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerService/managedclusters/<cluster-name>",  "CorrelationId": "",  "AgentName": "ConfigAgent",  "AgentVersion": "1.14.5",  "AgentTimestamp": "2024/02/07 06:04:43.672"  }
{  "Message": "2024/02/07 06:04:43 Failed to GET configurations with err : {\u003cnil\u003e}",  "LogType": "ConfigAgentTrace",  "LogLevel": "Information",  "Environment": "prod",  "Role": "ClusterConfigAgent",  "Location": "<region>",  "ArmId": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerService/managedclusters/<cluster-name>",  "CorrelationId": "",  "AgentName": "ConfigAgent",  "AgentVersion": "1.14.5",  "AgentTimestamp": "2024/02/07 06:04:43.672"  }

如果已啟用 Azure Arc 的 Kubernetes 的延伸模組數據平面中有預先存在的 PrivateLinkScope，且已啟用 Azure Arc 的 Kubernetes 與 AKS 受控叢集之間共用虛擬網路（或私人 DNS 伺服器），就會發生此錯誤。此網路設定會導致來自延伸模組數據平面的 AKS 輸出流量也透過相同的私人 IP 位址路由傳送，而不是透過公用 IP 位址路由傳送。

在 AKS 叢集中執行下列 nslookup 命令，以擷取數據平面端點所解析的特定私人 IP 位址：

PS D:\> kubectl exec -it -n kube-system extension-agent-<pod-guid> -- nslookup  <region>.dp.kubernetesconfiguration.azure.com
Non-authoritative answer:
<region>.dp.kubernetesconfiguration.azure.com        canonical name = <region>.privatelink.dp.kubernetesconfiguration.azure.com
Name:   <region>.privatelink.dp.kubernetesconfiguration.azure.com
Address: 10.224.1.184

當您在 Azure 入口網站中搜尋私人IP位址時，搜尋結果會指向確切的資源：虛擬網路、私人 DNS 區域、私人 DNS 伺服器等等。此資源具有針對已啟用 Azure Arc 的 Kubernetes 擴充功能數據平面所設定的私人端點。

解決方案 3.1：（建議）建立個別的虛擬網路

若要解決此問題，建議您為已啟用 Azure Arc 的 Kubernetes 和 AKS 計算建立個別的虛擬網路。

解決方案 3.2：建立 CoreDNS 覆寫

如果您的情況中不可能使用建議的解決方案，請為延伸模組數據平面端點建立 CoreDNS 覆寫，以透過公用網路。如需如何自定義 CoreDNS 的詳細資訊，請參閱<使用 Azure Kubernetes Service 自定義 CoreDNS>一節。

若要建立 CoreDNS 覆寫，請遵循下列步驟：

執行 nslookup 命令來尋找擴充數據平面端點的公用IP位址。請確定您根據 AKS 叢集的位置變更區域（例如 eastus2euap，）：

nslookup <region>.dp.kubernetesconfiguration.azure.com
Non-authoritative answer:
Name:    clusterconfig<region>.<region>.cloudapp.azure.com
Address:  20.39.12.229
Aliases:  <region>.dp.kubernetesconfiguration.azure.com
         <region>.privatelink.dp.kubernetesconfiguration.azure.com
         <region>.dp.kubernetesconfiguration.trafficmanager.net

建立現有 coreDNS 組態的備份：

kubectl get configmap -n kube-system coredns-custom -o yaml > coredns.backup.yaml

覆寫區域（例如， eastus2euap）資料平面端點與公用 IP 位址的對應。若要這樣做，請建立名為 corednsms.yaml 的 YAML 檔案，然後將下列範例組態複製到新檔案中。（請務必使用您環境的值來更新位址和主機名。

apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom      # This is the name of the configuration map that you can overwrite with your changes.
  namespace: kube-system
data:
  extensionsdp.override: |  # You can select any name here, but it must have the .override file name extension.
    hosts {
      20.39.12.229 <region>.dp.kubernetesconfiguration.azure.com
      fallthrough
    }

若要建立 ConfigMap，請執行 kubectl apply 命令，並指定 YAML 指令清單檔的名稱：
```
kubectl apply -f corednsms.yaml
```
若要重載 ConfigMap 並讓 Kubernetes 排程器在不停機的情況下重新啟動 CoreDNS，請執行 kubectl 推出重新啟動命令：
```
kubectl -n kube-system rollout restart deployment coredns
```

再次執行 nslookup 命令，以確定數據平面端點解析為提供的公用IP位址：

kubectl exec -it -n kube-system extension-agent-55d4f4795f-nld9q -- nslookup  [region].dp.kubernetesconfiguration.azure.com
Name:   <region>.dp.kubernetesconfiguration.azure.com
Address: 20.39.12.229

擴充代理程式 Pod 記錄不應再記錄「錯誤碼：403，訊息此流量未獲授權」錯誤專案。相反地，記錄應該包含「200」回應碼。

kubectl logs -n kube-system extension-agent-{id} 
{  "Message": "GET configurations returned response code {200}",  "LogType": "ConfigAgentTrace",  "LogLevel": "Information",  "Environment": "prod",  "Role": "ClusterConfigAgent",  "Location": "<region>",  "ArmId": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerService/managedclusters/<cluster-name>",  "CorrelationId": "",  "AgentName": "ConfigAgent",  "AgentVersion": "1.14.5"  }

錯誤：如果叢集中的所有節點集區都「CriticalAddonsOnly」受到污染，則無法排程擴充 Pod

發生此錯誤時，擴充代理程式記錄檔中會記錄下列專案：

擴充功能 Pod 錯誤：0/2 個節點可用：2 個節點有未降級的污點 {CriticalAddonsOnly： true}。先佔：有 0/2 個節點可用：2 先佔對排程沒有説明。

原因

當您嘗試在 AKS CriticalAddonsOnly 叢集上啟用已污染節點集區的擴充功能（例如分散式應用程式運行時間（DAPR）時，就會發生此錯誤。在此情況下，擴充 Pod 不會排程在任何節點上，因為這些污點沒有任何容忍。

若要檢視錯誤情況，請檢查擴充功能 Pod 以確認它們停滯在擱置狀態：

kubectl get po -n {namespace-name} -l app.kubernetes.io/name={name}

NAME                                   READY   STATUS    RESTARTS   AGE
{podname}                              0/2     Pending   0          2d6h

描述 Pod，以查看因為不支援的污點而無法排程它們：

kubectl describe po -n {namespace-name} {podname}

Events:
  Type     Reason            Age   From               Message
  ----     ------            ----  ----               -------
  Warning  FailedScheduling  18s   default-scheduler  0/2 nodes are available: 2 node(s) had untolerated taint {CriticalAddonsOnly: true}. preemption: 0/2 nodes are available: 2 Preemption is not helpful for scheduling.

注意

建議您不要在受污染的節點集區上安裝 CriticalAddOnsOnly 擴充功能，除非對應用程式工作負載執行此動作。
建議您不要在單一 CriticalAddOnsOnly 節點集區叢集上使用污點。如果您在只有一個節點集區的叢集中使用該污點，就無法在叢集中排程應用程式 Pod。請確定叢集中至少有一個節點集區沒有這個污點。如需何時應使用批注的詳細資訊 CriticalAddonsOnly ，請參閱在 Azure Kubernetes Service （AKS）中管理系統節點集區。

解決方案 1：將節點集區新增至叢集

若要解決此問題，請新增一個沒有 CriticalAddonsOnly 污點的節點集區。此動作會使擴充功能Pod排程在新節點集區上。

解決方案 2：移除 “CriticalAddonsOnly” 污點

如果可行且實用，您可以移除 CriticalAddonsOnly 污點，以便在叢集上安裝擴充功能。

Helm 錯誤

您可能會遇到下列任何 Helm 相關錯誤：

等候資源整備逾時
無法從存放庫 URL 下載 Helm 圖表
具有指定值的 Helm 圖表轉譯失敗
您的叢集中已存在資源
Helm 作業已在進行中

錯誤：等候資源整備的逾時

Kubernetes 應用程式的安裝失敗，並顯示下列錯誤訊息：

作業失敗：BackoffLimitExceeded

等候資源進入就緒/已完成狀態的逾時。

原因

此問題有下列常見原因：

資源限制：叢集中記憶體或CPU資源不足，可以防止Pod、作業或其他 Kubernetes 資源的成功初始化。最後，這種情況會導致安裝逾時。原則條件約束或節點污點（例如 NoSchedule）也可以封鎖資源初始化。
架構不符：嘗試在以 Windows 為基礎的節點上排程以 Linux 為基礎的應用程式，可能會導致 Kubernetes 資源初始化失敗。
不正確的組態設定：不正確的組態設定可防止 Pod 啟動。

解決方案

若要解決此問題，請遵循下列步驟：

檢查資源：請確定 Kubernetes 叢集有足夠的資源，而且節點允許 Pod 排程（您應該考慮污點）。確認記憶體和 CPU 資源符合需求。
檢查事件：檢查 Kubernetes 命名空間內的事件，以找出可能導致 Pod、作業或其他 Kubernetes 資源無法達到就緒狀態的潛在問題。
檢查 Helm 圖表和組態：許多 Kubernetes 應用程式會使用 Helm 圖表在叢集上部署資源。某些應用程式可能需要透過組態設定來輸入使用者。請確定所有提供的組態值都正確無誤，並符合安裝需求。

錯誤：無法從存放庫 URL 下載 Helm 圖表

除了輸出封鎖問題之外，叢集與防火牆之間發生連線問題，也會導致此錯誤。若要解決此問題，請參閱 Azure Kubernetes Service （AKS）叢集的輸出網路和 FQDN 規則。

錯誤：Helm 圖表轉譯失敗，並指定值

如果 Kubernetes 應用程式依賴 Helm 圖表在 Kubernetes 叢集中部署資源，就會發生此錯誤。這些應用程式可能需要透過安裝期間以 Helm 值的形式傳遞的組態設定所提供的使用者輸入。如果遺漏或不正確這些重要的組態設定，Helm 圖表可能無法轉譯。

若要解決此問題，請檢查擴充功能或應用程式檔，以判斷您是否省略任何必要值，或在應用程式安裝期間提供不正確的值。這些指導方針可協助您修正 Helm 圖表轉譯問題，因為設定值遺失或不正確。

錯誤：您的叢集中已存在資源

如果叢集中的 Kubernetes 資源與應用程式嘗試安裝的 Kubernetes 資源之間存在衝突，就會發生此錯誤。錯誤訊息通常會指定衝突資源的名稱。

如果衝突的資源很重要且無法取代，您可能無法安裝應用程式。如果資源不重要且可移除，請刪除衝突的資源，然後再試一次安裝。

錯誤：Helm 作業已在進行中

如果特定版本已有作業進行中，就會發生此錯誤。若要解決此問題，請等候 10 分鐘，然後重試作業。

與我們連絡，以取得說明

如果您有問題或需要相關協助，請建立支援要求，或詢問 Azure community 支援。您也可以向 Azure 意見反應社群提交產品意見反應。

共用方式為

針對部署 AKS 叢集擴充功能時的錯誤進行疑難解答

擴充功能建立錯誤

錯誤：無法及時從代理程式取得回應

原因 1：叢集擴充代理程式和管理員 Pod 未初始化

解決方案1：確定叢集延伸模組代理程式和管理員 Pod 正常運作

原因 2：問題會影響輸出區塊或防火牆

解決方案2：確定符合網路必要條件

原因 3：流量未獲授權

解決方案 3.1：（建議）建立個別的虛擬網路

解決方案 3.2：建立 CoreDNS 覆寫

錯誤：如果叢集中的所有節點集區都「CriticalAddonsOnly」受到污染，則無法排程擴充 Pod

原因

解決方案 1：將節點集區新增至叢集

解決方案 2：移除 “CriticalAddonsOnly” 污點

Helm 錯誤

錯誤：等候資源整備的逾時

原因

解決方案

錯誤：無法從存放庫 URL 下載 Helm 圖表

錯誤：Helm 圖表轉譯失敗，並指定值

錯誤：您的叢集中已存在資源

錯誤：Helm 作業已在進行中

與我們連絡，以取得說明

意見反應

其他資源

共用方式為

針對部署 AKS 叢集擴充功能時的錯誤進行疑難解答

擴充功能建立錯誤

錯誤：無法及時從代理程式取得回應

原因 1：叢集擴充代理程式和管理員 Pod 未初始化

解決方案1：確定叢集延伸模組代理程式和管理員 Pod 正常運作

原因 2：問題會影響輸出區塊或防火牆

解決方案2：確定符合網路必要條件

原因 3：流量未獲授權

解決方案 3.1：（建議） 建立個別的虛擬網路

解決方案 3.2：建立 CoreDNS 覆寫

錯誤：如果叢集中的所有節點集區都「CriticalAddonsOnly」受到污染，則無法排程擴充 Pod

原因

解決方案 1：將節點集區新增至叢集

解決方案 2：移除 “CriticalAddonsOnly” 污點

Helm 錯誤

錯誤：等候資源整備的逾時

原因

解決方案

錯誤：無法從存放庫 URL 下載 Helm 圖表

錯誤：Helm 圖表轉譯失敗，並指定值

錯誤：您的叢集中已存在資源

錯誤：Helm 作業已在進行中

與我們連絡，以取得說明

意見反應

其他資源

解決方案 3.1：（建議）建立個別的虛擬網路