사전 조건 OTel Container Insights 활성화(콘솔)OTel Container Insights 활성화(AWS CLI)CloudWatch에서 데이터 확인 문제 해결

빠른 시작: Amazon EKS의 OTel Container Insights

이 안내서에서는 기존 Amazon EKS 클러스터에서 OTel Container Insights를 활성화하는 방법을 안내합니다. 이 프로시저가 끝나면 클러스터는 Enhanced Observability가 활성화된 Amazon CloudWatch로 인프라 지표와 컨테이너 로그를 전송합니다.

OTel Container Insights는 AWS Management Console(가장 빠름) 또는 AWS CLI를 사용하는 두 가지 방법으로 활성화할 수 있습니다. 두 접근 방식 모두 OTel Container Insights 구성을 사용하여 동일한 amazon-cloudwatch-observability EKS 추가 기능을 설치합니다. 수동 에이전트 배포, 헬름 차트 또는 사용자 지정 수집기 파이프라인이 필요하지 않습니다. 전체 프로세스는 5분 미만이 걸립니다.

사전 조건

OTel Container Insights를 활성화하기 전에 다음 요구 사항을 충족하는지 확인합니다.

Kubernetes 버전 1.28 이상을 실행하는 기존의 Amazon EKS 클러스터
플랫폼 버전 eks.1 이상
버전 6.2.0 이상의 amazon-cloudwatch-observability 추가 기능
AWS CLI 버전 2.15.0 이상(CLI 기반 설정의 경우)
대상 클러스터와 통신하도록 구성된 kubectl
IAM 권한: eks:CreateAddon, eks:DescribeAddon, iam:CreateServiceLinkedRole
클러스터에 설치된 EKS Pod Identity Agent 추가 기능 또는 구성된 서비스 계정에 대한 IAM 역할(IRSA)
클러스터에서 CloudWatch 엔드포인트로의 아웃바운드 인터넷 액세스

OTel Container Insights 활성화(콘솔)

AWS Management Console은 OTel Container Insights를 활성화하는 가장 빠른 경로를 제공합니다.

콘솔을 사용하여 OTel Container Insights 활성화

https://console.aws.amazon.com/eks/에서 Amazon EKS 콘솔을 엽니다.
클러스터를 선택한 후 클러스터 이름을 선택합니다.
관찰성 탭을 선택합니다.
Container Insights 활성화를 선택하고 화면의 지침을 따릅니다.

자세한 콘솔 안내는 콘솔에서 OTel Container Insights 활성화 섹션을 참조하세요.

OTel Container Insights 활성화(AWS CLI)

다음 단계에 따라 AWS CLI를 사용하여 OTel Container Insights를 활성화합니다.

1단계 - IAM 역할 생성

CloudWatch Observability 추가 기능이 CloudWatch로 데이터를 전송할 수 있도록 허용하는 IAM 역할을 생성합니다.

CloudWatch Observability 추가 기능 IAM 역할 생성

다음 명령을 실행하여 EKS Pod Identity에 대한 신뢰 정책으로 역할을 생성합니다.


aws iam create-role \
  --role-name EKS-CloudWatch-Observability-Role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": { "Service": "pods.eks.amazonaws.com" },
      "Action": ["sts:AssumeRole", "sts:TagSession"]
    }]
  }'

CloudWatchAgentServerPolicy 관리형 정책을 역할에 연결합니다.


aws iam attach-role-policy \
  --role-name EKS-CloudWatch-Observability-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-Observability-Role

3단계: Amazon CloudWatch Observability 추가 기능 설치

OTel Container Insights가 활성화된 amazon-cloudwatch-observability 추가 기능을 설치합니다.

추가 기능 설치

다음 명령을 실행합니다. cluster-name을 Amazon EKS 클러스터의 이름으로 바꿉니다.
```
aws eks create-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values '{"otelContainerInsights":{"enabled":true}}'
```
중요
otelContainerInsights.enabled 구성이 필요합니다. OTel Container Insights는 기본적으로 활성화되어 있지 않습니다.

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에 표시됩니다.

지표 확인

CloudWatch에서 지표 확인

https://console.aws.amazon.com/cloudwatch/에서 CloudWatch 콘솔을 엽니다.
탐색 창에서 Query Studio를 선택합니다.
PromQL을 사용하여 container_cpu_usage_seconds_total과 같은 지표를 검색합니다.

로그 확인

클러스터에 대한 로그 그룹이 있는지 확인하려면 다음 명령을 실행합니다. cluster-name을 Amazon EKS 클러스터의 이름으로 바꿉니다.


aws logs describe-log-groups \
  --log-group-name-prefix "/aws/containerinsights/cluster-name" \
  --query "logGroups[].logGroupName" \
  --output table

예상 데이터 확보 시간

다음 표에는 OTel Container Insights를 활성화한 후 각 신호 유형에 대한 예상 지연 시간이 나와 있습니다.

신호	예상 지연 시간
인프라 지표	2~3분
컨테이너 로그	2~3분
성능 로그 이벤트	3~5분

문제 해결

Amazon EKS에서 OTel Container Insights를 활성화할 때 일반적인 문제를 해결하려면 다음 지침을 사용합니다.

추가 기능 상태가 CREATE_FAILED 또는 DEGRADED로 표시됨

증상: aws eks describe-addon을 실행하면 상태가 CREATE_FAILED 또는 DEGRADED로 표시됩니다.

원인: 일반적으로 IAM 권한이 부족하거나 Pod Identity 연결이 누락되어 추가 기능 설치가 실패했습니다.

해결 방법: 다음 단계에 따라 이 문제를 해결합니다.

다음 명령을 실행하여 자세한 오류 정보를 확인합니다. cluster-name을 해당 클러스터의 이름으로 바꿉니다.
```
aws eks describe-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --query "addon.health"
```
IAM 역할이 존재하고 CloudWatchAgentServerPolicy가 연결되어 있는지 확인합니다.
Pod Identity 연결이 올바른 네임스페이스(amazon-cloudwatch) 및 서비스 계정(cloudwatch-agent)을 대상으로 하는지 확인합니다.

실패한 추가 기능을 삭제하고 문제를 해결한 후 다시 설치합니다.


aws eks delete-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability

에이전트 포드가 CrashLoopBackOff 또는 보류 중 상태임

증상: kubectl get pods -n amazon-cloudwatch를 실행하면 하나 이상의 포드에 CrashLoopBackOff 또는 Pending 상태가 표시됩니다.

원인: 노드 리소스 부족, 권한 누락 또는 네트워크 연결 문제로 인해 에이전트 포드를 시작할 수 없습니다.

해결 방법: 다음 단계에 따라 이 문제를 해결합니다.

포드 이벤트에서 자세한 오류 메시지를 확인합니다.


kubectl describe pod -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent

에이전트 컨테이너 로그에 시작 오류가 있는지 확인합니다.


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

노드에 에이전트 포드에 사용할 수 있는 CPU와 메모리가 충분한지 확인합니다.
EKS Pod Identity Agent 추가 기능이 설치되어 실행 중인지 확인합니다.
```
kubectl get pods -n kube-system -l app.kubernetes.io/name=eks-pod-identity-agent
```

5분 후 CloudWatch에 지표가 표시되지 않음

증상: 에이전트 포드에 Running 상태가 표시되지만 5분 후에는 CloudWatch에 지표가 표시되지 않습니다.

원인: 일반적으로 네트워크 제한 또는 잘못된 IAM 권한으로 인해 에이전트가 CloudWatch로 데이터를 전송할 수 없습니다.

해결 방법: 다음 단계에 따라 이 문제를 해결합니다.

에이전트 포드가 CloudWatch 엔드포인트에 도달할 수 있는지 확인합니다. VPC 보안 그룹 및 네트워크 ACL이 CloudWatch 엔드포인트로의 아웃바운드 HTTPS 트래픽(포트 443)을 허용하는지 확인합니다.

에이전트 로그에서 권한 오류 또는 연결 제한 시간을 확인합니다.


kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=100 | grep -i "error\|timeout\|denied"

IAM 역할에 CloudWatchAgentServerPolicy 정책이 연결되어 있고 신뢰 정책이 pods.eks.amazonaws.com을 허용하는지 확인합니다.
CloudWatch에 VPC 엔드포인트를 사용하는 경우 엔드포인트 정책이 필요한 작업을 허용하는지 확인합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

OTel Container Insights(권장)

콘솔에서 OTel Container Insights 활성화

빠른 시작: Amazon EKS의 OTel Container Insights

사전 조건

OTel Container Insights 활성화(콘솔)

콘솔을 사용하여 OTel Container Insights 활성화

OTel Container Insights 활성화(AWS CLI)

1단계 - IAM 역할 생성

CloudWatch Observability 추가 기능 IAM 역할 생성

2단계: Pod Identity 연결 생성

Pod Identity 연결 생성

3단계: Amazon CloudWatch Observability 추가 기능 설치

추가 기능 설치

중요

4단계: 추가 기능 상태 확인

추가 기능 상태 확인

5단계: 에이전트 포드가 실행 중인지 확인

에이전트 포드가 실행 중인지 확인

CloudWatch에서 데이터 확인

지표 확인

CloudWatch에서 지표 확인

로그 확인

예상 데이터 확보 시간

문제 해결

추가 기능 상태가 CREATE_FAILED 또는 DEGRADED로 표시됨

에이전트 포드가 CrashLoopBackOff 또는 보류 중 상태임

5분 후 CloudWatch에 지표가 표시되지 않음