對 EKS 功能進行故障診斷

本主題提供 EKS 功能的一般故障診斷指引，包括功能運作狀態檢查、常見問題，以及功能特定故障診斷的連結。

注意

EKS 功能是完全受管的，並在叢集外部執行。您無法存取控制器日誌或控制器命名空間。故障診斷著重於功能運作狀態、資源狀態和組態。

一般疑難排解方法

疑難排解 EKS 功能時，請遵循下列一般方法：

1. 檢查功能運作狀態：使用 aws eks describe-capability 來檢視功能狀態和運作狀態問題

2. 驗證資源狀態：檢查您建立的狀態條件和事件的 Kubernetes 資源 CRDs)

3. 檢閱 IAM 許可：確保功能角色具有必要的許可

4. 檢查組態：驗證功能特定的組態是否正確

檢查功能運作狀態

所有 EKS 功能都透過 EKS 主控台和 describe-capability API 提供運作狀態資訊。

主控台：

1. 在以下網址開啟 Amazon EKS 主控台：https://console.aws.amazon.com/eks/home#/clusters。

2. 選取您的叢集名稱。

3. 選擇可觀測性索引標籤。

4. 選擇監控叢集。

5. 選擇功能索引標籤以檢視所有功能的運作狀態和狀態。

功能索引標籤會顯示：

• 功能名稱和類型

• 目前狀態

• 運作狀態問題，含描述

AWS CLI：

aws eks describe-capability \
  --region region-code \
  --cluster-name my-cluster \
  --capability-name my-capability-name

回應包括：

• 狀態：目前功能狀態 (CREATING、ACTIVE、UPDATING、DELETING、CREATE_FAILED) UPDATE_FAILED

• 運作狀態：運作狀態資訊，包括 功能偵測到的任何問題

常見功能狀態

CREATING：正在設定功能。

ACTIVE：功能正在執行並準備好使用。如果資源未如預期運作，請檢查資源狀態和 IAM 許可。

正在更新：正在套用組態變更。等待狀態傳回 ACTIVE。

CREATE_FAILED 或 UPDATE_FAILED：設定或更新發生錯誤。如需詳細資訊，請參閱運作狀態區段。常見原因：

• IAM 角色信任政策不正確或遺失

• IAM 角色不存在或無法存取

• 叢集存取問題

• 無效的組態參數

驗證 Kubernetes 資源狀態

EKS 功能會在叢集中建立和管理 Kubernetes 自訂資源定義 (CRDs)。疑難排解時，請檢查您建立的資源狀態：

# List resources of a specific type
kubectl get resource-kind -A

# Describe a specific resource to see conditions and events
kubectl describe resource-kind
         resource-name -n namespace

# View resource status conditions
kubectl get resource-kind
         resource-name -n namespace -o jsonpath='{.status.conditions}'

# View events related to the resource
kubectl get events --field-selector involvedObject.name=resource-name -n namespace
      

資源狀態條件提供下列相關資訊：

• 資源是否已就緒

• 遇到的任何錯誤

• 目前對帳狀態

檢閱 IAM 許可和叢集存取

許多功能問題來自 IAM 許可問題或缺少叢集存取組態。驗證功能角色許可和叢集存取項目。

檢查 IAM 角色許可

驗證功能角色具有必要的許可：

# List attached managed policies
aws iam list-attached-role-policies --role-name my-capability-role

# List inline policies
aws iam list-role-policies --role-name my-capability-role

# Get specific policy details
aws iam get-role-policy --role-name my-capability-role --policy-name policy-name

# View the role's trust policy
aws iam get-role --role-name my-capability-role --query 'Role.AssumeRolePolicyDocument'

信任政策必須允許capabilities.eks.amazonaws.com服務主體：

{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "capabilities.eks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

檢查 EKS 存取項目和存取政策

所有功能都需要其操作所在叢集上適當的 EKS 存取項目和存取政策。

驗證存取項目是否存在：

aws eks list-access-entries \
  --cluster-name my-cluster \
  --region region-code
         

在清單中尋找功能角色 ARN。如果遺失，則 功能無法存取叢集。

檢查連接到項目的存取政策：

aws eks list-associated-access-policies \
  --cluster-name my-cluster \
  --principal-arn arn:aws:iam::111122223333:role/my-capability-role \
  --region region-code
         

所有功能都需要適當的存取政策：

• ACK：需要許可才能建立和管理 Kubernetes 資源

• kro：需要建立和管理 Kubernetes 資源的許可

• Argo CD：需要建立和管理應用程式的許可，並且需要遠端目標叢集上的存取項目以進行多叢集部署

針對 Argo CD 多叢集部署：

如果部署到遠端叢集，請確認功能角色在每個目標叢集上有存取項目：

# Check Access Entry on target cluster
aws eks describe-access-entry \
  --cluster-name target-cluster \
  --principal-arn arn:aws:iam::111122223333:role/argocd-capability-role \
  --region region-code
         

如果目標叢集上缺少存取項目，Argo CD 就無法將應用程式部署到其中。如需組態詳細資訊註冊目標叢集，請參閱 。

功能特定的疑難排解

如需每種功能類型特有的詳細故障診斷指引：

• 對 ACK 功能的問題進行故障診斷 - 疑難排解 ACK 資源建立、IAM 許可和跨帳戶存取

• 對 Argo CD 功能的問題進行故障診斷 - 疑難排解應用程式同步、儲存庫身分驗證和多叢集部署

• 對 kro 功能的問題進行故障診斷 - 疑難排解 ResourceGraphDefinitions、CEL 表達式和 RBAC 許可

所有功能的常見問題

功能卡在 CREATING 狀態

如果功能保持 CREATING 狀態的時間超過預期：

1. 在主控台 (可觀測性 > 監控叢集 > 功能索引標籤） 或使用 CLI AWS 檢查功能運作狀態是否有特定問題：

   aws eks describe-capability \
     --region region-code \
     --cluster-name my-cluster \
     --capability-name my-capability-name \
     --query 'capability.health'

2. 驗證 IAM 角色是否存在，並具有正確的信任政策

3. 確保您的叢集可存取且運作狀態良好

4. 檢查是否有任何叢集層級的問題可能阻礙功能設定

未建立或更新的資源

如果功能是 ，ACTIVE但資源未建立或更新：

1. 檢查資源狀態是否有錯誤情況

2. 驗證特定 AWS 服務 (ACK) 或儲存庫 (Argo CD) 的 IAM 許可

3. 檢查建立基礎資源的 RBAC 許可 (kro)

4. 檢閱驗證錯誤的資源規格

功能運作狀態顯示問題

如果 describe-capability顯示運作狀態問題：

1. 仔細閱讀問題描述，通常指出特定問題

2. 解決根本原因 (IAM 許可、組態錯誤等）

3. 問題解決後，此功能會自動復原

後續步驟

• 使用 功能資源 - 管理功能資源

• 對 ACK 功能的問題進行故障診斷 - ACK 特定的疑難排解

• 對 Argo CD 功能的問題進行故障診斷 - Argo CD 特定疑難排解

• 對 kro 功能的問題進行故障診斷 - kro 特定疑難排解

• EKS 功能的安全考量 - 功能的安全最佳實務