AEWS 4기 5주차(1) - EKS Debuggig(k8s debugging)

before start..

본 글은 공식 문서 및 서종호(가시다)님의 AWS EKS 워크샵 내용을 기반으로 참고하여 학습 목적으로 작성하였습니다.
주관적인 해석이 포함되어 있어 사실과 다르거나 오류가 있을 수 있으니 참고용으로만 읽어주시기 바랍니다.

EKS Debugging - 참고

EKS 운영 중 발생하는 문제는 컨트롤 플레인, 노드, 네트워크, 워크로드, 스토리지, 옵저버빌리티 등 다양한 레이어에 걸쳐 나타나며, 체계적이고 신속하게 문제를 해결하기 위한 것입니다.

 

EKS Debugging Layer

• 컨트롤플레인(상위 레이어)
  종류 : API Server, etcd, 인증/인가, Add-on
• 노드
  종류 : kubelet, containerd,Karpenter, 
• 네트워크
  종류 : VPC CNI, DNS, Netowkr Policy
• 워크로드
  종류 : Pod 상태, Probe Deployment, HPA
• 스토리지
  종류 : EBS CNI, EFS CNI, PV/PVC
• Observability(하위 레이어)
  종류 : Metric, Log, Alarm, Dashboard

접근 방법

구분	Top-Down(증상 > 원인)	Bottom-Up(인프라 > 앱)
시작점	사용자 보고 증상/알림	컨트롤 플레인부터 순차 점검
적합한 상황	프로덕션 인시던트, 장애 대응	예방적 점검, 마이그레이션 후 검증
장/단점	장점 : 빠른 장애 해결, 사용자 영향 최소화 단점 : 근본 원인 놓칠 수 있음	장점 : 숨은 문제 조기 발견, 전체 상태 파악 단점 : 시간 소요가 큼
소요시간	분 단위(긴급 대응)	시간 단위(정기 점검)
권장 대상	SRE 엔지니어	플랫폼 팀, 클러스터 관리자

 

First 5 Minutes 체크리스트 - ★중요★

해당 체크리스트가 중요한 이유

• 스코프 판별을 통해 어느 구간에서 장애가 발생했는지와 초동 대응을 통해 장애 시간을 축소할 수 있습니다.
• 초기 진단(30초)
  # 클러스터 상태 확인
  aws eks describe-cluster --name <cluster-name> --query 'cluster.status' --output text
  
  # 노드 상태 확인(Running 상태 확인)
  kubectl get nodes
  
  # 비정상 Pod 확인
  kubectl get pods --all-namespaces | grep -v Running |grep -v Completed
• 스코프 판별(2분)
  # 최근 이벤트 확인(전체 네임스페이스)
  kubetl get events --all-namespaces --sort-by='.lastTimestamp' | tail -20
  
  # 특정 네임스페이스 Pod 상태 집계
  kubectl get pods -n <namespace 명> --no-headers | awk '{print $3}' | sort | uniq -c | sort -rn
  
  # 노드별 비정상 Pod 분포 확인
  kubectl get pods --all-namespaces -o wide --field-selector=status.phase!=Running | \
  awk 'NR>1 {print $8}' | sort | uniq -c | sort -rn
• 초동 대응(5분)
  # 문제 Pod의 상세 정보
  kubectl describe pod <pod 명> -n <namespace 명>
  
  # 이전 컨테이너 로그 (CrashLoopBackOff인 경우)
  kubectl logs <pod 명> -n <namespace 명> --previous
  
  # 리소스 사용량 확인
  kubectl top nodes
  kubectl top pods -n <namespace 명> --sort-by=cpu

 

Control Plane Debugging

EKS 컨트롤 플레인은 Cloudwatch 서비스를 통해 5가지 로그 타입을 수집할 수 있습니다.

• API(kube-apiserver) - API 요청/응답 기록 수집
• audit(kube-apiserver-audit) - 감사 로그 수집
• authenticator(aws-iam-authenticator) - IAM 인증 이벤트 수집
• ControllManager(kube-controller-manager) - 컨트롤러 동작 로그 수집
• Scheduler(kube-scheduler) - 스케줄링 결정 및 실패 로그 수집

 

Cloudwatch Logs insight 로그 상황별 검색

# API 서버 에러(400+) 분석
fields @timestamp, @message
| filter @logStream like /kube-apiserver-audit/
| filter responseStatus.code >= 400
| stats count() by responseStatus.code
| sort count desc

# 인증 실패 추척
fields @timestamp, @message
| filter @logStream like /authenticator/
| filter @message like /error/ or @message like /denied/
| sort @timestamp desc

 

#aws-auth ConfigMap 변경 감지
fields @timestamp, @message
| filter @logStream like /kube-apiserver-audit/
| filter objectRef.resource = "configmaps" and objectRef.name = "aws-auth"
| filter verb in ["update", "patch", "delete"]
| sort @timestamp desc

 

# API Throttling 탐지
fields @timestamp, @message
| filter @logStream like /kube-apiserver/
| filter @message like /throttle/ or @message like /rate limit/
| stats count() by bin(5m)

 

# 비인가 접근 시도(보안 이벤트)
fields @timestamp, @message
| filter @logStream like /kube-apiserver-audit/
| filter responseStatus.code = 403
| stats count() by user.username
| sort count desc

 

인증/인가 디버깅

쿠버네티스(EKS)의 Control Plane은  API 서버에서 인증, 인가에 대한 디버깅을 하는 이유는 클러스터의 보안을 유지하면서 동시에 원활한 운영을 보장하기 위해서입니다.

# 현재 IAM 자격증명 확인
aws sts get-caller-identity

# 클러스터 인증 모드 확인
aws eks describe-cluster --name <cluster-name> \
  --query 'cluster.accessConfig.authenticationMode' --output text

• aws sts get-caller-identity
  용도: 현재 터미널에서 AWS CLI를 실행하고 있는 나의 실제 IAM 자격 증명(User 또는 Role)을 확인합니다.
  이유: 쿠버네티스 접근이 거부되었을 때 내가 의도한 계정으로 로그인되어 있는지 가장 먼저 확인하는 기본 명령어입니다.
• aws eks describe-cluster ~ --query 'clustser.accessConfig.authenticationMode' --output text
  용도: EKS 클러스터가 IAM 사용자를 쿠버네티스 사용자로 매핑하는 방식 확인합니다.
  이유: 최근 EKS는 기존의 aws-auth 방식(ConfigMap)에서 더 안전한 Access Entry 방식(API)으로 전환 중입니다. 반환값이 CONFIG_MAP, API_AND_CONFIG_MAP, API 중 무엇인지에 따라 디버깅 방향이 달라집니다.

# aws-auth ConfigMap 확인
kubectl describe configmap aws-auth -n kube-system

• kubectl describe configmap aws-auth -n kube-system
  용도: IAM User/Role이 쿠버네티스의 어떤 그룹(system:masters 등)에 매핑되어 있는지 확인합니다.
  이유: 접속이 안 되는 사용자의 ARN이 이 파일 안에 제대로 등록되어 있는지, 오타는 없는지 확인하기 위함입니다.

# Access Entry 생성
aws eks create-access-entry \
  --cluster-name <cluster-name> \
  --principal-arn arn:aws:iam::ACCOUNT:role/ROLE-NAME \
  --type STANDARD

# Access Entry 목록 확인
aws eks list-access-entries --cluster-name <cluster-name>

• aws eks create-access-entry / aws eks list-access-entries
  용도: EKS API를 통해 특정 IAM 권한자에게 클러스터 접근 권한(Access Entry)을 직접 부여하거나 목록을 조회합니다.
  이유: aws-auth 파일을 직접 수정하다가 클러스터가 망가지는 사고를 방지하기 위해 도입된 새로운 접근 제어 방식을 관리할 때 사용합니다.

 

# 1. ServiceAccount에 annotation 확인
kubectl get sa <sa-name> -n <namespace> -o yaml

# 2. Pod 내 AWS 환경변수 확인
kubectl exec -it <pod-name> -- env | grep AWS

# 3. OIDC Provider 확인
aws eks describe-cluster --name <cluster-name> \
  --query 'cluster.identity.oidc.issuer' --output text

# 4. IAM Role의 Trust Policy에서 OIDC Provider ARN 및 조건 확인
aws iam get-role --role-name <role-name> \
  --query 'Role.AssumeRolePolicyDocument'

• kubectl get sa <sa-name> -n <namespace> -o yaml
  용도: 쿠버네티스의 ServiceAccount(SA)에 AWS IAM Role ARN이 올바르게 주석(Annotation)으로 달려있는지 확인합니다.
  이유: eks.amazonaws.com/role-arn 주석이 없거나 오타가 있으면 파드는 권한을 얻을 수 없습니다.
• kubectl exec -it <pod-name> -- env | grep AWS
  용도: 파드 내부에 접속하여 AWS 관련 환경 변수가 정상적으로 주입되었는지 확인합니다.
  이유: IRSA가 정상 작동했다면 AWS_ROLE_ARN과 AWS_WEB_IDENTITY_TOKEN_FILE이라는 환경 변수가 반드시 있어야 합니다. 없다면 SA 설정이나 파드 재생성 여부를 의심해야 합니다.
• aws eks describe-cluster ... oidc.issuer
  용도: EKS 클러스터의 고유한 OIDC 공급자 URL을 확인합니다.
  이유: AWS IAM이 K8s의 파드를 신뢰하려면 이 OIDC URL을 알아야 합니다. 이 URL이 IAM OIDC 공급자에 제대로 등록되어 있는지 대조할 때 씁니다.
• aws iam get-role ... --query 'Role.AssumeRolePolicyDocument'
  용도: IAM Role의 신뢰 정책(Trust Relationship)을 확인합니다.
  이유: 파드가 이 Role을 사용(Assume)하려면 신뢰 정책 안에 "특정 OIDC URL을 통해 들어온 특정 네임스페이스의 특정 SA만 이 역할을 쓸 수 있다"라는 조건이 정확히 명시되어 있어야 합니다. 이 조건문이 틀려서 권한 획득에 실패하는 경우가 90% 이상입니다.

RBAC / Pod Identity 디버깅

ServiceAcccount에서 IAM Role 매핑에 실패하였을 경우 AccessDenied가 발생하거나 UnauthorizedOperation 에러가 발생하여 정상적인 동작이 되지 않을 경우 디버깅할 수 있는 방법입니다.

 

# 1. ServiceAccount annotation 확인 (IRSA)
kubectl get sa <service-account> -n <namespace> -o jsonpath='{.metadata.annotations.eks\.amazonaws\.com/role-arn}'

# 2. Pod Identity Association 확인
aws eks list-pod-identity-associations --cluster-name $CLUSTER \
  | jq '.associations[] | select(.serviceAccount=="<service-account>")'

# 3. Pod에 환경변수가 주입되었는지 확인
kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.serviceAccountName}'
kubectl exec <pod-name> -n <namespace> -- env | grep AWS

# 4. IAM Role Trust Policy 확인
aws iam get-role --role-name <role-name> \
  --query 'Role.AssumeRolePolicyDocument' --output json

• 1. kubectl get sa ... (IRSA 방식 점검)
  목적: 쿠버네티스 ServiceAccount에 IAM Role Annotation이 있는지 확인합니다.
  이유: 기존 IRSA 방식을 사용 중이라면, 쿠버네티스 측에서 파드에서 IAM Role을 사용한다고 명시해 두는 유일한 표식이 annotation입니다. 오타가 있거나 누락되어 있으면 파드는 권한 부여 프로세스 자체를 시작하지 않습니다.
• 2. aws eks list-pod-identity-associations ... (Pod Identity 방식 점검)
  목적: EKS API를 통해 생성된 Pod Identity와 연결된 리소스가 있는지 확인합니다.
  이유: 최근에 나온 'EKS Pod Identity' 기능은 1번처럼 YAML에 주석을 달지 않고, AWS EKS 콘솔이나 CLI에서 직접 어떤 SA가 어떤 IAM Role을 쓸지 매핑합니다. 매핑 정보가 EKS 컨트롤 플레인에 정상적으로 등록되어 있는지 검증하는 필수 단계입니다.
• 3. kubectl exec ... env | grep AWS (최종 주입 확인)
  목적: 파드 내부 컨테이너에 AWS 자격 증명 환경 변수가 실제로 꽂혀 있는지 확인합니다.
  이유: 1번이나 2번 설정이 정상적으로 끝났다면, 파드가 실행될 때 Kubelet이나 Pod Identity Agent가 컨테이너 안에 특정한 환경 변수들(AWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE 등)을 강제로 밀어 넣습니다.
  디버깅 포인트: 설정(1, 2번)은 완벽한데 여기(3번)서 환경 변수가 안 보인다면? "설정을 바꾸기 전에 이미 파드가 띄워져서" 반영이 안 된 것입니다. 파드를 재시작(kubectl delete pod)해야 합니다.
• 4. aws iam get-role ... (AWS IAM 신뢰 정책 점검)
  목적: 대상 IAM Role의 신뢰 관계(Trust Relationship)가 올바른지 확인합니다.
  이유: 쿠버네티스에서 아무리 준비를 잘해서 IAM Role을 요청해도, 정작 AWS 쪽 문지기(IAM)가 "너한테는 이 역할 안 빌려줄 건데?" 하고 거절하면 실패합니다.
  IRSA 사용 시: 클러스터의 OIDC Provider URL이 맞게 적혀 있는지 확인해야 합니다.
  EKS Pod Identity 사용 시: pods.eks.amazonaws.com이라는 서비스 주체가 이 Role을 Assume할 수 있도록 허락되어 있는지 확인해야 합니다.

Cluster Health Issue Code

구분	설명
SUBNET_NOT_FOUND	클러스터 서브넷이 삭제됨(신규 서브넷 연결 필요)
SECURITY_GROUP_NOT_FOUND	클러스터 보안그룹이 삭제됨(보안 그룹 재생성)
IP_NOT_AVAILABLE	서브넷에 할당된 IP 부족, 서브넷 추가/확장 필요
VPC_NOT_FOUND	클러스터가 속한 VPC가 삭제됨 - 복구 불가
ASSUME_ROLE_ACCESS_DENIED	클러스터에서 할당한 IAM Role 권한 문제 - IAM 정책 수정
KMS_KEY_DISABLED	클러스터에서 사용 중인 Secret 리소스에서 KMS 키 비활성화
KMS_KEY_NOT_FOUND	KMS 키가 삭제됨 - 복구 불가