帮助改进此页面

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

排查 kro 功能问题

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

功能状态显示为 ACTIVE，但 ResourceGraphDefinition 无法正常工作

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

检查功能运行状况：

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

控制台：

AWS 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 权限：

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

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

检查 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 状态为 False，请查看状态条件信息，排查是否存在未知字段、类型不匹配或循环依赖等验证类错误。

已创建实例但未生成底层资源

若自定义资源实例已存在，但对应的底层 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 字段，用于展示其宏观状态：

实例同时包含四项状态条件：

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

验证 RBAC 权限：

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

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

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

CEL 表达式错误

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

常见 CEL 验证错误：

检查 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}

资源依赖关系无法解析

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'

模式验证失败

若实例因模式验证错误而无法创建，请确认该实例是否符合 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}'

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

后续步骤