# 설정 안내서(AWS CLI)
이 안내서에서는 AWS CLI를 사용하여 기존 Amazon EKS 클러스터에 Enhanced Container Insights(Classic)를 설치하는 방법을 안내합니다. 추가 기능은 인프라 지표, 컨테이너 로그 및 성능 데이터를 수집하는 DaemonSet로 CloudWatch 에이전트를 배포합니다.
**유지 관리 모드**
Enhanced Container Insights(Classic)는 유지 관리 모드입니다. 새 배포의 경우 [OTel Container Insights(권장)](container-insights-eks-otel.md)가 권장됩니다.
## 사전 조건
시작하기 전에 다음 요구 사항을 충족하는지 확인합니다.
+ Kubernetes 버전 1.25 이상을 실행하는 기존의 Amazon EKS 클러스터
+ 플랫폼 버전 `eks.1` 이상
+ AWS CLI 버전 2.12.0 이상
+ 대상 클러스터와 통신하도록 구성된 `kubectl`
+ IAM 권한: `eks:CreateAddon`, `eks:DescribeAddon`, `iam:CreateServiceLinkedRole`, `iam:CreateRole`, `iam:AttachRolePolicy`
+ 클러스터에 설치된 EKS Pod Identity Agent 추가 기능 또는 구성된 서비스 계정에 대한 IAM 역할(IRSA)
+ 클러스터에서 CloudWatch 엔드포인트로의 아웃바운드 인터넷 액세스
## 1단계 - IAM 역할 생성
CloudWatch 에이전트가 데이터를 CloudWatch로 전송할 수 있도록 IAM 역할을 생성합니다.
**CloudWatch 에이전트 IAM 역할 생성**
1. 다음 명령을 실행하여 EKS Pod Identity에 대한 신뢰 정책 파일로 역할을 생성합니다.
```
aws iam create-role \
--role-name EKS-CloudWatch-Agent-Role \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": { "Service": "pods.eks.amazonaws.com" },
"Action": ["sts:AssumeRole", "sts:TagSession"]
}]
}'
```
1. `CloudWatchAgentServerPolicy` 관리형 정책을 역할에 연결합니다.
```
aws iam attach-role-policy \
--role-name EKS-CloudWatch-Agent-Role \
--policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy
```
## 2단계: Pod Identity 연결 생성
IAM 역할을 클러스터의 CloudWatch 에이전트 서비스 계정과 연결합니다.
**Pod Identity 연결 생성**
+ 다음 명령을 실행합니다. {{cluster-name}}을 Amazon EKS 클러스터의 이름으로 바꾸고 {{account-id}}를 AWS 계정 ID로 바꿉니다.
```
aws eks create-pod-identity-association \
--cluster-name {{cluster-name}} \
--namespace amazon-cloudwatch \
--service-account cloudwatch-agent \
--role-arn arn:aws:iam::{{account-id}}:role/EKS-CloudWatch-Agent-Role
```
## 3단계: Amazon CloudWatch Observability 추가 기능 설치
클러스터에 `amazon-cloudwatch-observability` 추가 기능을 설치합니다.
**추가 기능 설치**
+ 다음 명령을 실행합니다. {{cluster-name}}을 Amazon EKS 클러스터의 이름으로 바꿉니다.
```
aws eks create-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--addon-version {{v5.x.x-eksbuild.x}}
```
{{v5.x.x-eksbuild.x}}를 사용 가능한 최신 v5.x 버전으로 바꿉니다. `--addon-version` 없이 설치하면 Classic 대신 OTel 파이프라인을 활성화하는 최신 버전(v6.2.0 이상)이 설치됩니다.
## 4단계: 추가 기능 상태 확인
추가 기능이 성공적으로 설치되었는지 확인합니다.
**추가 기능 상태 확인**
+ 다음 명령을 실행합니다. {{cluster-name}}을 Amazon EKS 클러스터의 이름으로 바꿉니다.
```
aws eks describe-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--query "addon.status" \
--output text
```
예상 출력은 `ACTIVE`입니다.
## 5단계: 에이전트 포드가 실행 중인지 확인
CloudWatch 에이전트 포드가 `amazon-cloudwatch` 네임스페이스에서 실행 중인지 확인합니다.
**에이전트 포드가 실행 중인지 확인**
+ 다음 명령을 실행합니다.
```
kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent
```
모든 포드에 `Running` 상태가 표시되어야 합니다.
## CloudWatch에서 데이터 확인
설정을 완료하면 Container Insights 데이터가 3\~5분 이내에 CloudWatch에 표시됩니다.
**Container Insights 데이터 확인**
1. [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)에서 CloudWatch 콘솔을 엽니다.
1. 탐색 창에서 **Contributor Insights**를 선택합니다.
1. 클러스터에 `node_cpu_utilization` 및 `pod_memory_utilization`과 같은 지표가 나타나는지 확인합니다.
## 문제 해결
Amazon EKS에 Enhanced Container Insights(Classic)를 설치할 때 일반적인 문제를 해결하려면 다음 지침을 따릅니다.
### 추가 기능 상태가 CREATE\_FAILED 또는 DEGRADED로 표시됨
**증상:** `aws eks describe-addon`을 실행하면 상태가 `CREATE_FAILED` 또는 `DEGRADED`로 표시됩니다.
**원인:** IAM 권한이 부족하거나 Pod Identity 연결이 누락되어 추가 기능 설치가 실패했습니다.
**해결 방법:** 다음 단계에 따라 이 문제를 해결합니다.
1. 다음 명령을 실행하여 자세한 오류 정보를 확인합니다. {{cluster-name}}을 해당 클러스터의 이름으로 바꿉니다.
```
aws eks describe-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--query "addon.health"
```
1. IAM 역할이 존재하고 `CloudWatchAgentServerPolicy`가 연결되어 있는지 확인합니다.
1. Pod Identity 연결이 올바른 네임스페이스(`amazon-cloudwatch`) 및 서비스 계정(`cloudwatch-agent`)을 대상으로 하는지 확인합니다.
1. 실패한 추가 기능을 삭제하고 문제를 해결한 후 다시 설치합니다.
```
aws eks delete-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability
```
### 5분 후 CloudWatch에 지표가 표시되지 않음
**증상:** 에이전트 포드에 `Running` 상태가 표시되지만 5분 후에는 CloudWatch에 지표가 표시되지 않습니다.
**원인:** 네트워크 제한 또는 잘못된 IAM 권한으로 인해 에이전트가 CloudWatch로 데이터를 전송할 수 없습니다.
**해결 방법:** 다음 단계에 따라 이 문제를 해결합니다.
1. VPC 보안 그룹 및 네트워크 ACL이 CloudWatch 엔드포인트로의 아웃바운드 HTTPS 트래픽(포드 443)을 허용하는지 확인합니다.
1. 에이전트 로그에서 권한 오류 또는 연결 제한 시간을 확인합니다.
```
kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=100 | grep -i "error\|timeout\|denied"
```
1. IAM 역할에 `CloudWatchAgentServerPolicy` 정책이 연결되어 있고 신뢰 정책이 `pods.eks.amazonaws.com`을 허용하는지 확인합니다.
### 에이전트 포드가 보류 중 또는 CrashLoopBackOff 상태로 멈춤
**증상:** `kubectl get pods -n amazon-cloudwatch`를 실행하면 하나 이상의 포드에 `Pending` 또는 `CrashLoopBackOff` 상태가 표시됩니다.
**원인:** 노드 리소스 부족, 이미지 가져오기 실패 또는 권한 누락으로 인해 에이전트 포드를 시작할 수 없습니다.
**해결 방법:** 다음 단계에 따라 이 문제를 해결합니다.
1. 포드 이벤트에서 자세한 오류 메시지를 확인합니다.
```
kubectl describe pod -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent
```
1. 노드에 에이전트 포드에 사용할 수 있는 CPU와 메모리가 충분한지 확인합니다.
1. EKS Pod Identity Agent 추가 기능이 설치되어 실행 중인지 확인합니다.
```
kubectl get pods -n kube-system -l app.kubernetes.io/name=eks-pod-identity-agent
```
## 다음 단계
업그레이드할 준비가 되셨나요? Enhanced Container Insights(Classic)에서 OTel Container Insights로 이동하는 단계별 지침은 [Enhanced Container Insights(Classic)에서 OTel 컨테이너 인사이트로 마이그레이션](container-insights-eks-migrate-from-classic.md) 섹션을 참조하세요.