**協助改進此頁面** 

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

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

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

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

**注意**  
EKS 功能是完全受管的，並在叢集外部執行。您無法直接存取控制器命名空間。故障診斷著重於功能運作狀態、資源狀態、組態和控制器日誌。您可以設定控制器日誌交付，以取得控制器行為的可見性。請參閱 [存取 EKS 功能控制器日誌](capabilities-controller-logs.md)。

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

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

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

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

1.  **檢閱控制器日誌**：如果已設定日誌交付，請查詢控制器日誌以取得錯誤和調校詳細資訊

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

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

## 使用控制器日誌進行故障診斷
<a name="_use_controller_logs_for_troubleshooting"></a>

如果您已設定控制器日誌交付 （請參閱[存取 EKS 功能控制器日誌](capabilities-controller-logs.md))，您可以查詢日誌以識別對帳錯誤、資源衝突和組態問題。

### 所有控制器的查詢錯誤
<a name="_query_errors_across_all_controllers"></a>

```
fields @timestamp, controller, message, error
| filter level = "error"
| sort @timestamp desc
| limit 50
```

### 篩選特定 ACK 服務控制器的日誌
<a name="_filter_logs_for_a_specific_ack_service_controller"></a>

使用 `controllerGroup` 欄位隔離日誌與特定 ACK 服務控制器：

```
fields @timestamp, message, error
| filter controllerGroup = "s3.services.k8s.aws"
| filter level = "error"
| sort @timestamp desc
```

若要依資源類型進一步篩選 （例如，僅限來自 EC2 控制器的`SecurityGroup`日誌）：

```
fields @timestamp, message, error
| filter controllerGroup = "ec2.services.k8s.aws"
| filter controllerKind = "SecurityGroup"
| sort @timestamp desc
| limit 100
```

### 篩選特定 Argo CD 應用程式的日誌
<a name="_filter_logs_for_a_specific_argo_cd_application"></a>

使用 `application` 欄位隔離特定 Argo CD 應用程式的日誌：

```
fields @timestamp, message, error
| filter application = "my-application"
| sort @timestamp desc
| limit 100
```

### 追蹤特定資源的對帳
<a name="_track_reconciliation_for_a_specific_resource"></a>

使用 `reconcileID` 欄位遵循單一調校週期：

```
fields @timestamp, level, message, error
| filter reconcileID = "your-reconcile-id"
| sort @timestamp asc
```

### 指出問題的常見日誌模式
<a name="_common_log_patterns_indicating_issues"></a>
+  **重複的對帳錯誤** — 控制器無法達到資源所需的狀態。檢查 `error` 欄位以取得詳細資訊，例如 IAM 許可失敗或資源組態無效。
+  **「協調程式錯誤」與 AWS API 錯誤** — 功能角色可能缺少特定 AWS 服務操作的許可。檢閱錯誤訊息並相應地更新 IAM 政策。
+  **資源沒有日誌項目 **- 如果您沒有看到預期控制器進行協調之資源的日誌，請確認該功能為 ，`ACTIVE`且該資源存在於該功能可存取的命名空間中。

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

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

 **主控台**：

1. 在以下網址開啟 Amazon EKS 主控台：https://console.aws.amazon.com/eks/home\#/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\_FAILED** 或 **UPDATE\_FAILED**：設定或更新發生錯誤。如需詳細資訊，請參閱運作狀態區段。常見原因：
+ 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) - 功能的安全最佳實務