# Amazon EKS의 Container Insights 문제 해결
<a name="container-insights-eks-troubleshooting"></a>

이 섹션에서는 Amazon EKS에서 Container Insights를 설정하거나 운영할 때 발생할 수 있는 일반적인 문제를 다룹니다. 다음 표와 진단 명령을 사용하여 OTel 또는 Classic 접근 방식을 사용하는지 여부에 관계없이 문제를 식별하고 해결합니다.

접근 방식별 설정 지침은 [빠른 시작: Amazon EKS의 OTel Container Insights](container-insights-eks-otel-quickstart.md) 또는 [설정 안내서(AWS CLI)](container-insights-eks-classic-setup.md) 섹션을 참조하세요. 접근 방식을 비교하려면 [Container Insights 접근 방식 비교](container-insights-eks-compare.md) 섹션을 참조하세요.

## CloudWatch에 지표가 표시되지 않음
<a name="container-insights-eks-troubleshooting-metrics"></a>

`ContainerInsights` 네임스페이스에 지표가 표시되지 않는 경우 다음 표를 사용하여 원인을 식별합니다.


| 증상 | 원인 | 해결 방법 | 
| --- | --- | --- | 
| ContainerInsights 네임스페이스에 지표가 없음 | IAM 역할에 cloudwatch:PutMetricData 권한이 없음 | CloudWatchAgentServerPolicy 관리형 정책을 에이전트 IAM 역할에 연결합니다. | 
| 지표가 일부 노드에는 표시되지만 다른 노드에는 표시되지 않음 | 테인트로 인해 에이전트 DaemonSet가 모든 노드에 예약되지 않음 | 테인팅된 노드에 대한 예약을 허용하도록 에이전트 DaemonSet에 허용치를 추가합니다. | 
| 지표 표시가 중지됨 | 에이전트 포드가 OOMKilled 또는 재시작 중임 | 에이전트 포드 리소스 사양의 메모리 제한을 늘립니다. | 
| 지표가 오래되었거나 0임 | 네트워크 연결이 차단됨 | VPC 보안 그룹을 확인하고 CloudWatch VPC 엔드포인트가 존재하는지 확인합니다. | 
| 향상된 지표가 누락됨 | 향상된 관찰성을 위해 에이전트가 구성되지 않음 | 에이전트 구성에서 enhancedObservability: true를 설정합니다. | 

## 에이전트 포드가 시작되지 않음
<a name="container-insights-eks-troubleshooting-agent-pods"></a>

에이전트 포드가 시작되지 않거나 실행 중이 아닌 상태로 유지되는 경우 다음 표를 사용하여 문제를 진단합니다.


| 증상 | 원인 | 해결 방법 | 
| --- | --- | --- | 
| ImagePullBackOff | Amazon ECR에 연결할 수 없거나 이미지 태그가 잘못됨 | 이미지 URI를 확인하고 노드가 Amazon ECR에 액세스할 수 있는지 확인합니다. | 
| Pending | 노드의 CPU 또는 메모리 부족 | 에이전트 포드 사양에서 노드 그룹을 확장하거나 리소스 요청을 줄입니다. | 
| CrashLoopBackOff | 잘못된 구성 또는 볼륨 마운트 누락 | 영향을 받는 포드에서 kubectl logs를 실행하여 포드 로그에 구성 오류가 있는지 확인합니다. | 
| FailedScheduling | 노드 선호도 또는 테인트로 인해 예약되지 않음 | DaemonSet 사양의 nodeSelector 및 허용치를 검토합니다. | 
| 종료 코드 1 | 서비스 계정에 IRSA 주석이 없음 | 서비스 계정에 eks.amazonaws.com/role-arn 주석이 있는지 확인합니다. | 

## 추가 기능 설치 실패
<a name="container-insights-eks-troubleshooting-addon"></a>

`amazon-cloudwatch-observability` 추가 기능을 설치하지 못하거나 비정상 상태를 보고하는 경우 다음 표를 사용하여 문제를 해결합니다.


| 증상 | 원인 | 해결 방법 | 
| --- | --- | --- | 
| CREATE\_FAILED | 이전 설치와 충돌하는 리소스 | 충돌하는 리소스를 삭제하고 추가 기능을 생성할 때 --resolve-conflicts OVERWRITE를 사용합니다. | 
| OIDC 공급자를 찾을 수 없음 | 클러스터에 대한 IAM OIDC ID 공급자가 없음 | eksctl utils associate-iam-oidc-provider를 실행하여 공급자를 생성합니다. | 
| 버전 충돌 | 추가 기능 버전이 Kubernetes 버전과 호환되지 않음 | aws eks describe-addon-versions를 실행하여 호환되는 버전을 나열합니다. | 
| DEGRADED 상태 | 권한 누락으로 인해 상태 확인이 실패함 | 포드 로그를 확인하고 IRSA 역할에 필수 정책이 연결되어 있는지 확인합니다. | 

## 로그 전송 문제
<a name="container-insights-eks-troubleshooting-logs"></a>

컨테이너 로그가 Amazon CloudWatch Logs에 표시되지 않는 경우 다음 표를 사용하여 원인을 식별합니다.


| 증상 | 원인 | 해결 방법 | 
| --- | --- | --- | 
| 로그 그룹이 존재하지 않음 | logs:CreateLogGroup 권한 누락 | 에이전트 IAM 역할에 Amazon CloudWatch Logs 권한을 추가합니다. | 
| 로그 그룹이 존재하지만 비어 있음 | 로그 또는 리전 불일치에 대해 에이전트가 구성되지 않음 | 에이전트 구성에 로그 수집이 포함되어 있고 리전이 클러스터 리전과 일치하는지 확인합니다. | 
| 로그가 5분 이상 지연됨 | 플러시 간격이 너무 높거나 노드에 과부하가 걸림 | 에이전트 구성의 force\_flush\_interval 값을 줄입니다. | 
| 성능 로그 누락 | 에이전트가 애플리케이션 로그에 대해서만 구성됨 | 에이전트 구성에 Container Insights 성능 로그 섹션이 있는지 확인합니다. | 

## 마이그레이션 관련 문제
<a name="container-insights-eks-troubleshooting-migration"></a>

Container Insights 접근 방식 간에 마이그레이션하는 동안 문제가 발생하는 경우 다음 표를 사용합니다. 전체 마이그레이션 워크플로는 [마이그레이션 안내서](container-insights-eks-migration-hub.md) 섹션을 참조하세요.


| 증상 | 원인 | 해결 방법 | 
| --- | --- | --- | 
| 병렬 실행 중 지표가 중복됨 | 두 접근 방식 모두 지표를 동시에 게시함 | 이 동작은 병렬 실행 중에 예상되는 동작입니다. 새 접근 방식을 검증한 후 레거시 접근 방식을 비활성화합니다. | 
| 접근 방식 간에 지표 값이 서로 다름 | 서로 다른 계산 방법 | 약간의 차이(5% 미만)는 예상됩니다. 큰 차이는 접근 방식 간의 구성 불일치를 나타냅니다. | 
| 롤백 실패 | 사용자 지정 구성이 다시 적용되지 않음 | 롤백할 때 전체 구성 값을 다시 적용합니다. | 
| 마이그레이션 중 경보 발생 | 전환 기간 동안의 지표 누락 | 영향을 받는 경보에서 누락된 데이터 처리를 notBreaching으로 일시적으로 설정합니다. | 

## OTel Container Insights 문제
<a name="container-insights-eks-troubleshooting-otel"></a>

다음 문제는 OTel Container Insights 접근 방식과 관련이 있습니다. 일반적인 설정 지침은 [빠른 시작: Amazon EKS의 OTel Container Insights](container-insights-eks-otel-quickstart.md) 섹션을 참조하세요.


| 증상 | 원인 | 해결 방법 | 
| --- | --- | --- | 
| 403 금지된 내보내기 오류 | IAM 역할에 CloudWatch 권한이 없음 | CloudWatchAgentServerPolicy가 에이전트 역할에 연결되어 있는지 확인합니다. | 
| 지표 엔드포인트에서 연결이 거부됨 | 수집기가 kubelet에 도달할 수 없음 | hostNetwork: true가 포드 사양에 설정되어 있는지 확인하거나 서비스 계정에 필요한 권한이 있는지 확인합니다. | 
| 높은 메모리 사용량 | 배치 프로세서 대기열이 너무 큼 | 수집기 구성에서 batch/timeout 및 batch/send\_batch\_size 값을 줄입니다. | 
| 사용자 지정 지표가 표시되지 않음 | 애플리케이션 엔드포인트에 대해 수신기가 구성되지 않음 | 수집기 구성에서 애플리케이션 지표 포트를 대상으로 하는 Prometheus 수신기를 추가합니다. | 

## 일반 진단 명령
<a name="container-insights-eks-troubleshooting-commands"></a>

다음 명령을 사용하여 Container Insights 배포에 대한 정보를 수집합니다.

에이전트 포드 상태를 확인하려면 다음 명령을 실행합니다.

```
kubectl get pods -n amazon-cloudwatch
```

에이전트 포드 로그를 확인하려면 다음 명령을 실행합니다.

```
kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=50
```

에이전트 DaemonSet 상태를 확인하려면 다음 명령을 실행합니다.

```
kubectl get daemonset -n amazon-cloudwatch
```

서비스 계정에서 IAM 역할을 확인하려면 다음 명령을 실행합니다.

```
kubectl get serviceaccount -n amazon-cloudwatch -o yaml
```

클러스터 추가 기능 상태를 확인하려면 다음 명령을 실행합니다. {{cluster-name}}을 Amazon EKS 클러스터의 이름으로 바꿉니다.

```
aws eks describe-addon --cluster-name {{cluster-name}} --addon-name amazon-cloudwatch-observability
```

Container Insights 로그 그룹을 나열하려면 다음 명령을 실행합니다. {{cluster-name}}을 Amazon EKS 클러스터의 이름으로 바꿉니다.

```
aws logs describe-log-groups --log-group-name-prefix "/aws/containerinsights/{{cluster-name}}"
```

## 관련 리소스
<a name="container-insights-eks-troubleshooting-related"></a>

Amazon EKS에서 Container Insights를 설정하고 운영하는 방법에 대한 자세한 내용은 다음 주제를 참조하세요.
+ [빠른 시작: Amazon EKS의 OTel Container Insights](container-insights-eks-otel-quickstart.md) - OTel Container Insights 설정
+ [설정 안내서(AWS CLI)](container-insights-eks-classic-setup.md) - Classic Container Insights 설정
+ [마이그레이션 안내서](container-insights-eks-migration-hub.md) - 접근 방식 간 마이그레이션
+ [Container Insights 접근 방식 비교](container-insights-eks-compare.md) - Container Insights 접근 방식 비교