🛠️ K8S Trouble Shooting : Persistent Volume(스토리지) 관련 오류 해결하기

 

 

Kubernetes에서 영구적인 데이터 저장을 위해 Persistent Volume(PV)과 Persistent Volume Claim(PVC)을 사용합니다.

하지만 스토리지 프로비저닝 문제, 볼륨 충돌, 마운트 실패 등의 다양한 오류가 발생할 수 있습니다.

이 글에서는 Kubernetes 환경에서 발생할 수 있는 대표적인 Persistent Volume(스토리지) 관련 오류 5가지를 정리하고, 각각의 원인과 해결 방법을 설명합니다. 🚀

 

---

 

1️⃣ “Failed to attach volume…”

 

🔎 오류 설명

 

이 오류는 볼륨을 Pod에 연결할 수 없을 때 발생합니다.

주로 스토리지 플러그인 문제, 볼륨이 이미 다른 노드에 연결된 경우, 또는 권한 문제로 인해 발생할 수 있습니다.

 

🔧 해결 방법

 

1) 볼륨 상태 확인

 

현재 클러스터에서 사용 가능한 Persistent Volume을 조회합니다.

kubectl get pv
kubectl get pvc -n <namespace>

 

2) 해당 볼륨이 다른 Pod에서 사용 중인지 확인

 

볼륨이 이미 다른 노드에 마운트되어 있으면 Pod에서 연결할 수 없습니다.

kubectl describe pvc <pvc-name> -n <namespace>

출력된 이벤트에서 already in use 메시지가 있는지 확인합니다.

 

3) 볼륨 강제 분리 후 다시 연결

 

볼륨이 제대로 해제되지 않았다면, 수동으로 분리한 후 다시 연결할 수 있습니다.

kubectl delete pod <pod-name> -n <namespace>

 

4) 노드에서 볼륨 디바이스 상태 확인

 

Kubernetes 노드에서 볼륨이 정상적으로 마운트되어 있는지 확인합니다.

lsblk
df -h

만약 디바이스가 여전히 마운트되어 있다면, 수동으로 마운트를 해제해야 할 수도 있습니다.

umount /path/to/mount

 

---

 

2️⃣ “Volume is already exclusively attached to one node and can’t be attached to another”

 

🔎 오류 설명

 

이 오류는 볼륨이 한 노드에만 연결될 수 있는 경우 발생합니다.

일반적으로 ReadWriteOnce(RWO)로 설정된 볼륨이 여러 노드에서 동시에 사용될 때 나타납니다.

 

🔧 해결 방법

 

1) 볼륨의 접근 모드 확인

 

볼륨의 접근 모드가 ReadWriteOnce인지 확인합니다.

kubectl get pvc <pvc-name> -o=jsonpath='{.spec.accessModes}'

 

2) 볼륨을 사용하는 기존 Pod 확인

 

볼륨을 점유한 Pod을 찾고 삭제할 수 있습니다.

kubectl get pods -o=wide --all-namespaces | grep <pvc-name>
kubectl delete pod <pod-name> -n <namespace>

 

3) StorageClass에서 WaitForFirstConsumer 정책 확인

 

볼륨이 자동으로 특정 노드에 바인딩되지 않도록 WaitForFirstConsumer를 설정합니다.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: my-storage-class
provisioner: kubernetes.io/aws-ebs
volumeBindingMode: WaitForFirstConsumer

 

---

 

3️⃣ “Unable to mount volumes for pod”

 

🔎 오류 설명

 

이 오류는 Kubernetes가 지정된 볼륨을 Pod에 마운트하지 못할 때 발생합니다.

일반적으로 파일 시스템 문제, 퍼미션 오류, 또는 PVC/PV 바인딩 실패가 원인입니다.

 

🔧 해결 방법

 

1) 볼륨 이벤트 확인

 

먼저, describe 명령어를 통해 PVC 및 PV 상태를 확인합니다.

kubectl describe pvc <pvc-name> -n <namespace>
kubectl describe pod <pod-name> -n <namespace>

 

2) 볼륨이 올바르게 바인딩되었는지 확인

 

PVC가 적절한 PV와 연결되었는지 확인하세요.

kubectl get pvc -o wide -n <namespace>
kubectl get pv -o wide

 

3) 퍼미션 오류 확인 및 수정

 

Pod이 볼륨을 마운트할 때 퍼미션 문제가 있는지 확인합니다.

kubectl exec -it <pod-name> -- ls -l /path/to/mount

만약 퍼미션 문제가 있다면, 다음과 같이 수정할 수 있습니다.

kubectl exec -it <pod-name> -- chmod -R 777 /path/to/mount

 

4) 파일 시스템 손상 확인

 

볼륨이 손상되었을 가능성이 있다면, fsck 명령어를 실행하여 확인할 수 있습니다.

fsck -y /dev/<volume-id>

 

---

 

4️⃣ “pod has unbound immediate PersistentVolumeClaims”

 

🔎 오류 설명

 

이 오류는 Pod이 요청한 PVC가 아직 바인딩되지 않았을 때 발생합니다.

일반적으로 StorageClass 설정 오류 또는 가용한 PV가 없을 때 나타납니다.

 

🔧 해결 방법

 

1) PVC 상태 확인

 

PVC가 어떤 상태인지 확인합니다.

kubectl get pvc -n <namespace>
kubectl describe pvc <pvc-name> -n <namespace>

 

2) 적절한 PV가 존재하는지 확인

 

PVC가 요구하는 스토리지가 PV에 존재하는지 확인합니다.

kubectl get pv

 

3) StorageClass 설정 확인

 

PVC가 StorageClass를 요구하는 경우, StorageClass가 올바르게 생성되었는지 확인합니다.

kubectl get storageclass

 

StorageClass를 생성하려면 다음 YAML을 사용할 수 있습니다.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: my-storage-class
provisioner: kubernetes.io/aws-ebs
parameters:
  type: gp2

 

---

 

5️⃣ “failed to provision volume with StorageClass…”

 

🔎 오류 설명

 

이 오류는 StorageClass를 사용하여 동적 볼륨을 프로비저닝할 때 실패할 경우 발생합니다.

일반적으로 스토리지 프로비저너 설정 문제 또는 리소스 부족이 원인입니다.

 

🔧 해결 방법

 

1) StorageClass 프로비저너 확인

 

사용 중인 StorageClass의 프로비저너가 올바르게 설정되었는지 확인합니다.

kubectl get storageclass

 

2) 해당 프로비저너가 활성화되었는지 확인

 

스토리지 프로비저너가 올바르게 실행되고 있는지 확인합니다.

kubectl get pods -n kube-system | grep provisioner

 

3) 클러스터의 노드에 올바른 스토리지 유형이 있는지 확인

 

스토리지 프로비저너가 사용할 수 있는 디스크가 존재하는지 확인합니다.

lsblk
df -h

 

4) 프로비저너의 로그 확인

 

스토리지 프로비저너 관련 로그를 확인합니다.

kubectl logs -n kube-system <provisioner-pod>

 

---

 

🎯 마무리

 

이 글에서는 Kubernetes에서 자주 발생하는 Persistent Volume(스토리지) 관련 오류 5가지와 그 해결 방법을 다뤘습니다.

 

✔️ 볼륨 연결 실패 (Failed to attach volume)

✔️ 볼륨 충돌 문제 (Volume is already exclusively attached to one node)

✔️ 볼륨 마운트 실패 (Unable to mount volumes for pod)

✔️ PVC 바인딩 문제 (pod has unbound immediate PersistentVolumeClaims)

✔️ StorageClass 프로비저닝 오류 (failed to provision volume with StorageClass)

 

만약 위 해결 방법으로도 문제가 해결되지 않는다면,

kubectl describe pvc, kubectl get storageclass, kubectl logs -n kube-system 명령어 등을 활용하여 추가로 분석해보는 것이 좋습니다.