**協助改進此頁面** 

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

若要為本使用者指南貢獻內容，請點選每個頁面右側面板中的**在 GitHub 上編輯此頁面**連結。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 對 EKS 功能進行故障診斷
<a name="capabilities-troubleshooting"></a>

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

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

## 一般疑難排解方法
<a name="_general_troubleshooting_approach"></a>

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

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

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

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

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

## 檢查功能運作狀態
<a name="_check_capability_health"></a>

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

 **主控台**：

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

1. 選取您的叢集名稱。

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

1. 選擇**監控叢集**。

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

功能索引標籤會顯示：
+ 功能名稱和類型
+ 目前狀態
+ 運作狀態問題，含描述

 ** 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`
+  **運作**狀態：運作狀態資訊，包括 功能偵測到的任何問題

## 常見功能狀態
<a name="_common_capability_statuses"></a>

 **CREATING**：正在設定功能。

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

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

 **CREATE\$1FAILED** 或 **UPDATE\$1FAILED**：設定或更新發生錯誤。如需詳細資訊，請參閱運作狀態區段。常見原因：
+ IAM 角色信任政策不正確或遺失
+ IAM 角色不存在或無法存取
+ 叢集存取問題
+ 無效的組態參數

## 驗證 Kubernetes 資源狀態
<a name="_verify_kubernetes_resource_status"></a>

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 許可和叢集存取
<a name="_review_iam_permissions_and_cluster_access"></a>

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

### 檢查 IAM 角色許可
<a name="_check_iam_role_permissions"></a>

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

```
# 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 存取項目和存取政策
<a name="_check_eks_access_entries_and_access_policies"></a>

所有功能都需要其操作所在叢集上適當的 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 就無法將應用程式部署到其中。如需組態詳細資訊[註冊目標叢集](argocd-register-clusters.md)，請參閱 。

## 功能特定的疑難排解
<a name="_capability_specific_troubleshooting"></a>

如需每個功能類型特有的詳細故障診斷指引：
+  [對 ACK 功能的問題進行故障診斷](ack-troubleshooting.md) - 疑難排解 ACK 資源建立、IAM 許可和跨帳戶存取
+  [對 Argo CD 功能的問題進行故障診斷](argocd-troubleshooting.md) - 疑難排解應用程式同步、儲存庫身分驗證和多叢集部署
+  [對 kro 功能的問題進行故障診斷](kro-troubleshooting.md) - 疑難排解 ResourceGraphDefinitions、CEL 表達式和 RBAC 許可

## 所有功能的常見問題
<a name="_common_issues_across_all_capabilities"></a>

### 功能卡在 CREATING 狀態
<a name="_capability_stuck_in_creating_state"></a>

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

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

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

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

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

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

### 未建立或更新的資源
<a name="_resources_not_being_created_or_updated"></a>

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

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

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

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

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

### 功能運作狀態顯示問題
<a name="_capability_health_shows_issues"></a>

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

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

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

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

## 後續步驟
<a name="_next_steps"></a>
+  [使用 功能資源](working-with-capabilities.md) - 管理功能資源
+  [對 ACK 功能的問題進行故障診斷](ack-troubleshooting.md) - ACK 特定的疑難排解
+  [對 Argo CD 功能的問題進行故障診斷](argocd-troubleshooting.md) - Argo CD 特定疑難排解
+  [對 kro 功能的問題進行故障診斷](kro-troubleshooting.md) - kro 特定疑難排解
+  [EKS 功能的安全考量](capabilities-security.md) - 功能的安全最佳實務