對 kro 功能的問題進行故障診斷

本主題提供 kro 的 EKS 功能疑難排解指引，包括功能運作狀態檢查、RBAC 許可、CEL 表達式錯誤和資源合成問題。

注意

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

功能是 ACTIVE，但 ResourceGraphDefinitions 無法運作

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

檢查功能運作狀態：

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

主控台：

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

2. 選取您的叢集名稱。

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

4. 選擇監控叢集。

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

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 許可。

檢查 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，請檢查條件訊息是否有驗證錯誤，例如未知欄位、類型不相符或循環相依性。

已建立執行個體，但基礎資源未顯示

如果自訂資源執行個體存在，但未建立基礎 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 許可。

CEL 表達式錯誤

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}

資源相依性無法解析

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"

常見的驗證問題：

• 缺少必要欄位：執行個體不提供所有必要的結構描述欄位

• 類型不符：提供預期整數的字串

• 列舉值無效：使用不在允許清單中的值

• 模式不相符：字串不符合 regex 模式

檢閱 RGD 結構描述：

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

確保您的執行個體為所有必要欄位提供正確的類型。

後續步驟

• EKS 的 kro 考量 - kro 考量事項和最佳實務

• 設定 kro 許可 - 為平台和應用程式團隊設定 RBAC

• kro 概念 - 了解 kro 概念和資源生命週期

• 對 EKS 功能進行故障診斷 - 一般功能故障診斷指引