🛠️ K8S Trouble Shooting : Helm 및 업그레이드 문제 해결하기

Helm을 사용하여 Kubernetes에서 애플리케이션을 배포하고 업그레이드할 때 다양한 오류가 발생할 수 있습니다.

이 글에서는 Kubernetes 환경에서 발생할 수 있는 대표적인 Helm 및 업그레이드 오류 4가지를 정리하고, 각각의 원인과 해결 방법을 설명합니다. 🚀

---

 

1️⃣ “Error: UPGRADE FAILED: failed to replace object: cannot patch…”

 

🔎 오류 설명

 

이 오류는 Helm 업그레이드 중 기존 리소스를 변경할 수 없을 때 발생합니다.

일반적으로 불변(immutable) 필드를 변경하려고 하거나, Kubernetes 리소스와 충돌이 발생할 때 나타납니다.

 

🔧 해결 방법

 

1) 불변 필드(Immutable Field) 변경 여부 확인

 

Kubernetes에서는 일부 필드는 변경이 불가능(immutable) 합니다.

예를 들어, **Service의 spec.clusterIP 또는 PVC의 storageClassName**을 변경할 수 없습니다.

kubectl edit svc <service-name>

변경이 불가능한 필드를 수정하려고 했다면, 대신 해당 리소스를 삭제 후 다시 생성해야 합니다.

 

2) 기존 리소스 삭제 후 Helm 재설치

 

불변 필드 문제로 인해 업그레이드가 불가능할 경우, 기존 릴리스를 삭제하고 새로 설치해야 합니다.

helm uninstall <release-name> -n <namespace>
helm install <release-name> apache-airflow/airflow -n <namespace>

3) 업그레이드 시 force 옵션 사용

 

강제로 리소스를 변경하려면 --force 옵션을 사용할 수 있습니다.

helm upgrade --install <release-name> <chart-name> --force -n <namespace>

하지만, 이 방법은 리소스를 삭제하고 다시 생성하기 때문에 주의가 필요합니다.

 

---

 

2️⃣ “operation cannot be fulfilled on…”

 

🔎 오류 설명

 

이 오류는 Helm이 변경할 수 없는 리소스에 대해 업데이트를 시도할 때 발생합니다.

일반적으로 Deployment, StatefulSet, ConfigMap 등의 리소스 충돌로 인해 나타납니다.

 

🔧 해결 방법

 

1) 현재 상태 확인

 

해당 리소스의 상태를 확인합니다.

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

 

2) 변경 불가능한 필드 확인

 

kubectl edit으로 해당 리소스를 편집하여 변경이 가능한 필드인지 확인합니다.

kubectl edit deployment <deployment-name> -n <namespace>

 

3) 기존 리소스 삭제 후 재적용

 

변경할 수 없는 필드라면, Helm 차트를 다시 삭제하고 재설치하는 것이 좋습니다.

helm uninstall <release-name> -n <namespace>
helm install <release-name> <chart-name> -n <namespace>

 

---

 

3️⃣ “operation cannot be fulfilled on persistentvolumeclaims…”

 

🔎 오류 설명

 

이 오류는 PersistentVolumeClaim(PVC)이 변경 불가능한 속성을 포함하고 있을 때 발생합니다.

특히, PVC의 storageClassName 변경이 불가능하여 문제가 발생하는 경우가 많습니다.

 

🔧 해결 방법

 

1) PVC 상태 확인

 

PVC의 상태를 확인합니다.

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

 

2) 기존 PVC 삭제 및 재생성

 

PVC의 storageClassName을 변경하려면, 기존 PVC를 삭제하고 다시 생성해야 합니다.

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

PVC 삭제 전에 데이터를 보존하려면 백업 후 다시 생성하는 것이 좋습니다.

 

3) 새로운 PVC로 마이그레이션

 

PVC의 데이터를 유지하면서 새로운 PVC로 이동하려면 새 PVC를 생성하고 기존 데이터를 복사해야 합니다.

kubectl cp <namespace>/<pod-name>:/path/to/data /local/path
kubectl delete pvc <pvc-name> -n <namespace>
kubectl apply -f new-pvc.yaml
kubectl cp /local/path <namespace>/<pod-name>:/path/to/data

 

---

 

4️⃣ “operation cannot be fulfilled on…”

 

🔎 오류 설명

 

이 오류는 다른 컨트롤러(Controller)가 특정 리소스를 점유하고 있어 변경이 불가능할 때 발생합니다.

예를 들어, Finalizers 또는 다른 컨트롤러가 리소스를 관리 중일 때 나타납니다.

 

🔧 해결 방법

 

1) Finalizer 확인 및 제거

 

Finalizer가 설정되어 삭제가 불가능할 경우, 이를 제거해야 합니다.

kubectl get <resource> <resource-name> -o=jsonpath='{.metadata.finalizers}' -n <namespace>

 

Finalizer를 삭제하려면 다음 명령을 실행합니다.

kubectl patch <resource> <resource-name> -p '{"metadata":{"finalizers":[]}}' --type=merge -n <namespace>

 

2) 리소스 강제 삭제

 

리소스가 삭제되지 않는다면 강제 삭제를 시도할 수 있습니다.

kubectl delete <resource> <resource-name> --grace-period=0 --force -n <namespace>

 

3) 컨트롤러 충돌 확인

 

다른 컨트롤러가 리소스를 점유하고 있는지 확인하고, 필요하다면 해당 컨트롤러를 삭제하거나 조정해야 합니다.

kubectl get events -n <namespace>

 

---

 

🎯 마무리

 

이 글에서는 Kubernetes에서 자주 발생하는 Helm 및 업그레이드 관련 오류 4가지와 그 해결 방법을 다뤘습니다.

 

✔️ Helm 업그레이드 실패 오류

✔️ 불변 필드(immutable field) 변경 불가 오류

✔️ PVC(PersistentVolumeClaim) 관련 충돌

✔️ Finalizer 및 컨트롤러 충돌 문제

 

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

kubectl describe, kubectl edit, helm uninstall/install 명령어 등을 활용하여 추가로 분석해보는 것이 좋습니다.