**帮助改进此页面** 

要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 GitHub 上编辑此页面**链接。

# EKS 功能问题排查
<a name="capabilities-troubleshooting"></a>

本主题提供了 EKS 功能的一般问题排查指南，包括功能运行状况检查、常见问题以及功能特定的问题排查链接。

**注意**  
EKS 功能完全托管，可在您的集群之外运行。您无权访问控制器日志或控制器命名空间。问题排查侧重于功能运行状况、资源状态和配置。

## 一般问题排查方法
<a name="_general_troubleshooting_approach"></a>

对 EKS 功能进行问题排查时，请遵循以下一般方法：

1.  **检查功能运行状况**：使用 `aws eks describe-capability` 查看功能状态和运行状况问题

1.  **验证资源状态**：检查您为状态条件和事件创建的 Kubernetes 资源（CRD）

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 权限。

 **UPDATING**：正在应用配置更改。等待状态恢复为 `ACTIVE`。

 **CREATE\$1FAILED** 或 **UPDATE\$1FAILED**：安装或更新遇到错误。有关详细信息，请查看“运行状况”部分。常见原因：
+ IAM 角色信任策略不正确或缺失
+ IAM 角色不存在或无法访问
+ 集群访问权限问题
+ 无效的配置参数

## 验证 Kubernetes 资源状态
<a name="_verify_kubernetes_resource_status"></a>

EKS 功能在您的集群中创建并管理 Kubernetes 自定义资源定义（CRD）。进行问题排查时，请检查您创建的资源的状态：

```
# 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. 可在控制台（**可观测性** > **监控集群** > **功能**选项卡）中或使用 AWS CLI 检查功能运行状况，了解特定问题：

   ```
   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)：针对功能的安全最佳实践