**이 페이지 개선에 도움 주기** 

이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 **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. https://console.aws.amazon.com/eks/home\#/clusters에서 Amazon EKS 콘솔을 엽니다.

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"
```

 **일반적인 검증 문제**:
+  **필수 필드 누락**: 인스턴스가 필요한 모든 스키마 필드를 제공하지 않음
+  **유형 불일치**: 정수가 예상되는 경우 문자열 제공
+  **유효하지 않은 열거 값**: 허용된 목록에 없는 값 사용
+  **패턴 불일치**: 문자열이 정규식 패턴과 일치하지 않음

 **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) - 일반 기능 문제 해결 지침