**協助改進此頁面** 

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

若要為本使用者指南貢獻內容，請點選每個頁面右側面板中的**在 GitHub 上編輯此頁面**連結。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 對 kro 功能的問題進行故障診斷
<a name="kro-troubleshooting"></a>

**注意**  
EKS 功能是完全受管的，並在叢集外部執行。您無法存取控制器日誌或控制器命名空間。故障診斷著重於功能運作狀態、RBAC 組態和資源狀態。

## 功能為 ACTIVE，但 ResourceGraphDefinitions 無法運作
<a name="_capability_is_active_but_resourcegraphdefinitions_arent_working"></a>

如果您的 kro 功能顯示`ACTIVE`狀態，但 ResourceGraphDefinitions 未建立基礎資源，請檢查功能運作狀態、RBAC 許可和資源狀態。

 **檢查功能運作狀態**：

您可以在 EKS 主控台或使用 AWS CLI 檢視功能運作狀態和狀態問題。

 **主控台**：

1. 在以下網址開啟 Amazon EKS 主控台：https://console.aws.amazon.com/eks/home\#/clusters。

1. 選取您的叢集名稱。

1. 選擇**可觀測性**索引標籤。

1. 選擇**監控叢集**。

1. 選擇**功能**索引標籤以檢視所有功能的運作狀態和狀態。

 ** 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 許可**：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}'
```

ResourceGraphDefinitions 有三個金鑰狀態條件：
+  `ResourceGraphAccepted` - RGD 是否通過驗證 (CEL 語法、類型檢查、欄位存在）
+  `KindReady` - 是否產生並註冊自訂 API 的 CRD
+  `ControllerReady` - kro 是否正在主動監看自訂 API 的執行個體

如果 `ResourceGraphAccepted`是 `False`，請檢查條件訊息是否有驗證錯誤，例如未知欄位、類型不相符或循環相依性。

## 已建立執行個體，但基礎資源未顯示
<a name="_instances_created_but_underlying_resources_not_appearing"></a>

如果自訂資源執行個體存在，但未建立基礎 Kubernetes 資源 （部署、服務、ConfigMaps)，請確認 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 功能需要許可才能建立 ResourceGraphDefinitions 中定義的基礎 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 建立時間發現，而不是在建立執行個體時。 kro 會驗證所有 CEL 語法、針對 Kubernetes 結構描述類型檢查表達式，並在建立 RGD 時驗證欄位是否存在。

 **常見的 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"
```

 **常見的驗證問題**：
+  **缺少必要欄位**：執行個體不提供所有必要的結構描述欄位
+  **類型不符**：提供預期整數的字串
+  **列舉值無效**：使用不在允許清單中的值
+  **模式不相符**：字串不符合 regex 模式

 **檢閱 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) - 一般功能故障診斷指引