**帮助改进此页面** 

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

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

本主题旨在介绍 EKS 托管型 kro 问题排查指引，内容涵盖功能运行状况检查、RBAC 权限、CEL 表达式错误以及资源组合编排问题。

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

## 功能状态显示为 ACTIVE，但 ResourceGraphDefinition 无法正常工作
<a name="_capability_is_active_but_resourcegraphdefinitions_arent_working"></a>

若 kro 功能状态显示为 `ACTIVE`，但 ResourceGraphDefinition 无法创建底层资源，请检查功能运行状况、RBAC 权限以及资源状态。

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

您可以在 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-kro

# Look for issues in the health section
```

 **常见原因：**
+  **RBAC 权限缺失**：kro 缺少创建底层 Kubernetes 资源的权限
+  **CEL 表达式无效**：ResourceGraphDefinition 中存在语法错误
+  **资源依赖异常**：被依赖的资源未处于就绪状态
+  **模式验证失败**：实例不符合 RGD 模式要求

 **验证 RBAC 权限**：

```
# Check if capability has cluster admin policy
kubectl get accessentry -A | grep kro
```

若该功能不具备所需权限，可将 `AmazonEKSClusterAdminPolicy` 关联到 kro 功能的访问条目；对于生产环境，也可创建权限范围更严格的 RBAC 策略。有关详细信息，请参阅 [配置 kro 权限](kro-permissions.md)。

 **检查 ResourceGraphDefinition 状态**：

```
# List all RGDs
kubectl get resourcegraphdefinition

# Describe specific RGD
kubectl describe resourcegraphdefinition my-rgd

# Check for validation errors
kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.conditions}'
```

ResourceGraphDefinition 包含三项关键状态条件：
+  `ResourceGraphAccepted`：RGD 是否通过验证（CEL 语法、类型校验、字段存在性验证）
+  `KindReady`：自定义 API 对应的 CRD 是否已生成并完成注册
+  `ControllerReady`：kro 是否正在主动监听自定义 API 的实例

若 `ResourceGraphAccepted` 状态为 `False`，请查看状态条件信息，排查是否存在未知字段、类型不匹配或循环依赖等验证类错误。

## 已创建实例但未生成底层资源
<a name="_instances_created_but_underlying_resources_not_appearing"></a>

若自定义资源实例已存在，但对应的底层 Kubernetes 资源（如 Deployment、Service、ConfigMap）未被创建，请验证 kro 是否具备相应权限，同时排查资源组合编排错误。

 **检查实例状态**：

```
# Describe the instance (replace with your custom resource kind and name)
kubectl describe custom-kind
         my-instance

# View instance events
kubectl get events --field-selector involvedObject.name=my-instance

# Check instance status conditions
kubectl get custom-kind
         my-instance -o jsonpath='{.status.conditions}'

# Check instance state
kubectl get custom-kind
         my-instance -o jsonpath='{.status.state}'
```

实例包含一个 `state` 字段，用于展示其宏观状态：
+  `ACTIVE`：实例已成功运行
+  `IN_PROGRESS`：实例正被处理或协调
+  `FAILED`：实例协调失败
+  `DELETING`：实例正被删除
+  `ERROR`：处理过程中发生错误

实例同时包含四项状态条件：
+  `InstanceManaged`：终结器与标签已正确配置
+  `GraphResolved`：运行时依赖图已创建，且相关资源已完成解析
+  `ResourcesReady`：所有资源均已创建并处于就绪状态
+  `Ready`：实例的整体运行状况（仅当所有子条件均为 `True` 时，该状态才会变为 `True`）

可重点关注 `Ready` 条件来判断实例的运行状况。若 `Ready` 状态为 `False`，请检查各子条件，明确是哪个阶段执行失败。

 **验证 RBAC 权限**：

kro 功能需要具备创建 ResourceGraphDefinition 中所定义的底层 Kubernetes 资源的权限。

```
# Check if the capability has the AmazonEKSClusterAdminPolicy
kubectl get accessentry -A | grep kro
```

若存在权限缺失，可将 `AmazonEKSClusterAdminPolicy` 关联到 kro 功能的访问条目；对于生产环境，则建议创建权限范围更严格的 RBAC 策略。有关详细信息，请参阅 [配置 kro 权限](kro-permissions.md)。

## CEL 表达式错误
<a name="_cel_expression_errors"></a>

CEL 表达式错误会在 ResourceGraphDefinition 创建阶段被捕获，而非在实例创建阶段。当您创建 RGD 时，kro 会对所有 CEL 语法进行验证、基于 Kubernetes 模式对表达式进行类型检查，同时验证字段是否存在。

 **常见 CEL 验证错误**：
+  **未定义字段引用**：引用了模式或资源中不存在的字段
+  **类型不匹配**：表达式返回的类型不符合预期（例如：预期为整数类型，实际返回字符串类型）
+  **语法无效**：CEL 表达式中存在缺失括号、引号或运算符的情况
+  **未知资源类型**：引用了集群中未存在的 CRD

 **检查 RGD 验证状态**：

```
# Check if RGD was accepted
kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.conditions[?(@.type=="ResourceGraphAccepted")]}'

# View detailed validation errors
kubectl describe resourcegraphdefinition my-rgd
```

若 `ResourceGraphAccepted` 状态为 `False`，对应的条件信息中会包含具体的验证错误信息。

 **有效的 CEL 表达式示例**：

```
# Reference schema field
${schema.spec.appName}

# Conditional expression
${schema.spec.replicas > 1}

# String template (expressions must return strings)
name: "${schema.spec.appName}-service"

# Standalone expression (can be any type)
replicas: ${schema.spec.replicaCount}

# Resource reference
${deployment.status.availableReplicas}

# Optional field access (returns null if field doesn't exist)
${configmap.data.?DATABASE_URL}
```

## 资源依赖关系无法解析
<a name="_resource_dependencies_not_resolving"></a>

kro 会从 CEL 表达式中自动推导资源依赖关系，并按正确顺序创建资源。若资源未按预期生成，请检查依赖顺序以及资源的就绪状态。

 **查看计算出的创建顺序**：

```
# See the order kro will create resources
kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.topologicalOrder}'
```

该操作会展示基于资源间 CEL 表达式引用关系计算得出的资源创建顺序。

 **检查资源就绪状态**：

```
# View instance status to see which resources are ready
kubectl get custom-kind
         my-instance -o jsonpath='{.status}'

# Check specific resource status
kubectl get deployment my-deployment -o jsonpath='{.status.conditions}'
```

 **验证 readyWhen 条件（若已配置）**：

`readyWhen` 字段为可选项。若未指定该字段，资源在创建完成后会被立即判定为就绪状态。若已定义 `readyWhen` 条件，请验证该条件是否能正确校验资源的就绪状态：

```
resources:
  - id: deployment
    readyWhen:
      - ${deployment.status.availableReplicas == deployment.spec.replicas}
```

 **检查资源事件**：

```
# View events for the underlying resources
kubectl get events -n namespace --sort-by='.lastTimestamp'
```

## 模式验证失败
<a name="_schema_validation_failures"></a>

若实例因模式验证错误而无法创建，请确认该实例是否符合 RGD 模式要求。

 **检查验证错误**：

```
# Attempt to create instance and view error
kubectl apply -f instance.yaml

# View existing instance validation status
kubectl describe custom-kind
         my-instance | grep -A 5 "Validation"
```

 **常见验证问题**：
+  **必填字段缺失**：实例未提供模式要求的全部必填字段
+  **类型不匹配**：在需要整数类型的位置传入了字符串类型
+  **枚举值无效**：使用了不在允许取值列表内的数值
+  **格式不匹配**：字符串未匹配正则表达式格式

 **查看 RGD 模式**：

```
# View the schema definition
kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.spec.schema}'
```

确保实例提供所有必填字段且类型正确。

## 后续步骤
<a name="_next_steps"></a>
+  [EKS 托管型 kro 注意事项](kro-considerations.md)：kro 注意事项和最佳实践
+  [配置 kro 权限](kro-permissions.md)：为平台团队与应用团队配置 RBAC
+  [kro 概念](kro-concepts.md)：了解 kro 的基本概念及资源生命周期
+  [EKS 功能问题排查](capabilities-troubleshooting.md)：一般功能问题排查指导