**帮助改进此页面** 

要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 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 资源（CRD）

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

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

 **CREATE\_FAILED** 或 **UPDATE\_FAILED**：安装或更新遇到错误。有关详细信息，请查看“运行状况”部分。常见原因：
+ 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)：针对功能的安全最佳实践