beautifulsoups.dev
Published on

EKS PV MountFailed - wrong fs type 해결법

Authors

서론

EKS에서 Stateful workload를 운영하다 보면 Pod 이벤트에 MountVolume.MountDevice failed 또는 MountFailed: wrong fs type, bad option, bad superblock 같은 메시지가 뜨며 컨테이너가 영원히 ContainerCreating에 머무는 경우가 있습니다. 이 에러는 “쿠버네티스가 PV를 마운트하려고 했는데 노드에서 해당 블록 디바이스/네트워크 파일시스템을 기대한 방식으로 붙이지 못했다”는 뜻입니다.

문제는 메시지가 너무 포괄적이라는 점입니다. 실제 원인은 크게 ① 파일시스템 타입 불일치(ext4/xfs 등), ② 볼륨이 포맷되지 않음(생 볼륨), ③ 노드에 필요한 유틸/커널 모듈 누락, ④ EFS/NFS 마운트 옵션/보안그룹/DNS 문제, ⑤ CSI 드라이버 설정(StorageClass fsType 등) 오류로 갈립니다. 이 글은 EBS(블록)와 EFS(네트워크)를 분리해 “어디서부터 확인해야 가장 빨리 원인을 좁힐 수 있는지”를 실전 체크리스트 형태로 정리합니다.

관련해서 EKS 운영 중 자주 만나는 다른 장애 진단 글도 함께 참고하면 좋습니다: EKS DiskPressure로 Pod Evicted 폭주 해결 10가지, EKS Pod Pending 0/XX nodes available 원인별 해결.

1) 증상 확인: 이벤트/로그에서 “무슨 마운트인지”부터 분리

먼저 이 에러가 EBS인지(EBS CSI), EFS인지(EFS CSI), 또는 in-tree 플러그인(구버전)인지부터 확인해야 합니다.

# Pod 이벤트에서 어떤 PV/PVC를 마운트하려는지 확인
kubectl describe pod <pod> -n <ns>

# PVC/PV가 어떤 CSI 드라이버를 쓰는지 확인
kubectl get pvc <pvc> -n <ns> -o yaml
kubectl get pv <pv> -o yaml
  • PV에 spec.csi.driver: ebs.csi.aws.com 이면 EBS
  • spec.csi.driver: efs.csi.aws.com 이면 EFS
  • kubernetes.io/aws-ebs 같은 값이면 구형(in-tree)일 수 있어 업그레이드/마이그레이션 이슈가 섞일 수 있습니다.

또한 노드 쪽 로그로 “커널이 어떤 에러를 냈는지”를 확인하면 빠릅니다.

# 해당 Pod가 스케줄된 노드 확인
kubectl get pod <pod> -n <ns> -o wide

# (권한이 있다면) 노드에서 kubelet 로그 확인
# Amazon Linux 2/2023, Bottlerocket 등 환경에 따라 경로/명령 상이
sudo journalctl -u kubelet -n 200 --no-pager

이제 EBS와 EFS로 나눠 해결합니다.

2) EBS(PV)에서 wrong fs type가 나는 대표 원인

EBS는 “블록 디바이스를 노드에 attach → 포맷되어 있으면 mount, 아니면 포맷 후 mount(설정에 따라)” 흐름입니다. 여기서 wrong fs type는 대체로 fsType 불일치 또는 포맷/슈퍼블록 문제로 귀결됩니다.

2.1 StorageClass/PV의 fsType 불일치(ext4 vs xfs)

가장 흔한 케이스는 볼륨은 ext4로 포맷돼 있는데 StorageClass 또는 PV에서 xfs로 마운트하려고 하거나 그 반대입니다.

확인 포인트:

kubectl get sc <storage-class> -o yaml
kubectl get pv <pv> -o yaml
  • EBS CSI에서는 parameters.fsType(StorageClass) 또는 PV의 volumeAttributes/마운트 설정(환경에 따라)을 통해 파일시스템 타입이 간접적으로 결정됩니다.
  • 운영 중 StorageClass를 변경했거나, 다른 클러스터에서 만든 볼륨을 재사용(import)했거나, 스냅샷/복구로 가져온 볼륨일 때 특히 자주 발생합니다.

해결 방법:

  1. 볼륨 실제 파일시스템을 확인 (가장 확실)
  • 노드에 직접 들어가 lsblk -f, blkid로 확인합니다.
# 노드에서 (EBS attach 후) 파일시스템 확인
lsblk -f
sudo blkid /dev/nvme1n1  # 장치명은 환경마다 다름
  1. StorageClass의 fsType을 실제와 맞춘다
  • 기존 PVC/PV가 이미 생성된 뒤에는 StorageClass만 바꿔도 즉시 반영되지 않으므로, 보통은 새 PVC로 마이그레이션하거나 PV를 재구성해야 합니다.

예: ext4로 통일하는 StorageClass

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3-ext4
provisioner: ebs.csi.aws.com
volumeBindingMode: WaitForFirstConsumer
parameters:
  type: gp3
  fsType: ext4
reclaimPolicy: Delete
allowVolumeExpansion: true

2.2 “생 볼륨”인데 포맷을 안 했거나, 포맷이 깨짐

정상적인 동적 프로비저닝이라면 CSI가 포맷까지 수행하는 경우가 많지만, 다음 상황에서는 포맷이 안 되어 있을 수 있습니다.

  • 기존 EBS 볼륨을 수동으로 PV에 붙였다(Static PV)
  • 스냅샷/복구 과정에서 파일시스템이 손상되었다
  • 암호화/키 이슈로 실제 디바이스 읽기가 비정상인데 에러가 포괄적으로 나왔다

이 경우 노드에서 file -s로 “디바이스가 어떤 타입인지”를 보면 빠릅니다.

# 노드에서 디바이스의 시그니처 확인
sudo file -s /dev/nvme1n1
# 예) Linux rev 1.0 ext4 filesystem data ...
# 예) data  (아무 시그니처 없음: 포맷 안 됨 가능성)

해결 방법(주의: 데이터 삭제 가능):

  • 데이터가 필요 없는 신규 볼륨이라면 올바른 파일시스템으로 포맷 후 마운트
# (신규 볼륨일 때만) ext4로 포맷
sudo mkfs.ext4 -F /dev/nvme1n1

# 마운트 테스트
sudo mkdir -p /mnt/test
sudo mount -t ext4 /dev/nvme1n1 /mnt/test
  • 데이터가 있는 볼륨이라면 무작정 mkfs를 하면 안 됩니다. fsck로 슈퍼블록 복구를 시도하거나 스냅샷 기반 복구 전략을 검토해야 합니다.

2.3 노드 OS에 필요한 패키지/모듈 누락(xfsprogs 등)

wrong fs type는 실제로는 “마운트에 필요한 유틸이 없다”는 의미로도 나타납니다.

  • xfs로 마운트하려는데 노드에 xfsprogs가 없다
  • 특정 AMI/커스텀 이미지에서 mount 유틸이 최소화되어 있다

확인:

# 노드에서
which mount
rpm -qa | egrep 'xfsprogs|e2fsprogs'

해결:

  • Amazon Linux 계열
sudo yum install -y xfsprogs e2fsprogs
  • Bottlerocket은 패키지 설치 모델이 다르므로(immutable) 사용 AMI/OS에 따라 EKS 최적화 AMI 사용, 또는 사용자 데이터/이미지 빌드에서 포함시켜야 합니다.

2.4 멀티 어태치/동일 볼륨 동시 마운트(특히 ReadWriteOnce)

EBS는 기본적으로 한 AZ 내에서 단일 노드에 attach되는 것이 일반적이며, PVC 접근 모드가 ReadWriteOnce인데 여러 노드에서 동시에 붙으려 하면 다양한 마운트 실패로 나타날 수 있습니다.

확인:

kubectl get pvc <pvc> -n <ns> -o jsonpath='{.spec.accessModes}'
kubectl describe pv <pv>

해결:

  • StatefulSet에서 volumeClaimTemplates를 사용해 Pod별로 PVC가 분리되도록 구성
  • 동일 PVC를 여러 Pod가 공유해야 한다면 EFS 같은 RWX 스토리지를 고려

3) EFS(PV)에서 wrong fs type가 나는 대표 원인

EFS는 NFS 기반이라 에러 메시지에 wrong fs type가 떠도 실제 원인은 대개 다음 중 하나입니다.

  • 노드에 amazon-efs-utils 또는 nfs-utils가 없어서 mount helper가 실패
  • 마운트 타겟/보안그룹/NACL 문제로 2049 포트가 막힘
  • DNS(특히 프라이빗 DNS/VPC DNS) 문제로 fs-xxxx.efs.<region>.amazonaws.com 해석 실패
  • CSI 드라이버의 mount 옵션이 환경과 충돌

3.1 노드에 EFS/NFS 유틸리티 설치 여부

확인:

# 노드에서
rpm -qa | egrep 'amazon-efs-utils|nfs-utils'

해결(일반적인 Amazon Linux):

sudo yum install -y amazon-efs-utils nfs-utils

EFS CSI 드라이버는 보통 노드에서 마운트를 수행하므로, 노드 OS에 필요한 유틸이 없으면 wrong fs type처럼 보이는 에러로 실패할 수 있습니다.

3.2 보안그룹/네트워크: 2049(TCP) 차단

EFS는 각 AZ에 마운트 타겟이 있고, 노드가 속한 서브넷/AZ에서 해당 마운트 타겟으로 2049가 열려야 합니다.

체크리스트:

  • EKS 노드 SG → EFS 마운트 타겟 SG 로 TCP 2049 허용
  • NACL에서 2049 및 ephemeral 포트 흐름이 막히지 않는지
  • 노드가 있는 AZ에 EFS 마운트 타겟이 존재하는지

노드에서 간단한 연결 테스트:

# EFS 마운트 타겟 IP로 2049 테스트 (nc가 없다면 telnet 등)
nc -vz <mount-target-ip> 2049

3.3 DNS 문제: EFS 도메인 해석 실패

노드에서:

nslookup fs-xxxx.efs.<region>.amazonaws.com

해석이 안 되면 VPC의 enableDnsSupport, enableDnsHostnames, 노드의 /etc/resolv.conf, CoreDNS 설정(클러스터 DNS 장애) 등을 의심해야 합니다.

3.4 EFS CSI StorageClass 예시(권장 구성)

EFS는 보통 Access Point를 쓰면 권한/경로/UID/GID를 표준화할 수 있어 운영이 편해집니다.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: efs-ap
provisioner: efs.csi.aws.com
parameters:
  provisioningMode: efs-ap
  fileSystemId: fs-xxxxxxxx
  directoryPerms: "700"
  gidRangeStart: "1000"
  gidRangeEnd: "2000"
reclaimPolicy: Delete
volumeBindingMode: Immediate

EFS에서 mountOptions를 과도하게 넣다가 환경에 맞지 않아 실패하는 경우가 있으니, 문제 해결 단계에서는 옵션을 최소화한 뒤 점진적으로 추가하는 편이 안전합니다.

4) 실전 트러블슈팅 순서(10분 컷 루틴)

아래 순서대로 보면 대부분 10~20분 내에 원인을 좁힐 수 있습니다.

  1. kubectl describe pod로 이벤트에서 어떤 PV/PVC인지, 에러 원문을 확보
  2. PV YAML에서 CSI 드라이버(EBS/EFS) 확인
  3. 노드 확인 후 kubelet 로그/journal에서 더 구체적인 mount 에러 확인
  4. EBS라면
    • StorageClass의 fsType 확인
    • 노드에서 lsblk -f, file -s, blkid로 실제 FS 확인
    • 필요 유틸(xfsprogs/e2fsprogs) 설치 여부 확인
  5. EFS라면
    • 노드에 amazon-efs-utils/nfs-utils 확인
    • SG/NACL에서 2049 허용 확인
    • DNS 해석 확인

운영 중 다른 원인으로 Pod가 정상처럼 보이는데 트래픽이 안 붙는 경우도 있으니, 스토리지 이슈를 해결한 뒤에는 엔드포인트/인그레스까지 함께 점검하는 습관이 좋습니다: EKS에서 Pod는 뜨는데 Service Endpoints가 0일 때.

5) 자주 쓰는 점검/수정 명령 모음

5.1 PVC/PV/SC 한 번에 보기

kubectl get pvc -n <ns>
kubectl get pv
kubectl get sc

5.2 PV가 참조하는 볼륨 핸들(EBS VolumeId/EFS fsid) 확인

kubectl get pv <pv> -o jsonpath='{.spec.csi.volumeHandle}{"\n"}'

5.3 Pod가 어느 노드에 붙었는지 확인

kubectl get pod <pod> -n <ns> -o wide

결론

MountFailed: wrong fs type는 에러 문구만 보면 막막하지만, EKS에서는 원인이 비교적 정형화되어 있습니다. EBS라면 “실제 포맷된 파일시스템과 fsType이 일치하는가, 포맷이 존재하는가, 노드 유틸이 갖춰졌는가”를 먼저 보세요. EFS라면 “노드 유틸 설치, 2049 네트워크, DNS” 3가지를 우선순위로 점검하면 됩니다.

마지막으로, 재발 방지를 위해서는 StorageClass를 환경별로 표준화(ext4 고정 등), 노드 AMI를 검증된 베이스로 통일, EFS는 Access Point 기반으로 권한 모델을 고정하는 방식이 가장 효과적입니다.

Discuss on Twitter • View on GitHub