[Troubleshooting] EKS EBS CSI Driver 설치 시 ConfigurationConflict 및 ResourceInUseException 해결

1. 문제 상황

EKS 클러스터에서 EBS CSI Driver를 설정하던 중, 크게 두 가지 단계에서 에러가 발생했습니다.

에러 1: eksctl을 이용한 IAM 서비스 계정(IRSA) 생성 실패

eksctl create iamserviceaccount \
  --name ebs-csi-controller-sa \
  --role-name AmazonEKS_EBS_CSI_DriverRole_new \
  ... --approve

• 증상: waiter state transitioned to Failure, Error: failed to create iamserviceaccount(s)
• 원인: --role-name에 지정한 이름(AmazonEKS_EBS_CSI_DriverRole_new)의 IAM 역할이 이미 AWS 계정에 존재하기 때문입니다. CloudFormation은 동일한 이름의 리소스를 생성하려고 할 때 충돌을 일으키며 롤백됩니다.

에러 2: EKS Addon 생성 후 CREATE_FAILED 및 업데이트 불가

• 증상: aws eks describe-addon 결과 상태가 CREATE_FAILED이며, ConfigurationConflict 메시지 출력. 이를 해결하기 위해 update-addon을 시도했으나 ResourceInUseException 발생.
• 원인: 이미 eksctl을 통해 생성된 ebs-csi-controller-sa가 존재하기 때문에, EKS 애드온 관리자가 해당 리소스에 대한 권한(Managed-by)을 가져오지 못해 충돌이 발생한 것입니다.

*여기서 ebs-csi-controller-sa 란

• Amazon EKS 환경에서 EBS(블록 스토리지) 볼륨의 생명주기를 관리하는 ebs-csi-controller 파드에 IAM 권한을 부여하기 위해 사용하는 쿠버네티스 ServiceAccount

• AWS IAM 역할(IRSA)과 연결되어, 컨트롤러가 볼륨 생성, 연결 등 AWS API 작업을 수행할 수 있도록 인증하는 핵심 요소

---

2. 원인 분석 (Deep Dive)

가설 1: 리소스 네이밍 충돌

eksctl은 CloudFormation 스택을 통해 작업을 수행합니다. --role-name 옵션을 고정하면, 해당 이름의 IAM Role이 이미 존재할 경우 스택 생성이 실패합니다. IAM Role은 전역 리소스이므로 고유한 이름을 가져야 합니다.

가설 2: 상태 관리의 교착 상태

AWS EKS 애드온의 상태 머신(State Machine)은 매우 엄격합니다.
1. ConfigurationConflict: 서비스 계정(SA)의 관리 주체가 eksctl인지 EKS 애드온인지 결정되지 않아 발생합니다.
2. ResourceInUseException: 애드온이 CREATE_FAILED 상태에 빠지면, AWS API는 이를 '불완전한 리소스'로 간주하여 update 명령을 허용하지 않습니다. 오직 delete 후 다시 create 하는 것만 허용됩니다.

---

3. 해결 방법 (Step-by-Step)

Step 1: 기존 실패 흔적 정리

가장 먼저 실패한 애드온 객체를 삭제하여 깨끗한 상태로 만듭니다.

aws eks delete-addon --cluster-name $CLUSTER_NAME --addon-name aws-ebs-csi-driver

Step 2: IAM Role 생성 확인 (또는 고유 이름 사용)

이미 Role이 존재한다면 그대로 사용하고, 새로 만든다면 반드시 기존에 없는 이름을 사용해야 합니다.

• Tip: eksctl 실행 시 --role-name을 생략하면 eksctl이 고유한 이름을 자동으로 생성해 줍니다. 만약 수동 지정이 필요하다면 버전 번호나 날짜를 붙여 중복을 피하십시오.

Step 3: OVERWRITE 옵션과 함께 애드온 재설치

이미 존재하는 ServiceAccount와의 갈등을 무시하고 EKS 애드온이 관리 권한을 강제로 가져오도록 설정합니다.

aws eks create-addon \
  --cluster-name $CLUSTER_NAME \
  --addon-name aws-ebs-csi-driver \
  --service-account-role-arn arn:aws:iam::$ACCOUNT_ID:role/고유한_IAM_역할_이름 \
  --resolve-conflicts OVERWRITE

---

4. 최종 결과 확인

aws eks describe-addon --cluster-name $CLUSTER_NAME --addon-name aws-ebs-csi-driver --query 'addon.status'
# "ACTIVE" 확인 시 성공

5. 핵심 요약 (Lessons Learned)

1. IAM Role Name: 자동화 도구(eksctl, terraform) 사용 시 리소스 이름 중복 여부를 반드시 체크할 것.
2. Conflict Strategy: 기존에 Kubernetes 리소스(SA 등)가 존재하는 상태에서 EKS 애드온을 추가할 때는 반드시 --resolve-conflicts OVERWRITE 옵션을 고려할 것.
3. State Recovery: EKS 애드온이 CREATE_FAILED라면 업데이트는 불가능하다. 삭제(Delete) 후 재생성이 답이다.