**帮助改进此页面** 

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

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

本主题将提供针对适用于 ACK 的 EKS 功能的问题排查指南，包括功能运行状况检查、资源状态验证和 IAM 权限问题。

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

## 功能处于活动状态，但无法创建资源
<a name="_capability_is_active_but_resources_arent_being_created"></a>

如果 ACK 功能显示为 `ACTIVE` 状态但无法在 Amazon 中创建资源，请检查功能运行状况、资源状态和 IAM 权限。

 **检查功能运行状况**：

您可以在 EKS 控制台或使用 Amazon CLI 查看功能运行状况和状态问题。

 **控制台**：

1. 从以下位置打开 Amazon EKS 控制台：https://console.aws.amazon.com/eks/home\$1/clusters。

1. 选择集群名称。

1. 选择**可观测性**选项卡。

1. 选择**监控集群**。

1. 选择**功能**选项卡，查看所有功能的运行状况和状态。

 **Amazon CLI**：

```
# View capability status and health
aws eks describe-capability \
  --region region-code \
  --cluster-name my-cluster \
  --capability-name my-ack

# Look for issues in the health section
```

 **常见原因：**
+  **缺少 IAM 权限**：功能角色缺少 Amazon 服务权限
+  **命名空间错误**：在未配置正确 IAMRoleSelector 的命名空间中创建了资源
+  **资源规范无效**：检查资源状态条件是否存在验证错误
+  **API 节流**：达到了 Amazon API 速率限制
+  **准入 Webhook**：准入 Webhook 阻止了控制器修补资源状态

 **检查资源状态**：

```
# Describe the resource to see conditions and events
kubectl describe bucket my-bucket -n default

# Look for status conditions
kubectl get bucket my-bucket -n default -o jsonpath='{.status.conditions}'

# View resource events
kubectl get events --field-selector involvedObject.name=my-bucket -n default
```

 **验证 IAM 权限**：

```
# View the Capability Role's policies
aws iam list-attached-role-policies --role-name my-ack-capability-role
aws iam list-role-policies --role-name my-ack-capability-role

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

## 资源已在 Amazon 中创建，但未在 Kubernetes 中显示
<a name="resources_created_in_shared_aws_but_not_showing_in_kubernetes"></a>

ACK 仅跟踪通过 Kubernetes 清单创建的资源。要使用 ACK 管理现有 Amazon 资源，请使用接管功能。

```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: existing-bucket
  annotations:
    services.k8s.aws/adoption-policy: "adopt-or-create"
spec:
  name: my-existing-bucket-name
```

有关资源接管的更多信息，请参阅 [ACK 概念](ack-concepts.md)。

## 无法创建跨账户资源
<a name="_cross_account_resources_not_being_created"></a>

如果使用 IAM 角色选择器时，无法在目标 Amazon 账户中创建资源，请验证信任关系和 IAMRoleSelector 配置。

 **验证信任关系**：

```
# Check the trust policy in the target account role
aws iam get-role --role-name cross-account-ack-role --query 'Role.AssumeRolePolicyDocument'
```

信任策略必须允许源账户的功能角色代入它。

 **确认 IAMRoleSelector 配置**：

```
# List IAMRoleSelectors (cluster-scoped)
kubectl get iamroleselector

# Describe specific selector
kubectl describe iamroleselector my-selector
```

 **验证命名空间对应关系**：

IAMRoleSelectors 是集群范围内的资源，但针对特定的命名空间。请确保 ACK 资源位于与 IAMRoleSelector 的命名空间选择器匹配的命名空间：

```
# Check resource namespace
kubectl get bucket my-cross-account-bucket -n production

# List all IAMRoleSelectors (cluster-scoped)
kubectl get iamroleselector

# Check which namespace the selector targets
kubectl get iamroleselector my-selector -o jsonpath='{.spec.namespaceSelector}'
```

 **检查 IAMRoleSelected 条件**：

通过检查 `ACK.IAMRoleSelected` 条件，验证 IAMRoleSelector 是否已与资源成功匹配：

```
# Check if IAMRoleSelector was matched
kubectl get bucket my-cross-account-bucket -n production -o jsonpath='{.status.conditions[?(@.type=="ACK.IAMRoleSelected")]}'
```

如果条件为 `False` 或缺失，则说明 IAMRoleSelector 的命名空间选择器与资源所在的命名空间不匹配。验证选择器的 `namespaceSelector` 是否与资源的命名空间标签匹配。

 **检查功能角色权限**：

功能角色需要目标账户角色的 `sts:AssumeRole` 和 `sts:TagSession` 权限：

```
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["sts:AssumeRole", "sts:TagSession"],
      "Resource": "arn:aws:iam::[.replaceable]`444455556666`:role/[.replaceable]`cross-account-ack-role`"
    }
  ]
}
```

有关跨账户配置的详细信息，请参阅[配置 ACK 权限](ack-permissions.md)。

## 后续步骤
<a name="_next_steps"></a>
+  [针对 EKS 的 ACK 注意事项](ack-considerations.md)：ACK 注意事项和最佳实践
+  [配置 ACK 权限](ack-permissions.md)：配置 IAM 权限和多账户模式
+  [ACK 概念](ack-concepts.md)：了解 ACK 概念和资源生命周期
+  [EKS 功能问题排查](capabilities-troubleshooting.md)：一般功能问题排查指导